Update MKit to v0.0.24

utils/mkit/include/build.sh

@@ -1,16 +1,18 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/ini.sh"   || die "cannot import ini.sh"
-. "$MKIT_DIR/include/facts.sh" || die "cannot import facts.sh"
+mkit_import ini
+mkit_import facts
 
 
 _build1() {
     #
-    # Process one skeleton
+    # Process one skeleton $1 of type $3 (or guessed) to path $2
     #
-    local srcpath="$1"
-    local dstpath="$2"
-    local ftype="$3"
+    local srcpath=$1    # skeleton path
+    local dstpath=$2    # destination meaty animal path
+    local ftype=$3      # file/builder type
     test -n "$dstpath"  || dstpath=${srcpath%.skel}
     test -n "$ftype"    || ftype=$(_guess_ftype "$dstpath")
     debug_var srcpath dstpath ftype
@@ -21,13 +23,14 @@ _build1() {
 
 _build1_ftype() {
     #
-    # Build a file of type $1
+    # Build a file of type $1; fom stdin to stdout
     #
-    local ftype="$1"
+    local ftype=$1      # file/builder type
     case $ftype in
         MKIT_COMMON)    _expand_tokens "tokens" ;;
         markdown)       _expand_includes | _expand_tokens "tokens" ;;
         rpmstuff)       _expand_tokens "tokens" "rpmstuff:tokens" ;;
+        debstuff)       _expand_tokens "tokens" "debstuff:tokens" ;;
         *)              die "unknown file type: $ftype" ;;
     esac
 }
@@ -59,17 +62,18 @@ _expand_includes() {
 
 _expand_tokens() {
     #
-    # Expand tokens from sections $@
+    # Read stdin, expanding tokens from sections $@
     #
-    local script=$(mktemp --tmpdir mkit-tmp.XXXXXXXXXX)
-    local section varname varvalue
+    local script        # sed script cache
+    local section       # each section to expand tokens from
+    local varname       # each token name
+    local varvalue      # each token value
+    script=$(mktemp --tmpdir mkit-tmp.XXXXXXXXXX)
     {
-        for section in "$@";
-        do
+        for section in "$@"; do
             debug_var section
             ini lskeys "$section" \
-              | while read varname;
-                do
+              | while read -r varname; do
                     varvalue="$(ini 1value "$section:$varname" | _qfs )"
                     echo "s|$varname|$varvalue|g;"
                     debug_var varname varvalue
@@ -77,6 +81,7 @@ _expand_tokens() {
         done
         echo "s|__MKIT_PROJ_NAME__|$(ini 1value project:name | _qfs)|g;"
         echo "s|__MKIT_PROJ_CODENAME__|$(ini 1value project:codename | _qfs)|g;"
+        echo "s|__MKIT_PROJ_LICENSE__|$(ini 1value project:license | _qfs)|g;"
         echo "s|__MKIT_PROJ_PKGNAME__|$(ini 1value project:pkgname | _qfs)|g;"
         echo "s|__MKIT_PROJ_TAGLINE__|$(ini 1value project:tagline | _qfs)|g;"
         echo "s|__MKIT_PROJ_MAINTAINER__|$(ini 1value project:maintainer | _qfs)|g;"
@@ -93,7 +98,7 @@ _guess_ftype() {
     #
     # Guess file type from destination path $1
     #
-    local dstpath="$1"
+    local dstpath=$1    # destination path
     case $dstpath in
         *.md) echo markdown    ;;
         *)    echo MKIT_COMMON ;;
@@ -114,21 +119,22 @@ build() {
     #
     # Add meat to all skeletons
     #
-    local srcpath
+    local srcpath   # each source path
     find -type f -name '*.skel' \
-     | while read srcpath;
-       do
+     | while read -r srcpath; do
            _build1 "$srcpath"
        done
 }
 
 build_manpages() {
-    local manfile mdfile
-    if command -v ronn >/dev/null;
-    then
+    #
+    # Build manpages using ronn
+    #
+    local manfile   # each manual file listed in '[files:man]'
+    local mdfile    # each source markdown file
+    if command -v ronn >/dev/null; then
         ini lskeys "files:man" \
-          | while read manfile;
-            do
+          | while read -r manfile; do
                 mdfile="$manfile.md"
                 ronn -r "$mdfile"
                 mkdir -p "$MKIT_LOCAL"
@@ -157,7 +163,11 @@ debstuff() {
     #
     # Build Debian stuff (eamed tarball, debian dir)
     #
-    local version="$(semver)"
+    local version       # package version
+    local debian_skel   # 'debian' folder skeleton
+    local dfsrc         # each source file from ^^
+    local dftgt         # each built packaging file
+    version=$(semver)
 
     # tarball - we should already have by means of 'dist'
     #
@@ -168,17 +178,15 @@ debstuff() {
 
     # read content of each mandatory file from debian_skel
     #
-    local debian_skel=$(ini 1value dist:debstuff)
+    debian_skel=$(ini 1value dist:debstuff)
     test -n "$debian_skel" || die "dist:debstuff not specified"
     test -d "$debian_skel" || die "debian directory template found: $debian_skel"
     mkdir -p debian/source
-    local dfsrc dftgt
     find "$debian_skel" -type f \
-      | while read dfsrc;
-        do
+      | while read -r dfsrc; do
             dftgt="debian/${dfsrc#$debian_skel}"
             mkdir -p "$(dirname "$dftgt")"
-            _build1 "$dfsrc" "$dftgt"
+            _build1 "$dfsrc" "$dftgt" debstuff
         done
     echo debian >> "$MKIT_LOCAL/built.lst"
 }
@@ -190,9 +198,12 @@ dist() {
     #FIXME: lacking Makefile skills, we do this step twice fot
     #       rpmstuff, hence -f hack for gzip
     #
-    local version=$(semver)
-    local git_lasthash=$(git_lasthash)
-    local dirname=$MKIT_PROJ_PKGNAME-$version
+    local version           # tarball version
+    local git_lasthash      # last git commit hash
+    local dirname           # directory and tarball name
+    version=$(semver)
+    dirname=$MKIT_PROJ_PKGNAME-$version
+    git_lasthash=$(git_lasthash)
     mkdir -p "$dirname"
     ini values "dist:tarball" | xargs -I DIST_ITEM cp -R DIST_ITEM "$dirname"
     update_version "$version" "$dirname/mkit.ini"
@@ -209,9 +220,10 @@ rpmstuff() {
     #
     # Build specfile
     #
-    local specname="$MKIT_PROJ_PKGNAME.spec"
-    local specsrc="$(ini 1value "dist:rpmstuff")"
+    local specname=$MKIT_PROJ_PKGNAME.spec      # .spec filename
+    local specsrc                               # source of specfile
+    specsrc="$(ini 1value "dist:rpmstuff")"
     test -n "$specsrc" || die "dist:rpmstuff not specified"
     test -f "$specsrc" || die "specfile template not found: $specsrc"
-    _build1 "$specsrc" "$specname"
+    _build1 "$specsrc" "$specname" rpmstuff
 }

utils/mkit/include/deploy.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
 
 _deploy_item() {
     #
@@ -23,17 +27,17 @@ _deploy_item() {
     # Directories are copied recursively, and mode is
     # applied only to files.
     #
-    local src="$1"
-    local dst="$2"
-    local mode="${3:-$MKIT_DEFAULT_MODE}"
-    if test -d "$src";
-    then
-        _maybe mkdir -vp "$(dirname "$dst")"
-        _maybe cp -Tvr "$src" "$dst"
-        find "$dst" -type f \
-          | while read chmod_item;
-            do
-                _maybe chmod "$mode" "$chmod_item"
+    local src=$1                            # source path
+    local dst=$2                            # destination path
+    local mode=${3:-$MKIT_DEFAULT_MODE}     # mode
+    local item                              # each in directory
+    if test -d "$src"; then
+        find "$src" -type f \
+          | while read -r item; do
+                [[ $item =~ .skel$ ]] \
+                 && grep -q "${item%.skel}" "$MKIT_LOCAL/built.lst" \
+                 && continue
+                _deploy_item "$item" "$dst${item#$src}" "$mode"
             done
     else
         _maybe install -DTvm "$mode" "$src" "$dst"
@@ -44,9 +48,9 @@ _get_dst() {
     #
     # Find out target path for src file $2 of group $1
     #
-    local grp=$1
-    local src=$2
-    local dst=$3
+    local grp=$1        # deploy group
+    local src=$2        # each source
+    local dst=$3        # alternative destination name
     test -n "$dst" || dst=${src##*/}
     echo "$(_get_root "$grp")/$dst"
 }
@@ -55,9 +59,11 @@ _get_root() {
     #
     # Find out target root for group $1
     #
-    local grp="$1"
-    local root=$(ini 1value "roots:$grp")
-    local destdir=$(ini 1value ENV:DESTDIR)
+    local grp=$1        # deploy group
+    local root          # root for this group
+    local destdir       # value of DESTDIR
+    root=$(ini 1value "roots:$grp")
+    destdir=$(ini 1value ENV:DESTDIR)
     destdir=${destdir%/}
     case $destdir:$root in
         *:)     die "missing in config.ini: roots:$grp" ;;
@@ -84,16 +90,17 @@ install() {
     #
     # Install product
     #
-    local dst group mode src
+    local group     # each deploy group
+    local mode      # mode (group-specific)
+    local src       # each source path
+    local dst       # each (final absolute) destination path
     ini lskeys "files" \
       | sort \
       | uniq \
-      | while read group;
-        do
+      | while read -r group; do
             mode=$(ini 1value "modes:$group")
             ini values "files:$group" \
-              | while read src dst;
-                do
+              | while read -r src dst; do
                     dst=$(_get_dst "$group" "$src" "$dst")
                     _deploy_item "$src" "$dst" "$mode"
                 done
@@ -106,15 +113,15 @@ uninstall() {
     #
     # Uninstall product
     #
-    local dst group src
+    local group     # each deploy group
+    local src       # each source path
+    local dst       # each (final absolute) destination path
     ini lskeys "files" \
       | sort \
       | uniq \
-      | while read group;
-        do
+      | while read -r group; do
             ini values "files:$group" \
-              | while read src dst;
-                do
+              | while read -r src dst; do
                     dst=$(_get_dst "$group" "$src" "$dst")
                     _maybe rm -vrf "$dst"
                 done

utils/mkit/include/facts.sh

@@ -1,12 +1,14 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/ini.sh" || die "cannot import ini.sh"
+mkit_import ini
 
 git_bool() {
     #
     # Get git bool (ie. exit status counts) $1
     #
-    local bool_name="$1"
+    local bool_name=$1      # name of boolean to get
     git_present || warn "can't give bool outside git repo: $bool_name"
     case "$bool_name" in
         dirty_files)
@@ -29,7 +31,7 @@ git_fact() {
     #
     # Get git fact $1
     #
-    local fact_name="$1"
+    local fact_name=$1      # name of fact to get
     git_present || warn "can't give fact outside git repo: $fact_name"
     case "$fact_name" in
         latest_tag)
@@ -88,9 +90,9 @@ git_lasthash() {
     # work if you got outside the git repo in other way than dist
     # target, but that's actually expected.)
     #
-    if git_present;
-    then    # we are in git repo
-        local last_hash=$(git rev-parse HEAD)
+    local last_hash     # last commit hash
+    if git_present; then    # we are in git repo
+        last_hash=$(git rev-parse HEAD)
         echo -n "$last_hash"
         git_bool dirty && echo -n ".dirty"
     else    # we are outside (eg. distributor's build dir')
@@ -146,18 +148,23 @@ semver() {
     # FIXME:  Using project:prerl for release IDs may not be compatible with
     #         release strategy implemented in release.sh
     #
-    local version=$(ini 1value project:version)
-    local prerl=$(ini 1value project:prerl)
-    grep ":" <<<"$prerl" && warn "colon in project:prerl may corrupt version data: $prerl"
+    local version       # version string (final result)
+    local prerl         # pre-release keyword (from mkit.ini, eg. 'alpha')
+    local latest_tag    # latest git tag
+    local commit        # commit indicator (CURRENT_BRANCH.gHASH)
+    local dirty         # 0 if dirty, 1 if clean
+    local suffix        # version suffix
+    version=$(ini 1value project:version)
+    prerl=$(ini 1value project:prerl)
+    grep ":" <<<"$prerl" \
+     && warn "colon in project:prerl may corrupt version data: $prerl"
     if git_present;
     then    # we are in git repo... so we can get smart
-        local latest_tag=$(git_fact latest_tag)
+        latest_tag=$(git_fact latest_tag)
         if ! git describe --tags --exact-match HEAD >&/dev/null;
         then    # we are at a later commit than the last tag
-            local commit="$(git_fact current_branch).g$(git_fact latest_sha)"
+            commit="$(git_fact current_branch).g$(git_fact latest_sha)"
         fi
-        local dirty=""
-        local suffix=""
         git_bool dirty; dirty=$?
         test -n "$latest_tag" && version=${latest_tag:1}
         case "$dirty:$commit" in
@@ -165,7 +172,7 @@ semver() {
             0:)  suffix="+dirty"         ;;
             1:*) suffix="+$commit"       ;;
             0:*) suffix="+$commit.dirty" ;;
-            *)   suffix=MKIT_BUG;
+            *)   suffix=MKIT_BUG
                  warn "MKIT_BUG: bad dirt/commit detection" ;;
         esac
         test -n "$prerl" && suffix="-$prerl$suffix"

utils/mkit/include/ini.sh

@@ -1,11 +1,13 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
 _ini_cat() {
     #
     # A no-op for text stream
     #
-    while read line;
-    do
+    local line      # each line
+    while read -r line; do
         printf -- "%s\n" "$line"
     done
 }
@@ -14,9 +16,11 @@ _ini_expand() {
     #
     # Expand reference value (prefix only)
     #
-    local line suffix ref value
-    while read line;                        # [foo:bar]/path
-    do
+    local line      # each input line
+    local suffix    # tail of the line
+    local ref       # reference
+    local value     # value if reference
+    while read -r line; do                  # [foo:bar]/path
         suffix="${line#\[*\]}"              # /path
         ref="${line%$suffix}"               # [foo:bar]
         ref="${ref%\]}"                     # [foo:bar
@@ -30,7 +34,7 @@ _ini_grepkey() {
     #
     # Read key from a section
     #
-    local wnt=$1
+    local wnt=$1    # wanted key
     grep '.' \
       | grep -v '\s*#' \
       | sed -e 's/ *= */=/; s/ +$//; s/^//;' \
@@ -48,17 +52,15 @@ _ini_greppath() {
     #     [files:share]
     #         my/lib.sh   = proj/my/lib.sh
     #
-    local wnt="$1"
-    local wntkey="${wnt##*:}"
-    local wntsec="${wnt%:$wntkey}"
-    if test "$wntsec" = 'ENV';
-    then
-        local override="${!wntkey}"
-        if test -n "$override";
-        then
-            echo "$override"
-            return
-        fi
+    local wnt=$1                    # wanted path
+    local wntkey=${wnt##*:}         # ^^ key part
+    local wntsec=${wnt%:$wntkey}    # ^^ section part
+    local override                  # ENV override (only ENV section)
+    if test "$wntsec" = 'ENV'; then
+        override=${!wntkey}
+        test -n "$override" \
+         && echo "$override" \
+         && return
     fi
     _ini_grepsec "$wntsec" | _ini_grepkey "$wntkey"
 }
@@ -67,12 +69,12 @@ _ini_grepsec() {
     #
     # Read one INI section
     #
-    local wnt="$1"
-    local ok=false
+    local wnt=$1        # wanted section name
+    local ok=false      # are we in the section?
+    local line          # each input line
     grep '.' \
       | grep -v '\s*#' \
-      | while read line;
-        do
+      | while read -r line; do
             case "$line" in
                 \[$wnt\]) ok=true;  continue ;;
                 \[*\])    ok=false; continue ;;
@@ -87,16 +89,15 @@ _ini_lskeys() {
     #
     # List keys from a section
     #
-    local sct="$1"
-    _ini_grepsec "$sct" | cut -d= -f1 | sort | uniq
+    local sct=$1    # section of interest
+    _ini_grepsec "$sct" | cut -d= -f1 | awk '!x[$0]++'
 }
 
 _ini_maybe_expand() {
     #
     # Decide whether or not to expand
     #
-    if test "$MKIT_INI_EXPAND" -gt 0;
-    then
+    if test "$MKIT_INI_EXPAND" -gt 0; then
         MKIT_INI_EXPAND=$(( --MKIT_INI_EXPAND )) _ini_expand
     else
         _ini_cat
@@ -107,10 +108,10 @@ ini() {
     #
     # do ini operation
     #
-    local op=$1
-    local arg=$2
-    local fn
-    local limit=_ini_cat
+    local op=$1             # operator
+    local arg=$2            # argument
+    local fn                # internal function implementing $op
+    local limit=_ini_cat    # limiting internal function
     case $op in
         lskeys) fn=_ini_lskeys   ;;
         sec)    fn=_ini_grepsec  ;;
@@ -125,9 +126,10 @@ update_version() {
     #
     # Change project.version in mkit.ini at path $2 to version $1
     #
-    local version="$1"
-    local inifile="$2"
-    local tmp=$(mktemp -t mkit.update_version.XXXXXXXX)
+    local version=$1    # new version
+    local inifile=$2    # mkit.ini path
+    local tmp           # mkit.ini cache
+    tmp=$(mktemp -t mkit.update_version.XXXXXXXX)
     <"$inifile" perl -e '
         my $hit = 0;
         my $done = 0;

utils/mkit/include/mkit.sh

@@ -1,9 +1,34 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/build.sh"  || die "cannot import build.sh"
-. "$MKIT_DIR/include/deploy.sh" || die "cannot import deploy.sh"
-. "$MKIT_DIR/include/release.sh" || die "cannot import release.sh"
-. "$MKIT_DIR/include/ini.sh"    || die "cannot import ini.sh"
+die() {
+    #
+    # Exit with message and non-zero exit status
+    #
+    echo "fatal: $*" >&2
+    exit 4
+}
+
+mkit_import() {
+    #
+    # Import mkit module $1.sh
+    #
+    # Check for module, source it and die with reasonable message if needed.
+    #
+    local modname=$1
+    local modpath
+    modpath="$MKIT_DIR/include/$modname.sh"
+    test -f "$modpath" || die "no such module: $modpath"
+    bash -n "$modpath" || die "bad syntax: $modpath"
+    #shellcheck disable=SC1090
+    . "$modpath" || die "failed to import: $modname"
+}
+
+mkit_import build
+mkit_import deploy
+mkit_import release
+mkit_import ini
 
 _valid_targets() {
     #
@@ -15,11 +40,13 @@ _valid_targets() {
     echo debstuff
     echo dist
     echo install
+    echo release
     echo release_x
     echo release_y
     echo release_z
     echo rpmstuff
     echo uninstall
+    echo vbump
     echo vbump_x
     echo vbump_y
     echo vbump_z
@@ -38,9 +65,8 @@ debug_var() {
     # Print debug message
     #
     $MKIT_DEBUG || return 0
-    local __mkit_debug_var_name__
-    for __mkit_debug_var_name__ in "$@";
-    do
+    local __mkit_debug_var_name__       # variable name to debug
+    for __mkit_debug_var_name__ in "$@"; do
         {
             echo -n "MKIT_DEBUG: ${FUNCNAME[1]}():"
             echo -n " $__mkit_debug_var_name__"
@@ -50,14 +76,6 @@ debug_var() {
     done
 }
 
-die() {
-    #
-    # Exit with message and non-zero exit status
-    #
-    echo "fatal: $*" >&2
-    exit 4
-}
-
 _compver() {
     #
     # True if version $1 matches our version
@@ -65,8 +83,11 @@ _compver() {
     # If our x is 0, check first two fragments, otherwise check just
     # the x.  Fragments must equal.
     #
-    local their_ver our_x our_y their_x their_y
-    their_ver="$1"
+    local their_ver=$1      # their version
+    local our_x             # our X
+    local our_y             # our Y
+    local their_x           # their X
+    local their_y           # their Y
     their_x=${their_ver%%.*}
     their_y=${their_ver##$their_x.}
     their_y=${their_y%%.*}
@@ -89,12 +110,12 @@ _chkiniversion() {
     # Look for "#mkit version=0.0.0" or similar in first or last
     # 3 lines of the file; then check if the version is supported.
     #
-    local ver_line
-    local their_ver
+    local ver_line      # line declaring version
+    local their_ver     # the declared version
     ver_line=$(
         {
             head -3 "$MKIT_INI"
-            tac "$MKIT_INI" | tail -3
+            tail -3 "$MKIT_INI"
         } | grep -m 1 -E '^# *mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
     )
     test -n "$ver_line" \
@@ -122,8 +143,7 @@ route() {
     #
     # Call correct function based on $1
     #
-    if _valid_targets | grep -qwx "^$1";
-    then
+    if _valid_targets | grep -qwx "^$1"; then
         "$1"
     else
         {

utils/mkit/include/release.sh

@@ -1,20 +1,26 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/ini.sh"   || die "cannot import ini.sh"
-. "$MKIT_DIR/include/facts.sh" || die "cannot import facts.sh"
+mkit_import ini
+mkit_import facts
 
 _bump_version() {
     #
     # Bump version on stdin by level $1 (x, y or z)
     #
-    local rlevel=$1
-    local old
+    local rlevel=$1     # release level
+    local old           # old version
+    local oldx          # ... X
+    local oldz          # ... Z
+    local oldy          # ... Y
+    local tmpy          # Y parsing cache
+    local new           # bumped version
     read -r old
-    local oldx=${old%.*.*}
-    local oldz=${old#*.*.}
-    local tmpy=${old%.*}
-    local oldy=${tmpy#*.}
-    local new=""
+    oldx=${old%.*.*}
+    oldz=${old#*.*.}
+    tmpy=${old%.*}
+    oldy=${tmpy#*.}
     case $rlevel in
         x) new="$((oldx+MKIT_BUMPSIZE)).0.0"            ;;
         y) new="$oldx.$((oldy+MKIT_BUMPSIZE)).0"        ;;
@@ -28,23 +34,23 @@ _relck() {
     #
     # Die if blocking condition $1 is detected
     #
-    local condition="$1"
-    local x
+    local condition=$1      # condition name
+    local oracle            # expected value
     case "$condition" in
         git_present)
             git rev-parse HEAD >&/dev/null\
              || die "cannot do this outside git repo"
             ;;
         at_relsrc)
-            local relsrc=$(ini 1value project:relsrc)
+            oracle=$(ini 1value project:relsrc)
             git_fact current_branch \
-              | grep -qFx "$relsrc" \
-             || die "you are not on release source branch: $relsrc"
+              | grep -qFx "$oracle" \
+             || die "you are not on release source branch: $oracle"
             ;;
         not_dirty)
             git diff --shortstat 2>/dev/null \
               | grep -q . \
-             && die "tree is dirty: $dirt"
+             && die "tree is dirty!"
             ;;
         tags_ok)
             git_fact latest_tag \
@@ -62,7 +68,7 @@ _relck() {
              && die "WIP commit since $(git_fact latest_tag)"
             ;;
         ini_version)
-            local oracle=$(git_fact latest_version | _bump_version "$rlevel")
+            oracle=$(git_fact latest_version | _bump_version "$rlevel")
             ini 1value project:version  \
               | grep -qFx "$oracle" \
              || die "new version not in mkit.ini: $oracle"
@@ -83,9 +89,10 @@ _release() {
     # FIXME: Using project:prerl as build.sh:semver() does may not be
     #        compatible with this release strategy
     #
-    local rlevel=$1
-    local newtag
-    local reldst
+    local rlevel=$1     # release level (x, y or z)
+    local newtag        # new tag
+    local relsrc        # release source branch (if any)
+    local reldst        # release destination branch (if any)
 
     _relck git_present
     _relck at_relsrc
@@ -101,10 +108,10 @@ _release() {
     $MKIT_DRY && return
     git tag -m "$(_release_msg)" "$newtag"
 
+    relsrc=$(ini 1value project:relsrc)
     reldst=$(ini 1value project:reldst)
-    debug_var reldst
-    if test -n "$reldst";
-    then
+    debug_var relsrc reldst
+    if test -n "$reldst" && test "$reldst" != "$relsrc"; then
         git branch -f "$reldst" "$newtag"
     fi
 }
@@ -127,8 +134,14 @@ _release_msg() {
 }
 
 _vbump() {
-    local rlevel="$1"
-    local nextver   # after the bump
+    #
+    # Do version bump at level $1
+    #
+    # Perform checks, compute new version, update mkit.ini and initiate
+    # 'Bump version' commit with changelog template.
+    #
+    local rlevel=$1     # bump level (x, y or z)
+    local nextver       # version after the bump
     _relck git_present
     _relck at_relsrc
     _relck not_dirty
@@ -143,6 +156,9 @@ _vbump() {
 }
 
 _vbump_gitmsg() {
+    #
+    # Compose git message template for 'Bump version' commit
+    #
     echo "Bump version"
     echo ""
     echo "Overview of changes:"
@@ -155,26 +171,58 @@ _vbump_gitmsg() {
         '
 }
 
+release() {
+    #
+    # Perform release on Z level
+    #
+    _release z
+}
+
 release_x() {
+    #
+    # Perform release on X level
+    #
     _release x
 }
 
 release_y() {
+    #
+    # Perform release on Y level
+    #
     _release y
 }
 
 release_z() {
+    #
+    # Perform release on Z level
+    #
     _release z
 }
 
+vbump() {
+    #
+    # Perform version bump on Z level
+    #
+    _vbump z
+}
+
 vbump_x() {
+    #
+    # Perform version bump on X level
+    #
     _vbump x
 }
 
 vbump_y() {
+    #
+    # Perform version bump on Y level
+    #
     _vbump y
 }
 
 vbump_z() {
+    #
+    # Perform version bump on Z level
+    #
     _vbump z
 }

utils/mkit/include/vars.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+
+#
+# Bump size (for vbump_? and release_?)
+#
+MKIT_BUMPSIZE=${MKIT_BUMPSIZE:-1}
+
+#
+# Debug mode (true|false)
+#
+MKIT_DEBUG=${MKIT_DEBUG:-false}
+
+#
+# Default deploy mode for files
+#
+MKIT_DEFAULT_MODE="644"
+
+#
+# Dry mode (true|false)
+#
+# Set to true to not install anything. Implies MKIT_DEBUG.
+#
+MKIT_DRY=${MKIT_DRY:-false}
+
+#
+# Path to mkit.ini
+#
+MKIT_INI=${MKIT_INI:-mkit.ini}
+
+#
+# Limit ini expansion depth
+#
+# To avoid endless loops, this value is subtracted each
+# time ini() expands a reference; when zero is reached,
+# no more expansions happen.
+#
+MKIT_INI_EXPAND=2
+
+#
+# Path to MKit local config and temp
+#
+# Typically hidden in project root, here MKit can
+# save its temporary lists.
+#
+MKIT_LOCAL=${MKIT_LOCAL:-.mkit}
+
+#
+# Package name
+#
+# Used as base for tarball and in some default tokens.
+#
+MKIT_PROJ_PKGNAME=""
+
+#
+# This MKit version
+#
+MKIT_VERSION=0.0.24

utils/mkit/make

@@ -1,80 +1,32 @@
 #!/bin/bash
+#shellcheck disable=SC2034
 # mkit - simple install helper
 # See LICENSE file for copyright and license details.
 
-die() {
-    echo "$@" && exit 9
+init_core() {
+    #
+    # Load core module (or die)
+    #
+    #shellcheck disable=SC1090
+    . "$MKIT_DIR/include/mkit.sh" \
+     && . "$MKIT_DIR/include/vars.sh" \
+     && return 0
+    echo "failed to load core; check if MKIT_DIR is set properly: $MKIT_DIR" >&2
+    exit 9
 }
 
-
-#
-# Bump size (for vbump_? and release_?)
-#
-MKIT_BUMPSIZE=${MKIT_BUMPSIZE:-1}
-
-#
-# Debug mode (true|false)
-#
-MKIT_DEBUG=${MKIT_DEBUG:-false}
-
-#
-# Default deploy mode for files
-#
-MKIT_DEFAULT_MODE="644"
-
 #
 # Path to MKit dir (where 'include' is)
 #
 MKIT_DIR=${MKIT_DIR:-$(dirname "$0")}
 
-#
-# Dry mode (true|false)
-#
-# Set to true to not install anything. Implies MKIT_DEBUG.
-#
-MKIT_DRY=${MKIT_DRY:-false}
-
-#
-# Path to mkit.ini
-#
-MKIT_INI=${MKIT_INI:-mkit.ini}
-
-#
-# Limit ini expansion depth
-#
-# To avoid endless loops, this value is subtracted each
-# time ini() expands a reference; when zero is reached,
-# no more expansions happen.
-#
-MKIT_INI_EXPAND=2
-
-#
-# Path to MKit local config and temp
-#
-# Typically hidden in project root, here MKit can
-# save its temporary lists.
-#
-MKIT_LOCAL=${MKIT_LOCAL:-.mkit}
-
-#
-# Package name
-#
-# Used as base for tarball and in some default tokens.
-#
-MKIT_PROJ_PKGNAME=""
-
-#
-# This MKit version
-#
-MKIT_VERSION=0.0.18
-
 
-. "$MKIT_DIR/include/mkit.sh" || die "failed to init; check if MKIT_DIR is set properly: $MKIT_DIR"
+init_core
 
 case "$1" in
-    --version-semver) echo "$MKIT_VERSION"; exit 0 ;;
-    --version)        echo "Mkit (Simple Makefile target helper) $MKIT_VERSION"
-                      exit 0 ;;
+    -V|--version-semver)    echo "$MKIT_VERSION"; exit 0 ;;
+    --version)              echo "Mkit (Simple Makefile target helper) $MKIT_VERSION"
+                            exit 0 ;;
 esac
 
 mkit_init

utils/mkit/mkit.mk

@@ -26,6 +26,9 @@ rpmstuff: dist
 install: all
 	@$(MKIT_DIR)/make install
 
+release:
+	@$(MKIT_DIR)/make release
+
 release_x:
 	@$(MKIT_DIR)/make release_x
 
@@ -38,6 +41,9 @@ release_z:
 uninstall:
 	@$(MKIT_DIR)/make uninstall
 
+vbump:
+	@$(MKIT_DIR)/make vbump
+
 vbump_x:
 	@$(MKIT_DIR)/make vbump_x
 
@@ -47,4 +53,4 @@ vbump_y:
 vbump_z:
 	@$(MKIT_DIR)/make vbump_z
 
-.PHONY: all clean dist rpmstuff install uninstall release_x release_y release_z vbump_x vbump_y vbump_z
+.PHONY: all clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z

utils/mkit/stub

@@ -0,0 +1,698 @@
+#!/bin/bash
+# mkit - simple install helper
+# See LICENSE file for copyright and license details.
+
+init_core() {
+    #
+    # Load core modules (or die)
+    #
+    #shellcheck disable=SC1090
+    . "$MKIT_DIR/include/mkit.sh" \
+     && . "$MKIT_DIR/include/vars.sh" \
+     && return 0
+    echo "failed to load core; check if MKIT_DIR is set properly: $MKIT_DIR" >&2
+    exit 9
+}
+
+#
+# Path to MKit dir (where 'include' is)
+#
+MKIT_DIR=${MKIT_DIR:-$(dirname "$0")}
+
+init_core
+
+mkit_import ini
+
+declare -A MKIT_STUB_LICENSES
+MKIT_STUB_LICENSES[GPLv1]="http://www.gnu.org/licenses/old-licenses/gpl-1.0.md"
+MKIT_STUB_LICENSES[GPLv2]="http://www.gnu.org/licenses/old-licenses/gpl-2.0.md"
+MKIT_STUB_LICENSES[GPLv3]="http://www.gnu.org/licenses/gpl-3.0.md"
+MKIT_STUB_LICENSES[LGPLv2]="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.md"
+MKIT_STUB_LICENSES[LGPLv3]="http://www.gnu.org/licenses/lgpl-3.0.md"
+MKIT_STUB_LICENSES[AGPLv3]="http://www.gnu.org/licenses/agpl-3.0.md"
+MKIT_STUB_LICENSES[FDLv1.3]="http://www.gnu.org/licenses/fdl-1.3.md"
+MKIT_STUB_LICENSES[FDLv1.2]="http://www.gnu.org/licenses/old-licenses/fdl-1.2.md"
+MKIT_STUB_LICENSES[FDLv1.1]="http://www.gnu.org/licenses/old-licenses/fdl-1.1.md"
+
+
+deploy() {
+    local file=$1       # which known file?
+    local any_name=${NiceName:-$PackageName}
+    local tmp
+    tmp=$(mktemp -t mkit.stub.deploy.XXXXXXX)
+    mkdir -p "$(dirname "$file")"
+    case $file in
+
+        Makefile)
+            echo -n "# $any_name"
+            test -n "$Tagline" && echo -n " - $Tagline"
+            echo
+            $MkLicense && echo '# See LICENSE.md file for copyright and license details.'
+            echo ''
+            echo 'MKIT_DIR=utils/mkit'
+            #shellcheck disable=SC2016
+            echo 'include $(MKIT_DIR)/mkit.mk'
+            ;;
+
+        README.md)
+            echo "$any_name"
+            tr -c '=\n' '=' <<<"$any_name"
+            echo ''
+            echo ''
+            if test -n "$Tagline"; then
+                echo "$Tagline"
+            else
+                echo "(Nothing to say about this project.)"
+            fi
+            ;;
+
+        */mkit.ini|mkit.ini)
+            echo "[project]"
+            echo "    version     = $Version"
+            test -n "$Codename"     && echo "    codename    = $Codename"
+            test -n "$NiceName"     && echo "    name        = $NiceName"
+            test -n "$Tagline"      && echo "    tagline     = $Tagline"
+            test -n "$PackageName"  && echo "    pkgname     = $PackageName"
+            test -n "$Maintainer"   && echo "    maintainer  = $Maintainer"
+            test -n "$VcsBrowser"   && echo "    vcs_browser = $VcsBrowser"
+            test -n "$RelSrc"       && echo "    relsrc      = $RelSrc"
+            test -n "$RelDst"       && echo "    reldst      = $RelDst"
+            if updating; then
+                remake_section dist
+                remake_section ENV
+                remake_section roots
+                remake_section tokens
+                remake_section modes
+                remake_section files
+            else
+                echo ""
+                echo "[dist]"
+                $MkLicense  && echo "    tarball = LICENSE.md"
+                $MkMakefile && echo "    tarball = Makefile"
+                $MkReadme   && echo "    tarball = README.md"
+                echo "    tarball = mkit.ini"
+                $MkPackaging && echo "    tarball = packaging"
+                echo "    tarball = src"
+                echo "    tarball = tests"
+                echo "    tarball = utils"
+                $MkPackaging && echo "    rpmstuff = packaging/template.spec"
+                $MkPackaging && echo "    debstuff = packaging/debian"
+                echo ""
+                echo "[ENV]"
+                echo "    PREFIX = /usr/local"
+                echo ""
+                echo "[roots]"
+                echo "    bin     = [ENV:PREFIX]/bin"
+                echo "    doc     = [ENV:PREFIX]/share/doc/$PackageName"
+                echo ""
+                echo "[tokens]"
+                echo "    __${PackageName^^}_FOO__ = Barr.."
+                echo ""
+                echo "[modes]"
+                echo "    bin     = 755"
+                echo "    doc     = 644"
+                echo ""
+                echo "[files]"
+                echo "    bin      = src/$PackageName"
+                $MkLicense && echo "    doc      = LICENSE.md"
+                $MkReadme  && echo "    doc      = README.md"
+            fi
+            echo ""
+            echo "#mkit version=$MKIT_VERSION"
+            ;;
+
+        packaging/template.spec)
+            echo 'Name:		__MKIT_PROJ_PKGNAME__'
+            echo 'Version:	__MKIT_PROJ_VERSION__'
+            echo 'Release:	1%{?dist}'
+            echo 'Summary:	__MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
+            echo ''
+            $MkLicense && echo "License:	$License"
+            echo 'Source0:	%{name}-%{version}.tar.gz'
+            echo ''
+            echo 'BuildArch:	noarch'
+            echo 'BuildRequires:	coreutils git'
+            echo 'Requires:	MKIT_STUB_REQUIRES'
+            echo ''
+            echo '%description'
+            echo 'MKIT_STUB_DESCRIPTION'
+            echo ''
+            echo '%prep'
+            echo '%setup -q'
+            echo ''
+            echo '%build'
+            echo 'make %{?_smp_mflags} PREFIX=/usr'
+            echo ''
+            echo '%install'
+            echo '%make_install PREFIX=/usr'
+            echo ''
+            echo '%files'
+            echo 'MKIT_STUB_FILELIST'
+            echo ''
+            echo '%changelog'
+            echo ''
+            echo '# specfile built with MKit __MKIT_SELF_VERSION__'
+            ;;
+
+        packaging/debian/copyright)
+            echo ""
+            ;;
+
+        packaging/debian/control)
+            echo 'Source: __MKIT_PROJ_PKGNAME__'
+            echo 'Maintainer: __MKIT_PROJ_MAINTAINER__'
+            test -n "$VcsBrowser" && echo 'Vcs-Browser: __MKIT_PROJ_VCS_BROWSER__'
+            echo 'Section: misc'
+            echo 'Priority: extra'
+            echo 'Standards-Version: 3.9.2'
+            echo 'Build-Depends: debhelper (>= 9)'
+            echo ''
+            echo 'Package: __MKIT_PROJ_PKGNAME__'
+            echo 'Architecture: all'
+            echo 'Depends: MKIT_STUB_REQUIRES'
+            echo 'Description: __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
+            echo ' MKIT_STUB_DESCRIPTION'
+            echo ''
+            echo '# control file built with MKit __MKIT_SELF_VERSION__'
+            ;;
+
+        packaging/debian/changelog)
+            echo '__MKIT_PROJ_PKGNAME__ (__MKIT_PROJ_VERSION__-1) UNRELEASED; urgency=medium'
+            echo ''
+            echo '  * Initial release. (Closes: #XXXXXX)'
+            echo ''
+            echo " -- __MKIT_PROJ_MAINTAINER__  $(date -R)"
+            ;;
+
+        packaging/debian/compat)
+            echo 9
+            ;;
+
+        packaging/debian/rules)
+            echo '#!/usr/bin/make -f'
+            echo ''
+            echo '%:'
+            echo ''
+            echo '	dh $@'
+            echo ''
+            echo 'override_dh_auto_install:'
+            echo ''
+            echo '	make install PREFIX=/usr DESTDIR=debian/tmp'
+            echo ''
+            echo 'override_dh_usrlocal:'
+            echo ''
+            echo '	@true'
+            ;;
+
+        packaging/debian/source/format)
+            echo '3.0 (quilt)'
+            ;;
+
+        packaging/debian/*.install)
+            echo MKIT_STUB_FILELIST
+            ;;
+
+        src/*.skel)
+            echo 'echo "my version is: __MKIT_PROJ_VERSION__"'
+            echo 'echo "And that'"'"'s all, folks!"'
+            ;;
+
+        LICENSE.md)
+            local url   # license URL
+            url="${MKIT_STUB_LICENSES[$License]}"
+            curl -sf "$url" \
+             || die "failed to download license: $url"
+            ;;
+
+        .mkit/autoclean)
+            ;;
+
+        MKIT_STUB_README.md)
+            echo "FINISHING MKIT CONFIGURATION"
+            echo "============================"
+            echo ""
+            echo "Congratulations, your new project has been configured!"
+            echo ""
+            echo "However, the *stub* script is not able to figure out"
+            echo "everything, so few things still need to be done manually."
+            echo "This document will guide you throught the rest of the"
+            echo "process."
+
+            echo ""
+            echo ""
+            echo "Structure"
+            echo "---------"
+            echo ""
+            echo "First, let's go through the directory structure:"
+            echo ""
+            echo " *  *src* directory - here is your main place to store"
+            echo "    source files.  This includes also documents like user"
+            echo "    manuals---IOW, anything intended to end up on user's"
+            echo "    machine should be uder 'src'."
+            echo ""
+            echo "    Note that during build time, files named ending with"
+            echo "    '.skel' are subject to token expansion, see mkit.ini"
+            echo "    section below for details."
+            echo ""
+            echo " *  *notes* directory - here you shall store notes"
+            echo "    intended for people contributing to your project,"
+            echo "    for instance, guidelines, coding style documents,"
+            echo "    TODOs, ideas, plans..."
+            echo ""
+            echo " *  *utils* directory - here you shall store utilities"
+            echo "    and scripts that will help you with project maintenance,"
+            echo "    and that, unlike software like compilers or versioning"
+            echo "    systems, can (and should) be embedded inside the"
+            echo "    repository."
+            echo ""
+            echo "    MKit itself is one nice example. :)"
+
+            if $MkPackaging; then
+            echo ""
+            echo " *  *packaging* directory contains templates that enable"
+            echo "    MKit create raw stuffs used to create DEB or RPM"
+            echo "    packages.  Similar to '.skel' files in 'src', all files"
+            echo "    here are automatically considered for token expansion,"
+            echo "    no matter how they are named (see mkit.ini section"
+            echo "    below)."
+            echo ""
+            echo "    NOTE: these templates, as well as any packages created by"
+            echo "    them are intended only for experimental, private use and"
+            echo "    testing."
+            echo ""
+            echo "    Should you have ambition to create 'real' packages for"
+            echo "    OS distribution such as Debian or Fedora (what a great"
+            echo "    idea!), be prepared that you will need to follow their"
+            echo "    guidelines.  This will most probably mean huge changes"
+            echo "    to these packages or even changes to your workflow."
+
+            echo ""
+            echo ""
+            echo "Placeholders"
+            echo "------------"
+            echo ""
+            echo "At places where *stub* script did not have way to get all"
+            echo "information automatically, it has inserted placeholders."
+            echo "You will need to go through all of these placeholders and"
+            echo "replace them with proper data."
+            echo ""
+            echo "Please follow instructions:"
+            echo ""
+            echo " 1. Look for placeholders starting with \`MKIT_STUB_\`"
+            echo "    prefix by calling this command:"
+            echo ""
+            echo "        grep -l MKIT_STUB_ -r"
+            echo ""
+            echo " 2. Go through each file and locate the placeholder.  (You"
+            echo "    will also see placeholders like \`__MKIT_*__\`, you can"
+            echo "    ignore those."
+            echo ""
+            echo " 3. Replace placeholder with appropriate information:"
+            echo ""
+            echo "     *  \`MKIT_STUB_REQUIRES\` - Requirements of your"
+            echo "        project."
+            echo ""
+            echo "     *  \`MKIT_STUB_DESCRIPTION\` - Description of your"
+            echo "        project (few sentences to paragraphs)."
+            echo ""
+            echo "     *  \`MKIT_STUB_FILELIST\` - List of full paths to"
+            echo "        your files after installation."
+            echo ""
+            echo "        Note that in case of debian/package.install files,"
+            echo "        PREFIX based paths (eg. /usr/bin) in this file should"
+            echo "        should be as if PREFIX was /usr."
+            echo ""
+            echo "        In case of Fedora-based distro, you should make use"
+            echo "        of RPM macros:"
+            echo ""
+            echo "            https://fedoraproject.org/wiki/Packaging:RPMMacros"
+            echo ""
+            echo "    Refer to these documents for further details:"
+            echo ""
+            echo "        http://rpm-guide.readthedocs.io/"
+            echo "        https://www.debian.org/doc/manuals/maint-guide/"
+            fi
+
+            echo ""
+            echo ""
+            echo "mkit.ini"
+            echo "--------"
+            echo ""
+            echo "Most sections still need to be reviewed. In order to do"
+            echo "that, you will need to understand how MKit works:"
+            echo ""
+            echo " 1. First, you need to define *roles* your files will play"
+            echo "    when they are installed on user's file systems.  These"
+            echo "    roles then imply where and how the files should be"
+            echo "    deployed."
+            echo ""
+            echo "    Typical example of a role is e.g. 'bin' for commands"
+            echo "    (normally under '/usr/bin' or '/usr/local/bin'), 'doc'"
+            echo "    for documents or 'lib' for libraries."
+
+            echo ""
+            echo " 2. Next, in \`[roots]\` section, you have to set target"
+            echo "    root directory for each role.  However, in order to"
+            echo "    enable people to implement local conventions, it is"
+            echo "    considered a good manner to also respect PREFIX"
+            echo "    environment variable.  For this reason, most paths"
+            echo "    need to start with \`[ENV:PREFIX]\`."
+            echo ""
+
+            echo " 3. \`[files]\` section is where you assign actual files"
+            echo "    from your repository to their final paths.  The format"
+            echo "    is \`ROLE = REPOPATH [RENAMED]\`, where ROLE is file's"
+            echo "    role, REPOPATH is relative path to the file."
+            echo ""
+            echo "    Final path is then composed by taking path assigned to"
+            echo "    ROLE and appending file's name.  However, if you need"
+            echo "    the deployed file to have different name than in the"
+            echo "    codebase, you can specify the other name as RENAMED."
+            echo ""
+            echo "    Note that you don't need to address every single file"
+            echo "    individually, if in your repo you have a directory with"
+            echo "    100 files of the same role, you can add just path to the"
+            echo "    directory itself."
+
+            echo ""
+            echo " 4. If some roles require special permissions on your files,"
+            echo "    \`[modes]\` section is your friend.  Permissions here"
+            echo "    should be in UNIX octal format."
+
+            echo ""
+            echo " 5. Next, \`[tokens]\` section allows you to define own"
+            echo "    placeholders that will be replaced when your scripts are"
+            echo "    built.  Each file in 'src' directory that is named with"
+            echo "    '.skel' suffix, and each file from 'packaging' directory"
+            echo "    (no matter its name), can contain one or more of tokens"
+            echo "    defined here, plus range of tokens automatically defined"
+            echo "    by MKit.  During build, these tokens are replaced with"
+            echo "    their actual values."
+
+            echo ""
+            echo " 6. Less interesting, but important section is \`[dist]\`,"
+            echo "    which lists files in your codebase that will be added"
+            echo "    to distribution tarball (part of \"stuffs\" mentioned"
+            echo "    above).  Listing directory here will include all its"
+            echo "    contents, and normally it's OK to be very inclusive, so"
+            echo "    most of the time this section should be OK."
+
+            echo ""
+            echo " 7. Even less interesting is section \`[ENV]\`.  It is"
+            echo "    special in that it provides *default* value for an"
+            echo "    environment variable.  You almost never need to touch"
+            echo "    this."
+            echo ""
+
+            echo " 8. Finally, the most interesting section!  \`[project]\`,"
+            echo "    provides most general information for your project such"
+            echo "    as name and version."
+            echo ""
+            echo "    Note that the \`version\` key is another \"special"
+            echo "    snowflake\" -- it is now set to 0.0.0, and you **should"
+            echo "    not need** to change  it manually.  When you feel you"
+            echo "    a are ready to release next version of your evolving"
+            echo "    project, simply call \`make vbump\` and MKit will take"
+            echo "    care of everything!"
+
+            if $MkMakefile; then
+            echo ""
+            echo ""
+            echo "Makefile"
+            echo "--------"
+            echo ""
+            echo "*stub* script also created a Makefile for you, but all"
+            echo "it really does is include MKit's own mkit.mk, which in turn"
+            echo "only maps \`make\` targets to actual mkit script calls."
+            echo "Unless your project already uses GNU Make, you should not"
+            echo "need to change this file."
+            fi
+
+            if $MkReadme; then
+            echo ""
+            echo ""
+            echo "README.md"
+            echo "---------"
+            echo ""
+            echo "Each serious project needs a serious README.  Which is why"
+            echo "*stub* has created a 'stub' of one for you."
+            fi
+
+            echo ""
+            echo ""
+            echo "The final touch"
+            echo "---------------"
+            echo ""
+            echo "Once you have reviewed everything, just delete this file!"
+            ;;
+
+    esac >"$tmp"
+    cat "$tmp" > "$file"
+    rm "$tmp"
+}
+
+known_licenses() {
+    local key
+    local first=true
+    for key in "${!MKIT_STUB_LICENSES[@]}"; do
+        $first && echo "$key"  && continue
+        echo ", $key"
+    done
+}
+
+usage() {
+    {
+        echo "Usage:"
+        echo "   stub [options] new PKGNAME"
+        echo "   stub [options] update"
+        echo "   stub -L"
+        echo ""
+        echo "Options:"
+        echo ""
+        echo "    -c CODENAME   your project codename"
+        echo "    -t TAGLINE    your project tagline"
+        echo "    -b RELSRC     pre-release branch"
+        echo "    -B RELDST     post-release branch"
+        echo "    -n NICENAME   your project's 'nice' name"
+        echo "    -l LICENSE    your options's license (see -L)"
+        echo "    -m MAINT      project maintainer's name and e-mail"
+        echo "    -v URL        URL to public code browser"
+        echo "    -V VERSION    initial version (default: 0.0.0)"
+        echo "    -a            enable autoclean ('make clean' after"
+        echo "                  each 'make install')"
+        echo "    -g            make git commits before and adter"
+        echo "                  (implies -y)"
+        echo "    -y            don't ask, just do it"
+        echo "    -R            skip creating README.md"
+        echo "    -M            skip creating Makefile"
+        echo "    -P            skip creating packaging templates"
+        echo "    -L            list know licenses and exit"
+        echo ""
+        echo "PKGNAME should be packaging-friendly name, ie. consist"
+        echo "only of small letters, numbers, underscore and dash."
+        echo "For your 'real' name, use NICENAME, which can be any"
+        echo "string."
+    } >&2
+    exit 2
+}
+
+confirm() {
+    local response      # user's response to our warning
+    $Force && return 0
+    {
+        echo "Warning: This operation can be destructive for your"
+        echo "current codebase.  At least following files will be"
+        echo "created or overwritten:"
+        echo ""
+        $MkPackaging    && echo " *  'packaging' directory (pass -P to avoid)"
+        $MkMakefile     && echo " *  'Makefile' (pass -M to avoid)"
+        $MkReadme       && echo " *  'README.md' (pass -R to avoid)"
+        $MkLicense      && echo " *  'LICENSE.md' (omit -l to avoid)"
+        echo " *  'mkit.ini'"
+        echo ""
+        read -p "Type 'yes' to proceed: " -r response
+    } >&2
+    test "$response" == "yes" && return 0
+    warn "Aborting."
+    return 1
+}
+
+mkcommit_backup() {
+    git ls-files --others \
+      | grep -qv -e '^utils/mkit$' -e '^utils/mkit/' \
+     || { warn "nothing to back up"; return 0; }
+    git add .                           || return
+    git rm -r --cached utils/mkit       || return
+    git commit -m "WIP [mkit/stub] backup" || return
+}
+
+mkcommit_mkit_code() {
+    git ls-files --others \
+      | grep -q -e '^utils/mkit$' -e '^utils/mkit/' \
+     || return 0
+    git add utils/mkit || return
+    git commit -m "WIP [mkit/stub] Add MKit version v$MKIT_VERSION" || return
+}
+
+mkcommit_mkit_conf() {
+    local msg       # commit message (the important art
+    git add . || return
+    case $Action in
+        new)    msg="Add MKit configuration stub" ;;
+        update) msg="Update MKit configuration"   ;;
+    esac
+    git commit -m "WIP [mkit/stub] $msg" || return
+}
+
+deploy_packaging() {
+    rm -rf packaging
+    deploy packaging/template.spec
+    deploy packaging/debian/copyright
+    deploy packaging/debian/control
+    deploy packaging/debian/changelog
+    deploy packaging/debian/compat
+    deploy packaging/debian/rules
+    deploy packaging/debian/source/format
+    deploy packaging/debian/"$PackageName".install
+}
+
+init_from_existing() {
+    #
+    # Initialize variables from old mkit.ini
+    #
+    test -f "$MKIT_INI" \
+     || die "mkit.ini not found; aborting update: $MKIT_INI"
+    user_gave Codename    || Codename=$(ini_raw1v project:codename)
+    user_gave License     || License=$(ini_raw1v project:license)
+    user_gave Maintainer  || Maintainer=$(ini_raw1v project:maintainer)
+    user_gave NiceName    || NiceName=$(ini_raw1v project:name)
+    user_gave PackageName || PackageName=$(ini_raw1v project:pkgname)
+    user_gave RelDst      || RelDst=$(ini_raw1v project:reldst)
+    user_gave RelSrc      || RelSrc=$(ini_raw1v project:relsrc)
+    user_gave Tagline     || Tagline=$(ini_raw1v project:tagline)
+    user_gave VcsBrowser  || VcsBrowser=$(ini_raw1v project:vcs_browser)
+    user_gave Version     || Version=$(ini_raw1v project:version)
+}
+
+ini_raw1v() {
+    #
+    # Read raw scalar from mkit.ini
+    #
+    local path=$1
+    MKIT_INI_EXPAND=0 ini 1value "$path"
+}
+
+user_gave() {
+    #
+    # True if user gave value to variable $1
+    #
+    local var=$1    # name of the variable
+    { test "${UserGave[$var]}" == 1; } 2>/dev/null
+}
+
+updating() {
+    #
+    # Are we updating?
+    #
+    test "$Action" == update
+}
+
+remake_section() {
+    #
+    # Re-compose mkit.ini section $1
+    #
+    local section=$1
+    local key
+    local value
+    ini lskeys "$section" | grep -q . \
+     || return 1
+    echo ""
+    echo "[$section]"
+    ini lskeys "$section" \
+      | while read -r key; do
+            MKIT_INI_EXPAND=0 ini values "$section:$key" \
+              | while read -r value; do
+                    echo "$key = $value"
+                done
+        done \
+      | column -to' ' \
+      | sed 's/^/    /'
+}
+
+main() {
+    local NiceName          # human-readable project name
+    local PackageName       # machine-safe project (package) name
+    local RelSrc            # pre-release branch
+    local RelDst            # post-release branch
+    local Codename          # release codename
+    local Tagline           # project tagline
+    local Maintainer        # project maintainer (Name + e-mail)
+    local VcsBrowser        # VCS browser (eg. GitHub URL)
+    local Version=0.0.0     # project version
+    local AutoClean=false   # touch .mkit/autoclean?
+    local MkCommits=false   # create pre/post git commits?
+    local Force=false       # go without asking?
+    local MkReadme=true     # create README.md?
+    local MkMakefile=true   # create Makefile?
+    local MkPackaging=true  # create packaging templates?
+    local MkLicense=false   # create LICENSE.md file
+    local Action            # 'update' to respect existing, 'new' to force
+                            # rewrite incl. MKIT_STUB_* placeholders
+    declare -A UserGave
+    while true; do case $1 in
+        -n) NiceName=$2;   UserGave[NiceName]=1;   shift 2 || usage ;;
+        -b) RelSrc=$2;     UserGave[RelSrc]=1;     shift 2 || usage ;;
+        -B) RelDst=$2;     UserGave[RelDst]=1;     shift 2 || usage ;;
+        -c) Codename=$2;   UserGave[Codename]=1;   shift 2 || usage ;;
+        -t) Tagline=$2;    UserGave[Tagline]=1;    shift 2 || usage ;;
+        -l) License=$2;    UserGave[License]=1;    shift 2 || usage ;;
+        -m) Maintainer=$2; UserGave[Maintainer]=1; shift 2 || usage ;;
+        -v) VcsBrowser=$2; UserGave[VcsBrowser]=1; shift 2 || usage ;;
+        -V) Version=$2;    UserGave[Version]=1;    shift 2 || usage ;;
+        -M) MkMakefile=false;   shift ;;
+        -R) MkReadme=false;     shift ;;
+        -a) AutoClean=true;     shift ;;
+        -y) Force=true;         shift ;;
+        -g) MkCommits=true;     shift ;;
+        -P) MkPackaging=false;  shift ;;
+        -L) known_licenses | tr , '\n'; exit 0 ;;
+        -*) usage ;;
+        *)  break ;;
+    esac done
+    Action=$1; PackageName=$2
+    case $Action:$PackageName in
+        new:)     usage ;;
+        new:*)    :     ;;
+        update:)  :     ;;
+        update:*) usage ;;
+        *)        usage ;;
+    esac
+    updating && init_from_existing
+    if test -n "$License"; then
+        known_licenses | grep -qxF "$License" \
+         || die "unknown license (use -L to get list): $License"
+        MkLicense=true
+    fi
+    if $MkCommits; then
+        mkcommit_backup || die "failed creating backup commit"
+        Force=true
+    fi
+    confirm            || return 1
+    deploy "$MKIT_INI"
+    deploy src/"$PackageName".skel
+    $MkMakefile     && deploy Makefile
+    $MkReadme       && deploy README.md
+    $MkLicense      && deploy LICENSE.md
+    $AutoClean      && deploy .mkit/autoclean
+    $MkPackaging    && deploy_packaging
+    if $MkCommits; then
+        mkcommit_mkit_code || die "failed creating post-commit"
+        mkcommit_mkit_conf || die "failed creating post-commit"
+    fi
+    deploy MKIT_STUB_README.md
+    warn "Configuration stub built, follow instructions in"
+    warn "MKIT_STUB_README.md to finish configuration."
+    return 0
+}
+
+main "$@"