Update MKit to v0.0.20

utils/mkit/include/build.sh

 
 _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
 
 _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
 }
 
 _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
     #
     # Guess file type from destination path $1
     #
-    local dstpath="$1"
+    local dstpath=$1    # destination path
     case $dstpath in
         *.md) echo markdown    ;;
         *)    echo MKIT_COMMON ;;
     #
     # 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"
     #
     # 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'
     #
 
     # 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"
 }
     #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"
     #
     # 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

     # 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
+    local src=$1                            # source path
+    local dst=$2                            # destination path
+    local mode=${3:-$MKIT_DEFAULT_MODE}     # mode
+    local chmod_item                        # each file to chmod in directory
+    if test -d "$src"; then
         _maybe mkdir -vp "$(dirname "$dst")"
         _maybe cp -Tvr "$src" "$dst"
         find "$dst" -type f \
-          | while read chmod_item;
-            do
+          | while read -r chmod_item; do
                 _maybe chmod "$mode" "$chmod_item"
             done
     else
     #
     # 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"
 }
     #
     # 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" ;;
     #
     # 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
     #
     # 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

     #
     # 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)
     #
     # 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)
     # 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')
     # 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
             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

     #
     # A no-op for text stream
     #
-    while read line;
-    do
+    local line      # each line
+    while read -r line; do
         printf -- "%s\n" "$line"
     done
 }
     #
     # 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
     #
     # Read key from a section
     #
-    local wnt=$1
+    local wnt=$1    # wanted key
     grep '.' \
       | grep -v '\s*#' \
       | sed -e 's/ *= */=/; s/ +$//; s/^//;' \
     #     [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"
 }
     #
     # 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 ;;
     #
     # List keys from a section
     #
-    local sct="$1"
+    local sct=$1    # section of interest
     _ini_grepsec "$sct" | cut -d= -f1 | sort | uniq
 }
 
     #
     # 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
     #
     # 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  ;;
     #
     # 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

     # 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__"
     # 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%%.*}
     # 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"
     #
     # 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

     #
     # 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"        ;;
     #
     # 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 \
              && 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"
     # 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 reldst        # release destination branch (if any)
 
     _relck git_present
     _relck at_relsrc
 
     reldst=$(ini 1value project:reldst)
     debug_var reldst
-    if test -n "$reldst";
-    then
+    if test -n "$reldst"; then
         git branch -f "$reldst" "$newtag"
     fi
 }
 }
 
 _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
 }
 
 _vbump_gitmsg() {
+    #
+    # Compose git message template for 'Bump version' commit
+    #
     echo "Bump version"
     echo ""
     echo "Overview of changes:"
 }
 
 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_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/make

 #!/bin/bash
+#shellcheck disable=SC2034,SC1090
 # mkit - simple install helper
 # See LICENSE file for copyright and license details.
 
 die() {
-    echo "$@" && exit 9
+    #
+    # Poor man's die() (mkit.sh has better)
+    #
+    echo "$@" >&2 && exit 9
 }
 
 
 #
 # This MKit version
 #
-MKIT_VERSION=0.0.18
+MKIT_VERSION=0.0.20
 
 
 . "$MKIT_DIR/include/mkit.sh" || die "failed to init; check if MKIT_DIR is set properly: $MKIT_DIR"

utils/mkit/mkit.mk

 install: all
 	@$(MKIT_DIR)/make install
 
+release:
+	@$(MKIT_DIR)/make release_z
+
 release_x:
 	@$(MKIT_DIR)/make release_x
 
 uninstall:
 	@$(MKIT_DIR)/make uninstall
 
+vbump:
+	@$(MKIT_DIR)/make vbump_z
+
 vbump_x:
 	@$(MKIT_DIR)/make vbump_x