Overview of changes:

 *  Minor scripting and packaging updates

.gitlab-ci.yml

+---
+include:
+  - project: 'vornet/infra/gladness'
+    ref: main
+    file: '/pipelines/mkit.yaml'

mkit.ini

 [project]
-    version     = 0.0.15
+    version     = 0.0.21
     name        = imapdomo
     pkgname     = imapdomo
     maintainer  = Alois Mahdal <netvor+imapdomo@vornet.cz>
-    vcs_browser = https://pagure.io/imapdomo
+    vcs_browser = https://gitlab.com/vornet/hacktop/imapdomo
     tagline     = imapfilter convenience wrapper
-    relsrc      = master
+    relsrc      = main
     reldst      = latest
 
 [dist]
     share   = src/imaprules.lua
     share   = src/main.lua
 
-#mkit version=0.0.40
+#mkit version=0.1.3

packaging/debian/control

 Standards-Version: 3.9.2
 Build-Depends:
  debhelper (>= 9),
+ make,
 
 Package: __MKIT_PROJ_PKGNAME__
 Architecture: all

packaging/template.spec

 License:    GPLv2
 Source0:    %{name}-%{version}.tar.gz
 BuildArch:  noarch
+BuildRequires: make
 
 Requires: %shellfu_req
 Requires: imapfilter

src/imapdomo.lua

 -- mail getters                                                             --
 ------------------------------------------------------------------------------
 
-pkg.get_queue = function(acct, mbox)
+pkg.get_queue = function(acct, mbox, size)
     --
     -- Get queue from *mbox* from *acct* or nil (no messages)
     --
     -- If mbox is not specified, "FILTER_QUEUE" is used
     --
     mbox = mbox or "FILTER_QUEUE"
+    size = size or 512
     local exist = acct[mbox]:check_status()
     if exist > 0 then
-        return acct[mbox]:select_all()
+        return pkg.head(size, acct[mbox]:select_all())
     end
     return nil
 end
     return result
 end
 
+pkg.head = function(num, seq)
+    --
+    -- Return first *num* elements from sequence
+    --
+    if not seq then return seq end
+    local result = seq:is_smaller(0)    -- HACK to generate empty sequence
+    for idx, value in ipairs(seq) do
+        if idx > num then break end
+        table.insert(result, value)
+    end
+    return result
+end
+
 pkg.filter_part_like = function(query, seq)
     --
     -- Run MIME part query on *seq* sequence of messages

src/imapdomo.skel

             "-c DIR      change to DIR before doing anything"                 \
             "-l          list handlers and exit"                              \
             "-d          turn on debugging mode"                              \
+            "-t CERTS    Use certificates file CERTS."                        \
+            "-T          Use system CA certificate storage."                  \
             "-N          turn off locking; make sure that handlers cannot"    \
             "            interfere with each other or that another locking"   \
             "            mechanism is in place.  Also see NOTE below."        \
+            "-V          Show imapdomo version and exit."                     \
        --                                                                     \
        "imapdomo will try to read init.lua and handlers/ACTION.lua from its"  \
        "configuration directory."                                             \
        "See imapfilter_config(5)) for guide and API reference.  Few functions"\
        "are also available in .imapdomo/imapdomo.lua"                         \
        ""                                                                     \
+       "By default, imapdomo will look for 'certificates' file under the"     \
+       "directory (__IMAPDOMO_CONFIG_USER__), and if it exists, it will tell" \
+       "imapfilter to use it via -t argument.  If it does not exist, it will" \
+       "leave the argument out, meaning imapfilter will use system cert"      \
+       "storage.  Use -T to force system storage or -t to force another file."\
+       ""                                                                     \
        "NOTE: Be aware that it's your responsibility to ensure that filters"  \
        "don't cause performance problems. (Trust me, it's not so hard to"     \
        "\"earn\" yourself a nice server ban--I learned that the hard way)."
     #
     debug -v NoLock
     $NoLock && return 0
+    mkdir -p "$IMAPDOMO_USER_CACHE"
     date +"$$@%s" > "$IMAPDOMO_USER_CACHE/lock"
     debug -f "$IMAPDOMO_USER_CACHE/lock"
 }
     CfgDir="$IMAPDOMO_CFGDIR"
     LogDir="$IMAPDOMO_USER_CACHE/logs"
     HeaderDir="$IMAPDOMO_USER_CACHE/headers"
-    Certs="$IMAPDOMO_CFGDIR/certificates"
+    test -f "$IMAPDOMO_CFGDIR/certificates" && Certs="$IMAPDOMO_CFGDIR/certificates"
     NoLock=false
     Debug=false
     #shellcheck disable=SC2034
         -t) Certs="$2"; shift 2 || usage -w "missing value to: $1" ;;
         -l) lshandlers; exit ;;
         -N) NoLock=true; shift ;;
+        -T) Certs=; shift ;;
         -V|--version-semver) show_semversion ;;
         --version) show_version ;;
         -*) usage -w "unknown argument: '$1'" ;;

utils/mkit/include/build.sh

 
 mkit_import ini
 mkit_import facts
+mkit_import plugin
+mkit_import util
 
 
-__build1() {
+build__file() {
     #
     # Process one skeleton $1 of type $3 (or guessed) to path $2
     #
     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")
+    test -n "$ftype"    || ftype=MKIT_COMMON
     debug_var srcpath dstpath ftype
-    <"$srcpath" __build1_ftype "$ftype" >"$dstpath"
-    __rec_built "$dstpath"
+    <"$srcpath" __build__file_type "$ftype" >"$dstpath"
+    build__record "$dstpath"
 }
 
-__build1_ftype() {
+__build__file_type() {
     #
     # Build a file of type $1; fom stdin to stdout
     #
     local ftype=$1      # file/builder type
-    case $ftype in
-        MKIT_COMMON)    __expand_macros "macros" ;;
-        rpmstuff)       __expand_macros "macros" "rpmstuff:macros" ;;
-        debstuff)       __expand_macros "macros" "debstuff:macros" ;;
-        *)              die "unknown file type: $ftype" ;;
-    esac
+    if test "$ftype" == MKIT_COMMON; then
+        __build__macro_expand "build:macros"
+    elif plugin__isvalid "$ftype"; then
+        __build__macro_expand "$ftype:macros"
+    else
+        die "unknown file type: $ftype"
+    fi
 }
 
-__expand_line() {
+__build__macro_ls() {
     #
-    # Expand macro from $MacroMap in single line $1
+    # List known macros
+    #
+    find "${MacroDirs[@]}" -mindepth 1 -depth -printf '%P\n' \
+      | sed 's/[.]/:/g'
+}
+
+__build__macro_read() {
+    #
+    # Read macro $1
+    #
+    local key=$1
+    find "${MacroDirs[@]}" -mindepth 1 -depth -name "$key" \
+      | head -1 \
+      | xargs -r cat
+}
+
+__build__macro_put() {
+    #
+    # Write stdin as macro $1
+    #
+    local fqkey=$1
+    local file="$MKIT_LOCAL/data/${fqkey//:/.}"
+    mkdir -p "${file%/*}"
+    cat >"$file"
+}
+
+__build__macro_expand_line() {
+    #
+    # Expand macro from config in single line $1
     #
     # If macro value has multiple lines, repeat original line with
     # different substitution.
     # line `see: "__FOO__"` will expand to two lines: `see: "foo"`
     # and `see: "bar"`.
     #
-    local line=$1   # line to process
-    local mname     # macro name
-    local mvline    # line of macro value
-    local xline     # expanded line
-    xline=$line
-    for mname in "${!MacroMap[@]}"; do
-        if ! test "${line//$mname}" == "$line"; then
-            xline=$(
-                while IFS= read -r mvline; do
-                    echo "${line//$mname/$mvline}"
-                done <<<"${MacroMap[$mname]}"
+    local raw_line=$1       # line to process
+    local macro_name        # macro name
+    local macro_value_line  # line of macro value
+    local expanded_line     # expanded line
+    expanded_line=$raw_line
+    for macro_name in $(__build__macro_ls); do
+        if ! test "${raw_line//$macro_name}" == "$raw_line"; then
+            expanded_line=$(
+                while IFS= read -r macro_value_line; do
+                    echo "${raw_line//"$macro_name"/"$macro_value_line"}"
+                done <<<"$(__build__macro_read "$macro_name")"
             )
         fi
-        line=$xline
+        raw_line=$expanded_line
     done
-    echo "$xline"
+    echo "$expanded_line"
     return 1
 }
 
-__expand_macros() {
+__build__macro_expand() {
     #
-    # Read stdin, expanding macros from sections $@
+    # Read stdin, expanding macros from extra sections $@
     #
-    local section       # each section to expand macros from
+    local MacroDirs=()  # directories to lookup macros in
+    local mdir          # every ^^
     local line          # each line on stdin
-    local mname         # each macro name
-    local -A MacroMap   # macro value map
-    MacroMap[__MKIT_MKIT_VERSION__]=$MKIT_VERSION
-    MacroMap[__MKIT_PROJ_NAME__]=$(ini 1value project:name)
-    MacroMap[__MKIT_PROJ_CODENAME__]=$(ini 1value project:codename)
-    MacroMap[__MKIT_PROJ_LICENSE__]=$(ini 1value project:license)
-    MacroMap[__MKIT_PROJ_PKGNAME__]=$(ini 1value project:pkgname)
-    MacroMap[__MKIT_PROJ_TAGLINE__]=$(ini 1value project:tagline)
-    MacroMap[__MKIT_PROJ_MAINTAINER__]=$(ini 1value project:maintainer)
-    MacroMap[__MKIT_PROJ_VCS_BROWSER__]=$(ini 1value project:vcs_browser)
-    MacroMap[__MKIT_PROJ_GIT_LASTHASH__]=$(__cached git_lasthash)
-    MacroMap[__MKIT_PROJ_GIT_LASTSUMMARY__]=$(__cached git_lastsummary)
-    MacroMap[__MKIT_PROJ_VERSION__]=$(__cached semver)
-    for section in "$@"; do
-        for mname in $(ini lskeys "$section"); do
-            MacroMap[$mname]=$(ini values "$section:$mname")
-        done
+    local bltndata="$MKIT_LOCAL/data/MKIT_BUILTIN"
+    local usrdata="$MKIT_LOCAL/data/macros"
+    test -d "$bltndata" && MacroDirs+=("$bltndata")
+    test -d "$usrdata" && MacroDirs+=("$usrdata")
+    for extra in "$@"; do
+        mdir="$MKIT_LOCAL/data/${extra//:/.}"
+        test -d "$mdir" || continue
+        MacroDirs+=("$mdir")
     done
-    debug_var MacroMap
     while IFS= read -r line; do
-        __expand_line "$line"
+        __build__macro_expand_line "$line"
     done
 }
 
-__guess_ftype() {
-    #
-    # Guess file type from destination path $1
-    #
-    local dstpath=$1    # destination path
-    case $dstpath in
-        *)    echo MKIT_COMMON ;;
-    esac
-}
-
-__qfs() {
-    #
-    # Quote for our sed scipt's RHS
-    #
-    sed '
-        s:\\:\\\\:g
-        s:|:\\|:g
-    '
-}
-
-__cached() {
+build__cached() {
     #
     # Cached value $1 of function $1()
     #
     # arguments).
     #
     local name=$1
-    __local_get "$name" && return 0
+    __local_get "$name" && debug "cache hit with: $name()" && return 0
+    debug "cache miss with: $name()"
     "$name" | __local_putb "$name"
     __local_get "$name"
 }
     # Make file $1 in $MKIT_LOCAL from stdin and mark as built
     #
     local fpath=$1
-    __local_put "$fpath" && __rec_built "$MKIT_LOCAL/$fpath"
+    __local_put "$fpath" && build__record "$MKIT_LOCAL/$fpath"
 }
 
 __local_put() {
     cat "$fpath" 2>/dev/null
 }
 
-__rec_built() {
+build__fact() {
+    #
+    # Make fact file $1 in $MKIT_LOCAL from stdin; mark as built
+    #
+    local name=$1
+    __local_put "facts/$name" || die
+    build__recordr "$MKIT_LOCAL/facts"
+}
+
+build__factr() {
+    #
+    # Read fact file $1 from $MKIT_LOCAL
+    #
+    local name=$1
+    cat "$MKIT_LOCAL/facts/$name" || die
+}
+
+build__record() {
     #
     # Record file $1 for deletion on `clean`
     #
     echo "1:$file" >> "$MKIT_LOCAL/built.lst"
 }
 
-_mkit_data() {
+build__recordr() {
     #
-    # Build sampler showing all macro values
+    # Record dir $1 for recursive  deletion on `clean`
+    #
+    local path=$1
+    mkdir -p "$MKIT_LOCAL"
+    echo "r:$path" >> "$MKIT_LOCAL/built.lst"
+}
+
+_mkit_builddata() {
+    #
+    # Build config data
     #
     local macro
     local section
-    local sections
-    sections=()
-    ini lskeys macros | grep -q . && sections=(macros)
-    sections+=( $(ini lssect | grep ':macros$') )
-    {
-        echo "(builtin):"
-        echo "  x_MKIT_MKIT_VERSION__ => '__MKIT_MKIT_VERSION__'"
-        echo "  x_MKIT_PROJ_NAME__ => '__MKIT_PROJ_NAME__'"
-        echo "  x_MKIT_PROJ_CODENAME__ => '__MKIT_PROJ_CODENAME__'"
-        echo "  x_MKIT_PROJ_LICENSE__ => '__MKIT_PROJ_LICENSE__'"
-        echo "  x_MKIT_PROJ_PKGNAME__ => '__MKIT_PROJ_PKGNAME__'"
-        echo "  x_MKIT_PROJ_TAGLINE__ => '__MKIT_PROJ_TAGLINE__'"
-        echo "  x_MKIT_PROJ_MAINTAINER__ => '__MKIT_PROJ_MAINTAINER__'"
-        echo "  x_MKIT_PROJ_VCS_BROWSER__ => '__MKIT_PROJ_VCS_BROWSER__'"
-        echo "  x_MKIT_PROJ_GIT_LASTHASH__ => '__MKIT_PROJ_GIT_LASTHASH__'"
-        echo "  x_MKIT_PROJ_GIT_LASTSUMMARY__ => '__MKIT_PROJ_GIT_LASTSUMMARY__'"
-        echo "  x_MKIT_PROJ_VERSION__ => '__MKIT_PROJ_VERSION__'"
-        for section in "${sections[@]}"; do
-            echo "$section:"
-            for macro in $(ini lskeys "$section"); do
-                echo "  x${macro:1} => '$macro'"
-            done
+    test -d "$MKIT_LOCAL/data/build.macros" && {
+        warn "mkit: using cached _mkit_builddata: $(date -Isec -r "$MKIT_LOCAL/data/build.macros")" \
+             "mkit:   (hint: run 'make clean' to regenerate it)"
+        return 0
+    }
+    build__recordr "$MKIT_LOCAL/data"
+    for macro in $(ini lskeys "build:macros"); do
+        ini values "build:macros:$macro" | __build__macro_put "build:macros/$macro"
+    done
+}
+
+_mkit_inidata() {
+    #
+    # Build INI data
+    #
+    test -d "$MKIT_LOCAL/data/ini" && {
+        warn "mkit: using cached _mkit_inidata: $(date -Isec -r "$MKIT_LOCAL/data/ini")" \
+             "mkit:   (hint: run 'make clean' to regenerate it)"
+        return 0
+    }
+    build__recordr "$MKIT_LOCAL/data"
+    local sect
+    local key
+    ini lssect \
+      | while read -r sect; do
+            mkdir -p "$MKIT_LOCAL/data/ini/$sect"
+            ini lskeys "$sect" \
+              | while read -r key; do
+                    ini values "$sect:$key" >"$MKIT_LOCAL/data/ini/$sect/$key"
+                done
         done
-    } \
-      | __expand_macros "MKIT_BUILTIN" "${sections[@]}" \
-      | sed '/^  x/ s|x|_|'
+}
+
+_mkit_metadata() {
+    #
+    # Build meta data
+    #
+    local plg_sections=()
+    test -d "$MKIT_LOCAL/data/MKIT_BUILTIN" && {
+        warn "mkit: using cached _mkit_metadata: $(date -Isec -r "$MKIT_LOCAL/data/MKIT_BUILTIN")" \
+             "mkit:   (hint: run 'make clean' to regenerate it)"
+        return 0
+    }
+    build__recordr "$MKIT_LOCAL/data"
+    echo "$MKIT_VERSION"            | __build__macro_put MKIT_BUILTIN/__MKIT_MKIT_VERSION__
+    ini 1value project:name         | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_NAME__
+    ini 1value project:codename     | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_CODENAME__
+    ini 1value project:license      | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_LICENSE__
+    ini 1value project:pkgname      | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_PKGNAME__
+    ini 1value project:tagline      | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_TAGLINE__
+    ini 1value project:maintainer   | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_MAINTAINER__
+    ini 1value project:vcs_browser  | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_VCS_BROWSER__
+    build__cached git_lasthash      | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_GIT_LASTHASH__
+    build__cached git_lastsummary   | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_GIT_LASTSUMMARY__
+    build__cached semver            | __build__macro_put MKIT_BUILTIN/__MKIT_PROJ_VERSION__
+    util__loadarr plg_sections __plugin_macro_sections
+    debug_var plg_sections
+    for section in macros "${plg_sections[@]}"; do
+        for macro in $(ini lskeys "$section"); do
+            ini values "$section:$macro" | __build__macro_put "$section/$macro"
+        done
+    done
+}
+
+__subdirs() {
+    #
+    # List direct sub-directories of $1
+    #
+    find "$1" -maxdepth 1 -mindepth 1 -printf '%P\n' -type d
+}
+
+__subfiles() {
+    #
+    # List direct sub-files of $1
+    #
+    find "$1" -maxdepth 1 -mindepth 1 -printf '%P\n' -type f
+}
+
+__plugin_macro_sections() {
+    #
+    # List macro sections for plugins
+    #
+    plugin__ls \
+      | sed 's/$/:macros/'
+}
+
+_mkit_show_metadata() {
+    #
+    # Show sampler of macro values
+    #
+    __show_msection MKIT_BUILTIN
+    __show_msection macros
+    __plugin_macro_sections \
+      | while read -r section; do
+            __show_msection "$section"
+        done
+}
+
+_mkit_show_builddata() {
+    #
+    # Show sampler of config values
+    #
+    __show_msection build:macros
+}
+
+__show_msection() {
+    #
+    # Show macros of section $1
+    #
+    local section=$1
+    local macro_name
+    local first=true
+    local label=$section
+    local secdir="$MKIT_LOCAL/data/${section//:/.}"
+    test -d "$secdir" || return 0
+    test "$section" == MKIT_BUILTIN && label="(builtin)"
+    for macro_name in $(__subfiles "$secdir"); do
+        $first && echo "$label:"; first=false
+        echo "    $macro_name => '$(<"$secdir/$macro_name")'"
+    done
 }
 
 build() {
     local srcpath   # each source path
     find . -type f -name '*.skel' \
      | while read -r srcpath; do
-           __build1 "$srcpath"
+           build__file "$srcpath"
        done
 }
 
     true
 }
 
-debstuff() {
-    #
-    # Build Debian stuff (eamed tarball, debian dir)
-    #
-    local version       # package version
-    local debian_skel   # 'debian' folder skeleton
-    local dfsrc         # each source file from ^^
-    local dftgt         # each built packaging file
-    version=$(__cached semver)
-
-    # tarball - we should already have by means of 'dist'
-    #
-    mv "${MKIT_PROJ_PKGNAME}-$version.tar.gz" \
-       "${MKIT_PROJ_PKGNAME}_$version.orig.tar.gz" \
-     || die "could not rename tarball"
-    __rec_built "${MKIT_PROJ_PKGNAME}_$version.orig.tar.gz"
-
-    # read content of each mandatory file from debian_skel
-    #
-    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
-    find "$debian_skel" -type f \
-      | while read -r dfsrc; do
-            dftgt="debian/${dfsrc#$debian_skel}"
-            mkdir -p "$(dirname "$dftgt")"
-            __build1 "$dfsrc" "$dftgt" debstuff
-        done
-    __rec_built debian
-}
-
 dist() {
     #
     # Create distributable tarball
     version=$(semver)
     dirname=$MKIT_PROJ_PKGNAME-$version
     git_lasthash=$(git_lasthash)
+    debug_var version dirname git_lasthash
     mkdir -p "$dirname"
     ini values "dist:tarball" | xargs -I DIST_ITEM cp -R DIST_ITEM "$dirname"
     mkdir -p "$dirname/.mkit"
     echo -n "$version" > "$dirname/.mkit/semver"
     echo -n "$git_lasthash" > "$dirname/.mkit/git_lasthash"
+    cp -r "$MKIT_LOCAL/data" "$dirname/.mkit/"
     tar -cf "$dirname.tar" "$dirname"
     gzip -f "$dirname.tar"      # see above FIXME
-    __rec_built "$dirname.tar.gz"
+    build__record "$dirname.tar.gz"
     rm -rf "$dirname"
 }
-
-rpmstuff() {
-    #
-    # Build specfile
-    #
-    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" rpmstuff
-}

utils/mkit/include/deploy.sh

 # See LICENSE file for copyright and license details.
 
 mkit_import ini
+mkit_import build
 
-__deploy_item() {
+__deploy__item() {
     #
     # Deploy item and make it look like wanted
     #
-    # usage: __deploy_item src dst [mode]
+    # usage: __deploy__item src dst [mode]
     #
     # Both src and dst must be names of actual items[1],
     # whereas dst must not exist.  On update, dst is
                 [[ $item =~ .skel$ ]] \
                  && grep -qe "${item%.skel}" "$MKIT_LOCAL/built.lst" \
                  && continue
-                __deploy_item "$item" "$dst${item#$src}" "$mode"
+                __deploy__item "$item" "$dst${item#"$src"}" "$mode"
             done
     else
         test "$mode" == "SRC" && mode=$(stat -c "%a" "$src")
-        __maybe install -DTvm "$mode" "$src" "$dst"
+        __deploy__maybe install -DTvm "$mode" "$src" "$dst"
     fi
 }
 
-__get_dst() {
+__deploy__dst() {
     #
     # Find out target path for src file $2 of group $1
     #
     local src=$2        # each source
     local dst=$3        # alternative destination name
     test -n "$dst" || dst=${src##*/}
-    echo "$(__get_root "$grp")/$dst"
+    echo "$(__deploy__root "$grp")/$dst"
 }
 
-__get_root() {
+__deploy__root() {
     #
     # Find out target root for group $1
     #
     esac
 }
 
-__maybe() {
+__deploy__maybe() {
     #
     # Call the deploy command $1 $@ unless in dry mode
     #
             mode=$(ini 1value "modes:$group")
             ini values "files:$group" \
               | while read -r src dst; do
-                    dst=$(__get_dst "$group" "$src" "$dst")
-                    __deploy_item "$src" "$dst" "$mode"
+                    dst=$(__deploy__dst "$group" "$src" "$dst")
+                    __deploy__item "$src" "$dst" "$mode"
                 done
         done
     test -f "$MKIT_LOCAL/autoclean" && clean
       | while read -r group; do
             ini values "files:$group" \
               | while read -r src dst; do
-                    dst=$(__get_dst "$group" "$src" "$dst")
-                    __maybe rm -vrf "$dst"
+                    dst=$(__deploy__dst "$group" "$src" "$dst")
+                    __deploy__maybe rm -vrf "$dst"
                 done
         done
 }

utils/mkit/include/facts.sh

     # Get git bool (ie. exit status counts) $1
     #
     local bool_name=$1      # name of boolean to get
-    git_present || warn "can't give bool outside git repo: $bool_name"
+    git_present || {
+        warn "can't give bool outside git repo: $bool_name"
+        return 3
+    }
     case "$bool_name" in
         dirty_files)
             git diff-files | grep -qm 1 .
         dirty)
             git_bool dirty_files || git_bool dirty_index
             ;;
+        async)
+            local status_desc   # status description (in square brackets)
+            status_desc=$(git status -sb | grep '^##.*' | grep -o '\[[^]]*\]$')
+            grep -qw behind <<<"$status_desc" && return 0
+            grep -qw ahead <<<"$status_desc" && return 0
+            return 1
+            ;;
         *)
             warn "unknown git bool asked: $bool_name"
             return 2
         reldiff)
             git log --oneline "$(git_fact latest_tag)..HEAD" --name-only
             ;;
+        reldiff_brief)
+            git rev-list --oneline "$(git_fact latest_tag)..HEAD"
+            ;;
         latest_sha)
             git log -1 --pretty=format:%h HEAD
             ;;
       | cut -d' ' -f2-
 }
 
+make_bmeta() {
+    #
+    # Compose build metadata string
+    #
+    local is_tagged=T   # T if tagged (clean, no metadata), F if devel
+    local brname        # current branch name
+    local ghash         # current commit short hash
+    if ! git describe --tags --exact-match HEAD >&/dev/null;
+    then    # we are at a later commit than the last tag
+        is_tagged=F
+        brname=$(git_fact current_branch | sed 's/[^[:alnum:]]/_/g')
+        ghash=$(git_fact latest_sha)
+    fi
+    {
+        if test "$is_tagged" == F; then
+            test -n "$stamp" && echo "t$stamp"
+            echo "$brname"
+            echo "g$ghash"
+            test -n "$MKIT_UPSTREAM" && echo "u$MKIT_UPSTREAM"
+            git_bool async && "$MKIT_ASYNC" && echo async
+            "$MKIT_IN_CI" && test -z "$MKIT_UPSTREAM" && git_bool async && {
+                warn "branch is out-of sync with upstream; git hash might be misleading" \
+                     "  (hint: if this is due to CI auto-rebase, set MKIT_UPSTREAM to original shorthash)"
+            }
+        fi
+        git_bool dirty && echo dirty
+    } | paste -sd.
+}
+
+make_suffix() {
+    local bmeta
+    bmeta=$(make_bmeta)
+    test -n "$bmeta" || return 0
+    echo "+$bmeta"
+}
+
 semver() {
     #
     # Build proper SemVer version string
     local xyz           # base version string
     local prerl         # pre-release keyword (from mkit.ini, eg. 'beta')
     local latest_tag    # latest git tag
-    local brname        # current branch name
-    local ghash         # current commit short hash
-    local is_tagged=T   # T if tagged (clean, no metadata), F if devel
-    local is_dirty=F    # F if dirty, T if clean
     local stamp         # timestamp or nothing (see $MKIT_TSTAMP)
     local suffix        # version suffix
     prerl=$(ini 1value project:prerl)
         *)  warn "bad form of last tag, using base version from mkit.ini: tag is '$latest_tag'"
             xyz=$(ini 1value project:version) ;;
     esac
-    if ! git describe --tags --exact-match HEAD >&/dev/null;
-    then    # we are at a later commit than the last tag
-        is_tagged=F
-        brname=$(git_fact current_branch | sed 's/[^[:alnum:]]/_/g')
-        ghash=$(git_fact latest_sha)
-    fi
-    git_bool dirty && is_dirty=T
-    case "$is_dirty:$is_tagged:$stamp" in
-        F:T:*)  suffix=""                                 ;;
-        T:T:)   suffix="+dirty"                           ;;
-        T:T:*)  suffix="+t$stamp.dirty"                   ;;
-        F:F:)   suffix="+$brname.g$ghash"                 ;;
-        F:F:*)  suffix="+t$stamp.$brname.g$ghash"         ;;
-        T:F:)   suffix="+$brname.g$ghash.dirty"           ;;
-        T:F:*)  suffix="+t$stamp.$brname.g$ghash.dirty"   ;;
-        *)      suffix=MKIT_BUG
-                warn "MKIT_BUG: bad dirt/commit detection" ;;
-    esac
+    suffix=$(make_suffix)
     test -n "$prerl" && suffix="-$prerl$suffix"
     echo "$xyz$suffix"
 }

utils/mkit/include/ini.sh

         ((Depth++))
         debug_var line_todo
         test "$Depth" -le "$MaxDepth" || {
-            warn "expansion error: reached maximum depth: $Depth > $MaxDepth"
-            warn "    original line: $line_orig"
-            warn "    expanded line: $line_todo"
+            warn "expansion error: reached maximum depth: $Depth > $MaxDepth" \
+                 "    original line: $line_orig" \
+                 "    expanded line: $line_todo"
             return 3
         }
         line_done=$(__ini_expandln_once "$line_todo")
         ipath=${ref#[}; ipath=${ipath%]}
         value=$(ini 1value "$ipath")
         debug_var line ref ipath value
-        line=$(sed "s|\\[$ipath\\]|$value|" <<<"$line")
+        line=${line//"[$ipath]"/"$value"}
     done
     echo "$line"
 }
 
 __ini_grepkey() {
     #
-    # Read key from a section
+    # Read key from a normalized `key=value` section
     #
     local wnt=$1    # wanted key
     grep '.' \
-      | sed -e 's/ *= */=/; s/ +$//; s/^//;' \
       | grep -e "^$wnt=" \
       | cut -d= -f2- \
       | __ini_maybe_expand
     #
     local wnt=$1                    # wanted path
     local wntkey=${wnt##*:}         # ^^ key part
-    local wntsec=${wnt%:$wntkey}    # ^^ section part
+    local wntsec=${wnt%:"$wntkey"}  # ^^ section part
     local override                  # ENV override (only ENV section)
     if test "$wntsec" = 'ENV'; then
         override=${!wntkey}
     grep '.' \
       | while read -r line; do
             case "$line" in
-                \[$wnt\]) ok=true;  continue ;;
-                \[*\])    ok=false; continue ;;
+                \["$wnt"\]) ok=true;  continue ;;
+                \[*\])      ok=false; continue ;;
             esac
             $ok || continue
             printf -- '%s\n' "$line"
         done \
-      | sed -e 's/ *= */=/; s/ +$//; s/^//;'
+      | grep '^[[:space:]]*[^[:space:]:][^:]*[[:space:]]*[=]' \
+      | sed -e 's/[[:space:]]*=[[:space:]]*/=/; s/[[:space:]]*$//; s/^[[:space:]]*//;'
 }
 
 __ini_lskeys() {
     esac
     __ini_body | $fn "$arg" | $limit
 }
-
-update_version() {
-    #
-    # Change project:version in mkit.ini at path $2 to value $1
-    #
-    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;
-        foreach (<STDIN>) {
-            if      ($done) { print; next; }
-            elsif   (m/\[project\]/) { $hit++; print; next; }
-            elsif   (m/\[/) { $hit = 0; print; next; }
-            elsif   ($hit) { s/\bversion\b( *)=( *).*/version$1=$2$ARGV[0]/ and $done++; print; }
-            else { print; next; }
-        }
-    ' "$version" >"$tmp" || die "failed to update version in mkit.ini"
-    mv "$tmp" "$inifile"
-}

utils/mkit/include/mkit.sh

 # MKit - simple install helper
 # See LICENSE file for copyright and license details.
 
+_MKIT_IMPORTED=""
+
 die() {
     #
     # Exit with message and non-zero exit status
     #
     local modname=$1
     local modpath
+    test "$modname" == mkit && die "cannot re-import core module: $modname"
+    __mkit__is_imported "$modname" && return 0
     modpath="$MKIT_DIR/include/$modname.sh"
     test -f "$modpath" || die "no such module: $modpath"
     bash -n "$modpath" || die "bad syntax: $modpath"
-    #shellcheck disable=SC1090
+    #shellcheck disable=SC1090,SC1091
     . "$modpath" || die "failed to import: $modname"
+    _MKIT_IMPORTED+=":$modname"
 }
 
-mkit_import build
-mkit_import deploy
-mkit_import release
-mkit_import ini
-
-__valid_targets() {
-    #
-    # List valid routes
-    #
-    echo _mkit_data
-    echo build
-    echo clean
-    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
+__mkit__is_imported() {
+    #
+    # True if module $1 is already imported
+    #
+    local modname=$1
+    grep -qw -e "$modname" <<<"$_MKIT_IMPORTED"
 }
 
+mkit_import ini
+mkit_import target
+
 debug() {
     #
     # Print debug message
     #
     # True if version $1 matches our version
     #
-    # If our x is 0, check first two fragments, otherwise check just
-    # the x.  Fragments must equal.
+    # We're following a particular convention described in SemVer
+    # issue #363:
+    #
+    #     https://github.com/semver/semver/issues/363
+    #
+    # In short: If our X is 0, check first two fragments, otherwise
+    # check just the x.  Fragments must equal.
     #
     local their_ver=$1      # their version
     local our_x             # our X
     local our_y             # our Y
+    local our_z             # our z
     local their_x           # their X
     local their_y           # their Y
-    their_x=${their_ver%%.*}
-    their_y=${their_ver##$their_x.}
-    their_y=${their_y%%.*}
-    our_x=${MKIT_VERSION%%.*}
-    our_y=${MKIT_VERSION##$our_x.}
-    our_y=${our_y%%.*}
-    debug_var MKIT_VERSION our_x our_y their_ver their_x their_y
-    test "$their_x" -eq "$our_x" || return 1
-    test "$our_x" -eq 0 && {
-        test "$their_y" = "$our_y"
-        return $?
+    local their_z           # their Z
+    local diff_x='='        # difference in X: '=' for equal, 'o' for different
+    local diff_y='='        #  ^^ ...... in Y
+    local diff_z='='        #  ^^ ...... in Z
+    read -r their_x their_y their_z <<<"$(__parse_ver_xyz "$their_ver")" || die
+    read -r our_x   our_y   our_z   <<<"$(__parse_ver_xyz "$MKIT_VERSION")" || die
+    test "$their_x" -eq "$our_x" || diff_x=o
+    test "$their_y" -eq "$our_y" || diff_y=o
+    test "$their_z" -eq "$our_z" || diff_z=o
+    debug_var MKIT_VERSION our_x our_y our_z their_ver their_x their_y their_z diff_x diff_y diff_z
+    case $our_x.$our_y:$diff_x.$diff_y.$diff_z in
+        *.*:=.=.=)  return 0 ;;
+        *.*:o.?.?)  return 1 ;;
+        0.0:=.=.o)  __compver_hint_async ;;
+        0.*:=.=.?)  __compver_hint_async ;;
+        0.*:=.o.?)  return 1 ;;
+        *.*:=.=.o)  __compver_hint_async ;;
+        *)          warn "MKit bug while comparing versions!" \
+                         " .. MKit could not handle version difference; here's dump:" \
+                         " ...... MKIT_VERSION=$MKIT_VERSION" \
+                         " ...... their_ver=$their_ver" \
+                         " ...... our_x=$our_x our_y=$our_y our_z=$our_z" \
+                         " ...... their_x=$their_x their_y=$their_y their_z=$their_z" \
+                         " ...... diff_x=$diff_x diff_y=$diff_y diff_z=$diff_z"
+                    return 1 ;;
+    esac
+}
+
+__parse_ver_xyz() {
+    #
+    # Print space-separated X, Y and Z from version $1
+    #
+    local ver=$1
+    local xyz
+    xyz=$(grep -oE '^[0-9]+[.][0-9]+[.][0-9]+' <<<"$ver")
+    test -n "$xyz" || {
+        warn "could not parse version: $ver"
     }
-    return 0
+    echo "${xyz//./ }"
+}
+
+__compver_hint_async() {
+    #
+    # Warn about the version being async
+    #
+    # Versions where later fragments are different are considered
+    # compatible, but when MKit is updated, the best practice is
+    # to consult the changelog and see if fixes or new features
+    # enable optimizing or removing workarounds from the mkit.ini
+    # file.
+    #
+    # For that reason we will inform the maintainer about this
+    # fact.
+    #
+    # Because in typical MKit usage the MKit itself is embedded
+    # in the same git repository as the file, it should be easy
+    # to maintain the synchronicity.
+    #
+    warn "hint: mkit.ini version is out of sync: MKit: $MKIT_VERSION, mkit.ini: $their_ver" \
+         "hint:  .. To hide this hint, consider updating mkit.ini based" \
+         "hint:  .. on changes between these versions and update version" \
+         "hint:  .. directive (\`#mkit version=..\`) to match MKit."
 }
 
 __chkiniversion() {
         {
             head -3 "$MKIT_INI"
             tail -3 "$MKIT_INI"
-        } | grep -m 1 -E '^# *mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
+        } | grep -m 1 -E '^#mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
     )
     test -n "$ver_line" \
-     || die "version mark ('#mkit version=x.y.z') not found in: $MKIT_INI"
+     || die "version directive ('#mkit version=x.y.z') not found in: $MKIT_INI"
     their_ver="$(tr -d '[:blank:]v' <<<"${ver_line##*=}")"
     __compver "$their_ver" \
      || die "bad mkit.ini version: $their_ver does not match $MKIT_VERSION"
     $MKIT_DRY && MKIT_DEBUG=true
     #shellcheck disable=SC2034
     MKIT_PROJ_PKGNAME=$(ini 1value "project:pkgname")
+    test -n "$MKIT_PROJ_PKGNAME" || die "failed to determine pkgname: project:pkgname in $MKIT_INI"
     test -f "$MKIT_INI" || die "cannot find mkit.ini: $MKIT_INI"
     __chkiniversion
 }
 
-route() {
-    #
-    # Call correct function based on $1
-    #
-    if __valid_targets | grep -qwx "^$1"; then
-        "$1"
-    else
-        {
-            echo "usage: $(basename "$0") TARGET"
-            echo
-            echo "valid targets:"
-            __valid_targets | sed 's/^/    /'
-        } >&2
-    fi
-}
-
 warn() {
     #
     # Print warning message
     #
-    echo "$@" >&2
+    printf '%s\n' "$@" >&2
 }

utils/mkit/include/plugin.sh

+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
+mkit_import util
+
+plugin__lspaths() {
+    #
+    # List existing paths from $MKIT_PLUGINPATH
+    #
+    local path
+    debug_var MKIT_PLUGINPATH
+    tr ':' '\n' <<<"$MKIT_PLUGINPATH" \
+      | while read -r path; do
+            debug_var path
+            test -d "$path" || continue
+            echo "$path"
+        done
+}
+
+plugin__ls() {
+    plugin__lspaths \
+      | while read -r path; do
+            debug_var path
+            find "$path" -mindepth 1 -maxdepth 1 -printf '%P\n'
+        done
+}
+
+plugin__option_bool() {
+    #
+    # Safely load boolean option $1
+    #
+    local name=$1
+    __plugin__option_safeload \
+        "$name" \
+        "util__isa_bool" \
+        "not a boolean (true|false)"
+}
+
+plugin__option_enum() {
+    #
+    # Safely load enum option $1, allowing values $2..
+    #
+    __plugin__check_call || return 5
+    local name=$1; shift
+    local allowed_values=("$@")
+    local value
+    local desc_allowed
+    value=$(plugin__option_single "$name")
+    debug_var name value
+    test -n "$value" || return 1
+    util__isa_enum "$value" "${allowed_values[@]}" || {
+        desc_allowed=$(util__join "|" "${allowed_values[@]}")
+        warn "not one of supported values ($desc_allowed): $name = $value"
+        return 3
+    }
+    echo "$value"
+}
+
+plugin__option_multi() {
+    #
+    # Print multi-line plugin option $1
+    #
+    __plugin__check_call || return 5
+    local name=$1
+    ini values "options:$_MKIT__PLUGIN__NAME:$name" \
+      | util__gate_printable
+}
+
+plugin__option_single() {
+    #
+    # Print single-line plugin option $1
+    #
+    __plugin__check_call || return 5
+    local name=$1
+    ini 1value "options:$_MKIT__PLUGIN__NAME:$name" \
+      | grep .
+}
+
+plugin__option_int() {
+    #
+    # Safely load boolean option $1
+    #
+    local name=$1
+    __plugin__option_safeload \
+        "$name" \
+        "util__isa_int" \
+        "not an integer"
+}
+
+plugin__option_name() {
+    #
+    # Safely load boolean option $1
+    #
+    local name=$1
+    __plugin__option_safeload \
+        "$name" \
+        "util__isa_name" \
+        "not a valid name (alphanumeric, starting with letter)"
+}
+
+plugin__option_posint() {
+    #
+    # Safely load boolean option $1
+    #
+    local name=$1
+    __plugin__option_safeload \
+        "$name" \
+        "util__isa_posint" \
+        "not a positive integer"
+}
+
+plugin__path() {
+    #
+    # Print path to plugin file $1
+    #
+    local name=$1
+    local binpath
+    plugin__lspaths \
+      | while read -r path; do
+            binpath="$path/$name"
+            debug_var binpath
+            test -x "$binpath" || continue
+            echo "$binpath"
+        done
+}
+
+plugin__handle() {
+    #
+    # Run method $2 of plugin $1
+    #
+    local _MKIT__PLUGIN__NAME=$1
+    local method=$2
+    local require=true
+    local path
+    local fn
+    test "${method:0:1}" == "." && {
+        require=false
+        method=${method:1}
+    }
+    fn=${_MKIT__PLUGIN__NAME}__${method}
+    path=$(plugin__path "$_MKIT__PLUGIN__NAME")
+    test -n "$path" || die "plugin not found: $_MKIT__PLUGIN__NAME"
+    bash -n "$path" || die "syntax errors in plugin file: $path"
+    #shellcheck disable=SC1090
+    . "$path" || die "error importing plugin: $_MKIT__PLUGIN__NAME at $path"
+    type -t "$fn" | grep -qw function || {
+        $require && die "missing handler: $fn() in plugin $_MKIT__PLUGIN__NAME at $path"
+        debug "SILENTLY SKIPPING UNDEFINED HANDLER: $fn() in $_MKIT__PLUGIN__NAME at $path"
+        return 0
+    }
+    debug "RUNNING HANDLER"
+    debug_var fn
+    "$fn"
+}
+
+plugin__isvalid() {
+    #
+    # True if plugin $1 is valid
+    #
+    local plugin=$1
+    plugin__ls | grep -qwxe "$plugin"
+}
+
+__plugin__check_call() {
+    #
+    # Check that this call is valid
+    #
+    local func=${FUNCNAME[1]}
+    local caller=${FUNCNAME[2]}
+    test -n "$_MKIT__PLUGIN__NAME" && return 0
+    warn "illegal call: $func() from $caller() _MKIT__PLUGIN__NAME=$_MKIT__PLUGIN__NAME" \
+         "  hint: are we inside plugin?"
+    return 3
+}
+
+__plugin__option_safeload() {
+    #
+    # Safely load option $1 with validator $2 and error message $3
+    #
+    __plugin__check_call || return 5
+    local name=$1
+    local validator=$2
+    local msg=$3
+    local value
+    value=$(plugin__option_single "$name")
+    debug_var name value
+    test -n "$value" || return 1
+    "$validator" "$value" || {
+        warn "$msg: $name=$value"
+        return 3
+    }
+    echo "$value"
+}

utils/mkit/include/release.sh

 mkit_import ini
 mkit_import facts
 
-__bump_version() {
+__release__bump_version() {
     #
     # Bump version on stdin by level $1 (x, y or z)
     #
     echo "$new"
 }
 
-__relck() {
+__release__check() {
     #
     # Die if blocking condition $1 is detected
     #
              || die "last change must be version bump in mkit.ini"
             ;;
         no_wip)
-            git_fact reldiff \
-              | grep '^....... WIP ' \
+            git_fact reldiff_brief \
+              | grep -iE \
+                    -e '^[^ ]+ WIP ' \
+                    -e '^[^ ]+ WIP$'  \
+                    -e '^[^ ]+ WIP:'  \
              && die "WIP commit since $(git_fact latest_tag)"
             ;;
         ini_version)
-            oracle=$(git_fact latest_version | __bump_version "$rlevel")
+            oracle=$(git_fact latest_version | __release__bump_version "$rlevel")
             ini 1value project:version  \
               | grep -qFxe "$oracle" \
              || die "new version not in mkit.ini: $oracle"
     local relsrc        # release source branch (if any)
     local reldst        # release destination branch (if any)
 
-    __relck git_present
-    __relck at_relsrc
-    __relck not_dirty
-    __relck tags_ok
-    __relck vbump_hot
-    __relck no_wip
-    __relck ini_version
+    __release__check git_present
+    __release__check at_relsrc
+    __release__check not_dirty
+    __release__check tags_ok
+    __release__check vbump_hot
+    __release__check no_wip
+    __release__check ini_version
 
-    newtag=$(git_fact latest_version | __bump_version "$rlevel" | git_ver2tag )
+    newtag=$(git_fact latest_version | __release__bump_version "$rlevel" | git_ver2tag )
     set -e
     debug_var newtag
     $MKIT_DRY && return
     # Generate message for annotated tag
     #
     # The last commit before issuing a release must be "Bump version" commit
-    # suggested by _vbump_gitmsg() and  manually edited by user.  Since the
+    # suggested by __release__vbump_gitmsg() and  manually edited by user.  Since the
     # commit contains changelog, this function just uses the message body.
     #
     # The sort message (first line) is replaced with a nicer one (with project
       | tail -n +3
 }
 
-__vbump() {
+__release__update_ini() {
+    #
+    # Change project:version in mkit.ini at path $2 to value $1
+    #
+    local version=$1    # new version
+    local inifile=$2    # mkit.ini path
+    local tmp           # mkit.ini cache
+    tmp=$(mktemp -t mkit.__release__update_ini.XXXXXXXX)
+    <"$inifile" perl -e '
+        my $hit = 0;
+        my $done = 0;
+        foreach (<STDIN>) {
+            if      ($done) { print; next; }
+            elsif   (m/\[project\]/) { $hit++; print; next; }
+            elsif   (m/\[/) { $hit = 0; print; next; }
+            elsif   ($hit) { s/\bversion\b( *)=( *).*/version$1=$2$ARGV[0]/ and $done++; print; }
+            else { print; next; }
+        }
+    ' "$version" >"$tmp" || die "failed to update version in mkit.ini"
+    mv "$tmp" "$inifile"
+}
+
+__release__vbump() {
     #
     # Do version bump at level $1
     #
     local rlevel=$1     # bump level (x, y or z)
     local nextver       # version after the bump
     local cache         # cache for the message
-    __relck git_present
-    __relck at_relsrc
-    __relck not_dirty
-    nextver=$(ini 1value project:version | __bump_version "$rlevel")
+    __release__check git_present
+    __release__check at_relsrc
+    __release__check not_dirty
+    nextver=$(ini 1value project:version | __release__bump_version "$rlevel")
     debug_var nextver
     $MKIT_DRY && return
-    update_version "$nextver" mkit.ini \
+    __release__update_ini "$nextver" mkit.ini \
       || die "failed to update version in mkit.ini"
     git add mkit.ini \
       || die "failed to add mkit.ini to the index"
-    cache=$(mktemp -t "mkit._vbump_gitmsg.XXXXXXXX")
-    _vbump_gitmsg "$nextver" > "$cache"
+    cache=$(mktemp -t "mkit.__release__vbump_gitmsg.XXXXXXXX")
+    __release__vbump_gitmsg "$nextver" > "$cache"
     git commit -e -F "$cache"   # note: reading from stdin will break vim
     rm "$cache"
 }
 
-_vbump_gitmsg() {
+__release__vbump_gitmsg() {
     #
     # Compose git message template for 'Bump version' commit
     #
     #
     # Perform version bump on Z level
     #
-    __vbump z
+    __release__vbump z
 }
 
 vbump_x() {
     #
     # Perform version bump on X level
     #
-    __vbump x
+    __release__vbump x
 }
 
 vbump_y() {
     #
     # Perform version bump on Y level
     #
-    __vbump y
+    __release__vbump y
 }
 
 vbump_z() {
     #
     # Perform version bump on Z level
     #
-    __vbump z
+    __release__vbump z
 }

utils/mkit/include/target.sh

+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
+mkit_import plugin
+
+target__ls() {
+    #
+    # List valid routes
+    #
+    target__map | cut -d' ' -f1
+}
+
+target__map() {
+    #
+    # List valid routes and corresponding module:functions
+    #
+    #shellcheck disable=SC2291
+    {
+        echo _mkit_builddata        build:_mkit_builddata
+        echo _mkit_inidata          build:_mkit_inidata
+        echo _mkit_metadata         build:_mkit_metadata
+        echo _mkit_show_builddata   build:_mkit_show_builddata
+        echo _mkit_show_metadata    build:_mkit_show_metadata
+        echo build                  build:build
+        echo clean                  build:clean
+        echo dist                   build:dist
+        echo install                deploy:install
+        echo release                release:release
+        echo release_x              release:release_x
+        echo release_y              release:release_y
+        echo release_z              release:release_z
+        echo uninstall              deploy:uninstall
+        echo vbump                  release:vbump
+        echo vbump_x                release:vbump_x
+        echo vbump_y                release:vbump_y
+        echo vbump_z                release:vbump_z
+    }
+}
+
+target__isvalid() {
+    #
+    # True if target $1 is valid
+    #
+    local target=$1
+    target__map | grep -qwe "^$target"
+}
+
+target__route() {
+    #
+    # Call correct function based on $1
+    #
+    local target=$1
+    local es
+    if target__isvalid "$target"; then
+        target__run "$target"; es=$?
+    elif plugin__isvalid "$target"; then
+        plugin__handle "$target" main; es=$?
+    else
+        {
+            echo "usage: $(basename "$0") TARGET"
+            echo
+            echo "valid targets (built-in):"
+            target__ls | sed 's/^/    /'
+            echo
+            echo "valid targets (from plugins):"
+            plugin__ls | sed 's/^/    /'
+        } >&2
+        es=2
+    fi
+    return "$es"
+}
+
+target__run() {
+    #
+    # Run target $1
+    #
+    local target=$1
+    local module
+    local fn
+    read -r module fn <<<"$(
+        target__map \
+          | tr : ' ' \
+          | grep -we "^$target" \
+          | cut -d' ' -f2-
+    )"
+    debug_var target module fn
+    mkit_import "$module"
+    "$fn"
+}

utils/mkit/include/util.sh

+#!/bin/bash
+
+util__gate_printable() {
+    #
+    # True if stdin had non-whitespace values
+    #
+    local value
+    value=$(cat)
+    grep -q '[[:print:]]' <<<"$value" || return 1
+    echo "$value"
+}
+
+util__isa_bool() {
+    #
+    # True if $1 is a boolean value
+    #
+    test "$1" == false && return 0
+    test "$1" == true && return 0
+    return 1
+}
+
+util__isa_enum() {
+    #
+    # True if $1 is one of $2..
+    #
+    local value=$1; shift
+    local alloweds=("$@")
+    local allowed
+    for allowed in "${alloweds[@]}"; do
+        test "$value" == "$allowed" && return 0
+    done
+    return 1
+}
+
+util__isa_int() {
+    #
+    # True if $1 is an integer
+    #
+    # Note that $1 does not have to be decimal; in POSIX shells,
+    # eg. 0xf1 is a valid hexadecimal integer and 0755 is a valid
+    # octal integer.
+    #
+    {
+        test -z "$1"    && return 1
+        test "$1" -ge 0 && return 0
+        return 1
+    } 2>/dev/null
+}
+
+util__isa_name() {
+    #
+    # True if $1 is a name in most languages
+    #
+    echo "$1" | grep -qx '[[:alpha:]_][[:alnum:]_]*'
+}
+
+util__isa_posint() {
+    #
+    # True if $1 is a positive integer
+    #
+    {
+        test -z "$1"    && return 1
+        test "$1" -ge 0 && return 0
+        return 1
+    } 2>/dev/null
+}
+
+util__join() {
+    #
+    # Use $1 to join items $2..
+    #
+    local dlm=$1; shift
+    local items=("$@")
+    local item
+    local head=true
+    for item in "${items[@]}"; do
+        $head || echo -n "$dlm"
+        $head && head=false
+        echo -n "$item"
+    done
+}
+
+util__loadarr() {
+    #
+    # Save output lines from command $2.. to array named $1
+    #
+    # Usage:
+    #     util__loadarr ARRAY CMD [ARG]..
+    #
+    # Unlike `mapfile -t <<<"$(command)", this produces zero
+    # items if command output was empty.
+    #
+    local __util__arr_fromcmd__oarr=$1; shift
+    local __util__arr_fromcmd__cmd=("$@")
+    local __util__arr_fromcmd__tmp
+    local __util__arr_fromcmd__es
+    __util__arr_val_oarr "$__util__arr_fromcmd__oarr" || return 2
+    __util__arr_fromcmd__tmp=$(mktemp /tmp/util__loadarr.__util__arr_fromcmd__tmp.XXXXX)
+    "${__util__arr_fromcmd__cmd[@]}" > "$__util__arr_fromcmd__tmp"; __util__arr_fromcmd__es=$?
+    mapfile -t "$__util__arr_fromcmd__oarr" <"$__util__arr_fromcmd__tmp"
+    rm "$__util__arr_fromcmd__tmp"
+    return $__util__arr_fromcmd__es
+}
+
+util__loadenv() {
+    #
+    # Safely load value from envvar $1
+    #
+    local name=$1
+    local value
+    value=${!name}
+    test -n "$value" || return 1
+    echo "$value"
+}
+
+util__loadenv_bool() {
+    #
+    # Safely load integer from envvar $1
+    #
+    local name=$1
+    __util__safe_loadenv \
+        "$name" \
+        util__isa_bool \
+        "not a boolean (true|false): $name=$value"
+}
+
+util__loadenv_enum() {
+    #
+    # Safely load enum from envvar $1, allowing values $2..
+    #
+    local name=$1; shift
+    local allowed_values=("$@")
+    local value
+    local desc_allowed
+    value=${!name}
+    test -n "$value" || return 1
+    util__isa_enum "$value" "${allowed_values[@]}" || {
+        desc_allowed=$(util__join "|" "${allowed_values[@]}")
+        warn "not one of supported values ($desc_allowed): $name = $value"
+        return 3
+    }
+    echo "$value"
+}
+
+util__loadenv_int() {
+    #
+    # Safely load integer from envvar $1
+    #
+    local name=$1
+    __util__safe_loadenv \
+        "$name" \
+        util__isa_int \
+        "not an integer"
+}
+
+util__loadenv_name() {
+    #
+    # Safely load positive integer from envvar $1
+    #
+    local name=$1
+    __util__safe_loadenv \
+        "$name" \
+        util__isa_name \
+        "not a valid name (alphanumeric, starting with letter)"
+}
+
+util__loadenv_posint() {
+    #
+    # Safely load positive integer from envvar $1
+    #
+    local name=$1
+    __util__safe_loadenv \
+        "$name" \
+        util__isa_posint \
+        "not a positive integer"
+}
+
+util__sort_by_length() {
+    #
+    # Sort items on stdin by length
+    #
+    while IFS= read -r item; do
+        echo "${#item} $item"
+    done \
+      | sort -n \
+      | cut -d' ' -f2-
+}
+
+util__warnbox() {
+    #
+    # Emit warning $2 box-decorated with char $1, follow by lines $3..
+    #
+    local char=$1; shift
+    local subj=$1; shift
+    local body=("$@")
+    case "${#body[*]}" in
+        0)  __util__warnbox1 "$char" "$subj" ;;
+        *)  __util__warnbox_sub "$char" "$subj" "${body[@]}" ;;
+    esac
+}
+
+__util__warnbox1() {
+    #
+    # Emit warning $2 box-decorated with char $1
+    #
+    local char=$1
+    local msg=$2
+    local line
+    local midline="$char$char $msg $char$char"
+    line=$(__util__make_hr "$char" "$midline")
+    warn "$line" \
+         "$midline" \
+         "$line"
+}
+
+__util__warnbox_sub() {
+    #
+    # Emit warning $2 box-decorated with char $1, follow by lines $3..
+    #
+    local char=$1; shift        # decoration character
+    local subj=$1; shift        # local of the message subject
+    local body=("$@")           # lines of the message body
+    local longest               # longest line from subject and body
+    local width                 # length of ^^
+    local hr                    # horizontal ruler
+    local vr="$char$char"       # vertical ruler point
+    local padded_body           # body lines; padded
+    local padded_subj           # body line; padded
+    local line                  # each of ^^^
+    local out_lines=()          # final lines
+    longest=$(__util__longest "$subj" "${body[@]}")
+    width=${#longest}
+    padded_subj=$(__util__rpad "${width}" "$subj")
+    util__loadarr padded_body __util__rpad "$width" "${body[@]}"
+    debug_var longest width padded_subj padded_body
+    hr=$(__util__make_hr "$char" "$vr $longest $vr")
+    out_lines+=(
+        "$hr"
+        "$vr $padded_subj $vr"
+        "$hr"
+    )
+    for line in "${padded_body[@]}"; do
+        out_lines+=("$vr $line $vr")
+    done
+    out_lines+=("$hr")
+    warn "${out_lines[@]}"
+}
+
+__util__longest() {
+    #
+    # Choose longest of $@
+    #
+    printf '%s\n' "$@" \
+      | util__sort_by_length \
+      | tail -n 1
+}
+
+__util__make_hr() {
+    #
+    # Repeat char $1 to the length of $2
+    #
+    local char=$1
+    local stuff=$2
+    local length=${#stuff}
+    __util__repchar "$char" "$length"
+}
+
+__util__repchar() {
+    #
+    # Repeat char $1 $2 times
+    #
+    local char=$1
+    local times=$2
+    local togo=$times
+    while test "$togo" -gt 0; do
+        echo -n "$char"
+        ((togo--))
+    done
+    echo
+}
+
+__util__rpad() {
+    #
+    # Right-pad all of $2.. to length $1 with space
+    #
+    local wid=$1; shift
+    local rest=("$@")
+    printf "%-${wid}s"'\n' "${rest[@]}"
+}
+
+__util__safe_loadenv() {
+    #
+    # Safely load envvar $1 with validator $2 and error message $3
+    #
+    local name=$1
+    local validator=$2
+    local msg=$3
+    local value
+    value=${!name}
+    debug_var name value
+    test -n "$value" || return 1
+    "$validator" "$value" || {
+        warn "$msg: $name=$value"
+        return 3
+    }
+    echo "$value"
+}
+
+__util__isa_name() {
+    #
+    # True if $1 is a name in most languages
+    #
+    echo "$1" | grep -qx '[[:alpha:]_][[:alnum:]_]*'
+}
+
+__util__arr_val_oarr() {
+    #
+    # Validate output array named $1
+    #
+    local name=$1
+    __util__isa_name "$name" || { warn "invalid array name: $name"; return 2; }
+}

utils/mkit/include/vars.sh

 # See LICENSE file for copyright and license details.
 
 
+#
+# Add 'async' tag to build meta-data (true|false)
+#
+# If 'true' and during the version computation git branch is behind
+# or ahead its remote counterpart, build meta-data (part after '+'
+# sign) will contain word 'async'.
+#
+# This is to warn testers and developers when build was done after
+# automatic rebase done by CI system.
+#
+# Defaults to 'true'.
+#
+MKIT_ASYNC=${MKIT_ASYNC:-true}
+
 #
 # Bump size (for vbump_? and release_?)
 #
 #
 MKIT_DRY=${MKIT_DRY:-false}
 
+#
+# Is MKit running in CI (true|false)
+#
+# If MKit is running in CI, it's recommended to set this to 'true'
+# to enable one or more useful warnings.
+#
+# Defaults to 'false'.
+#
+MKIT_IN_CI=${MKIT_IN_CI:-false}
+
 #
 # Path to mkit.ini
 #
 #
 MKIT_LOCAL=${MKIT_LOCAL:-.mkit}
 
+#
+# Paths to MKit plugins
+#
+# Colon-separated list of paths where MKit will recognize
+# plug-ins.
+#
+MKIT_PLUGINPATH=${MKIT_PLUGINPATH:-$MKIT_DIR/plugins:$MKIT_LOCAL/plugins:$MKIT_DIR-plugins}
+
 #
 # Package name
 #
 #
 MKIT_TSTAMP=${MKIT_TSTAMP:-ctime}
 
+#
+# Upstream hash to add to build meta-data
+#
+# If set to non-empty string, it must represent a short-hash of
+# upstream commit on which local branch was automatically rebased
+# before build.
+#
+# If CI system automatically rebases branches, the resulting short-hash
+# (appearing with `g` prefix) will be meaningless, and might be
+# misleading -- testers and developers might see the build as coming
+# from an unknown source.
+#
+# In that case, it's strongly recommended for CI to set this to the
+# original pushed short-hash before the rebase.  Resulting meta-data
+# will contain both hashes, allowing users to pair test results with
+# original push.  The appearance of the extra hash will also warn
+# about the fact that the rebase took place.
+#
+# For example, if developer pushed branch 'foo' that pointed to
+# `5faf551`, and CI system rebased it, altering the HEAD to
+# `bb4baa4`, by default the version would look like:
+#
+#     0.0.1+t202103011224.foo.gbb4baa4
+#
+# This would be meaningless for testing, as the `bb4baa4` hash is
+# completely temporary and unknonwn.
+#
+# However, a conformant CI should set `MKIT_UPSTREAM=5faf551`, which
+# will result in version like:
+#
+#     0.0.1+t202103011224.foo.gbb4baa4.u5faf551
+#
+# which still has technically correct git hash after `g`, but contains
+# the original hash as pushed after `u`.
+#
+# Defaults to empty value.
+#
+MKIT_UPSTREAM=${MKIT_UPSTREAM:-}
+
 #
 # This MKit version
 #
-MKIT_VERSION=0.0.40
+MKIT_VERSION=0.1.3

utils/mkit/make

-#!/bin/bash
-#shellcheck disable=SC2034
-# mkit - simple install helper
-# See LICENSE file for copyright and license details.
-
-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
-}
-
-#
-# Path to MKit dir (where 'include' is)
-#
-MKIT_DIR=${MKIT_DIR:-$(dirname "$0")}
-
-
-init_core
-
-case "$1" in
-    -V|--version-semver)    echo "$MKIT_VERSION"; exit 0 ;;
-    --version)              echo "Mkit (Simple Makefile target helper) $MKIT_VERSION"
-                            exit 0 ;;
-esac
-
-mkit_init
-
-route "$@"

utils/mkit/mkit

+#!/bin/bash
+#shellcheck disable=SC2034
+# mkit - simple install helper
+# See LICENSE file for copyright and license details.
+
+usage() {
+    print_help >&2
+    test $# -gt 0 && {
+        printf >&2 '%s\n' "" "$@"
+    }
+    exit 2
+}
+
+print_help() {
+    local self=${0##*/}
+    local lines=(
+        "usage:"
+        "  $self TARGET"
+        "  $self -i|--ini-1value PATH"
+        "  $self -I|--ini-values PATH"
+        "  $self --list-plugins"
+        "  $self --list-targets"
+        "  $self -V|--version-semver"
+        "  $self --version"
+        ""
+        "commands:"
+        "   TARGET          build target TARGET"
+        "   -i PATH         print single-line value at INI path PATH"
+        "                   (ignore all but last instance of this"
+        "                   value in the INI)"
+        "   -I PATH         like -i, but list all instances, one per line"
+        "                   (multi-line values)"
+        "   --list-plugins  print list of found plugins and exit"
+        "   --list-targets  print list of valid targets and exit"
+        "   -V|--version    print version (in SemVer format) and exit"
+        "   --help          print this help text and exit"
+        ""
+    )
+    printf '%s\n' "${lines[@]}"
+    echo "valid targets (built-in):"
+    target__ls | sed 's/^/    /'
+    echo
+    echo "valid targets (from plugins):"
+    plugin__ls | sed 's/^/    /'
+}
+
+
+init_core() {
+    #
+    # Load core module (or die)
+    #
+    #shellcheck disable=SC1090,SC1091
+    . "$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")}
+
+just_ini() {
+    #
+    # Just do one mkit.ini operation $1
+    #
+    local op=$1
+    local key=$2
+    mkit_init || return $?
+    ini "$op" "$key"
+}
+
+main () {
+    init_core
+    case "$1" in
+        -V|--version)           echo "$MKIT_VERSION"; exit 0 ;;
+        -i|--ini-1value)        just_ini 1value "$2"; exit $? ;;
+        -I|--ini-values)        just_ini values "$2"; exit $? ;;
+        --ini-lskeys)           just_ini lskeys "$2"; exit $? ;;
+        --ini-lssect)           just_ini lssect "$2"; exit $? ;;
+        --ini-sec)              just_ini sec    "$2"; exit $? ;;
+        --list-targets)         mkit_init; target__ls; plugin__ls; exit 0 ;;
+        --list-plugins)         mkit_init; plugin__ls; exit 0 ;;
+        --help)                 print_help; exit 0 ;;
+        -*)                     usage "unknown argument: $1" ;;
+    esac
+    test "$#" -gt 0 || usage
+    mkit_init
+    target__route "$@"
+}
+
+main "$@"

utils/mkit/mkit.mk

 
 export MKIT_DIR
 
+plugins := $(shell "$(MKIT_DIR)"/mkit --list-plugins)
+
+
 all: build
 
-_mkit_data:
-	@"$(MKIT_DIR)"/make _mkit_data
+_mkit_builddata: _mkit_metadata
+	@"$(MKIT_DIR)"/mkit _mkit_builddata
 
-build:
-	@"$(MKIT_DIR)"/make build
+_mkit_inidata:
+	@"$(MKIT_DIR)"/mkit _mkit_inidata
 
-clean:
-	@"$(MKIT_DIR)"/make clean
+_mkit_metadata:
+	@"$(MKIT_DIR)"/mkit _mkit_metadata
+
+_mkit_show_metadata: _mkit_metadata
+	@"$(MKIT_DIR)"/mkit _mkit_show_metadata
 
-debstuff: dist
-	@"$(MKIT_DIR)"/make debstuff
+_mkit_show_builddata: _mkit_builddata
+	@"$(MKIT_DIR)"/mkit _mkit_show_builddata
 
-dist: clean
-	@"$(MKIT_DIR)"/make dist
+build: _mkit_builddata
+	@"$(MKIT_DIR)"/mkit build
 
-rpmstuff: dist
-	@"$(MKIT_DIR)"/make rpmstuff
+dist: _mkit_metadata
+	@"$(MKIT_DIR)"/mkit dist
+
+clean:
+	@"$(MKIT_DIR)"/mkit clean
 
 install: all
-	@"$(MKIT_DIR)"/make install
+	@"$(MKIT_DIR)"/mkit install
 
 release:
-	@"$(MKIT_DIR)"/make release
+	@"$(MKIT_DIR)"/mkit release
 
 release_x:
-	@"$(MKIT_DIR)"/make release_x
+	@"$(MKIT_DIR)"/mkit release_x
 
 release_y:
-	@"$(MKIT_DIR)"/make release_y
+	@"$(MKIT_DIR)"/mkit release_y
 
 release_z:
-	@"$(MKIT_DIR)"/make release_z
+	@"$(MKIT_DIR)"/mkit release_z
 
 uninstall:
-	@"$(MKIT_DIR)"/make uninstall
+	@"$(MKIT_DIR)"/mkit uninstall
 
 vbump:
-	@"$(MKIT_DIR)"/make vbump
+	@"$(MKIT_DIR)"/mkit vbump
 
 vbump_x:
-	@"$(MKIT_DIR)"/make vbump_x
+	@"$(MKIT_DIR)"/mkit vbump_x
 
 vbump_y:
-	@"$(MKIT_DIR)"/make vbump_y
+	@"$(MKIT_DIR)"/mkit vbump_y
 
 vbump_z:
-	@"$(MKIT_DIR)"/make vbump_z
+	@"$(MKIT_DIR)"/mkit vbump_z
+
+$(plugins): clean _mkit_metadata
+	@"$(MKIT_DIR)"/mkit $@
 
-.PHONY: all _mkit_data clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z
+.PHONY: all _mkit_builddata _mkit_inidata _mkit_metadata _mkit_show_builddata _mkit_show_metadata clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z $(plugins)

utils/mkit/plugins/debstuff

+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import build
+mkit_import target
+
+debstuff__main() {
+    #
+    # Build Debian stuff (eamed tarball, debian dir)
+    #
+    local version       # package version
+    local debian_skel   # 'debian' folder skeleton
+    local dfsrc         # each source file from ^^
+    local dftgt         # each built packaging file
+    target__run dist || die
+    version=$(build__cached semver)
+
+    # tarball - we should already have by means of 'dist'
+    #
+    mv "${MKIT_PROJ_PKGNAME}-$version.tar.gz" \
+       "${MKIT_PROJ_PKGNAME}_$version.orig.tar.gz" \
+     || die "could not rename tarball"
+    build__record "${MKIT_PROJ_PKGNAME}_$version.orig.tar.gz"
+
+    # read content of each mandatory file from debian_skel
+    #
+    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
+    find "$debian_skel" -type f \
+      | while read -r dfsrc; do
+            dftgt="debian/${dfsrc#"$debian_skel"}"
+            mkdir -p "$(dirname "$dftgt")"
+            build__file "$dfsrc" "$dftgt" debstuff
+        done
+    build__recordr debian
+}

utils/mkit/plugins/pystuff

+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import build
+mkit_import target
+
+pystuff__main() {
+    #
+    # Build setup.py and mkvenv.sh
+    #
+    local ModName           # Python module name
+    local ProjVersion       # MKit project version
+    local Skel              # setup.py skeleton
+    local MkvenvDir         # venv maker: target venv directory
+    local MkvenvScript      # venv maker: script name
+    local MkvenvPost        # venv maker: post commands
+    target__run build || die
+    Skel="$(ini 1value "dist:pystuff")"
+    MkvenvDir=$(__pystuff__load_mkvenv_dir)
+    MkvenvScript=$(__pystuff__load_mkvenv_script)
+    MkvenvPost=$(__pystuff__load_mkvenv_post)
+    ProjVersion=$(build__cached semver)
+    ModName=$(ini 1value macros:__VDK_PYLIB_MODNAME__)
+    build__fact "pystuff/mkvenv_dir" <<<"$MkvenvDir"
+    build__fact "pystuff/mkvenv_script" <<<"$MkvenvScript"
+    test -n "$Skel" || die "dist:pystuff not specified"
+    test -f "$Skel" || die "setup.py template not found: $Skel"
+    __pystuff__make_setup_py
+    __pystuff__make_mkvenv
+}
+
+__pystuff__find_dist() {
+    local candidate
+    candidate=$(
+        find "dist" -maxdepth 1 -mindepth 1 -printf '%P\n' \
+          | grep -m1 -e "$ModName-.*tar.gz"
+    )
+    test -f "dist/$candidate" && echo "dist/$candidate" && return 0
+    #shellcheck disable=SC2016
+    warn "could not find dist package in: dist" \
+         " .. hint: looking for $ModName-*.tar.gz" \
+         ' .. hint: did you run `make pystuff` first?'
+    return 3
+}
+
+__pystuff__make_setup_py() {
+    build__file "$Skel" "setup.py" pystuff
+    build__recordr dist
+    build__recordr "$ModName.egg-info"
+    python3 -m build
+}
+
+__pystuff__load_mkvenv_dir() {
+    #
+    # Safely load directory for the venv
+    #
+    util__loadenv PYSTUFF__VENV_DIR && return 0
+    plugin__option_single "dir" && return 0
+    echo venv
+}
+
+__pystuff__load_mkvenv_script() {
+    #
+    # Safely load command for the venv
+    #
+    util__loadenv PYSTUFF__VENV_SCRIPT && return 0
+    plugin__option_single "mkvenv_script" && return 0
+    echo mkvenv.sh
+}
+
+__pystuff__load_mkvenv_post() {
+    #
+    # Safely load command for the venv
+    #
+    util__loadenv PYSTUFF__VENV_POST && return 0
+    plugin__option_multi "mkvenv_post" && return 0
+}
+
+__pystuff__q() {
+    #
+    # Quote command $@
+    #
+    printf '%q ' "$@";
+    echo
+}
+
+__pystuff__make_mkvenv() {
+    #
+    # Create the mkvenv.sh script
+    #
+    local dist
+    local req
+    dist=$(__pystuff__find_dist) \
+     || die "could not find dist"
+    build__record "$MkvenvScript"
+    {
+        echo "#!/bin/sh -e"
+        echo "#"
+        echo "# created by MKit $MKIT_VERSION pystuff for $ModName-$ProjVersion"
+        echo "#"
+        echo ""
+        __pystuff__q python3 -m venv "$MkvenvDir"
+        __pystuff__q . "$MkvenvDir/bin/activate"
+        python3 "setup.py" --requires \
+          | grep . \
+          | while read -r req; do
+                __pystuff__q python3 -m pip install --force-reinstall "$req"
+            done
+        __pystuff__q python3 -m pip install --force-reinstall "$dist"
+        echo ""
+        echo "echo >&2 'Virtual environment should be ready. run following command:'"
+        echo "echo >&2 ''"
+        echo "echo >&2 '    source venv/bin/activate'"
+        echo "echo >&2 ''"
+        echo "echo >&2 'to activate it.'"
+        test -n "$MkvenvPost" && {
+            echo
+            echo "#"
+            echo "# user POST action ([options:pystuff:mkvenv_post]"
+            echo "#"
+            echo "$MkvenvPost"
+        }
+    } | sed 's/ *$//' >"$MkvenvScript"
+    bash -n "$MkvenvScript" || die "script has syntax errors"
+    chmod +x "$MkvenvScript"
+}

utils/mkit/plugins/rpmstuff

+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import build
+mkit_import target
+
+rpmstuff__main() {
+    #
+    # Build specfile
+    #
+    local specname=$MKIT_PROJ_PKGNAME.spec      # .spec filename
+    local specsrc                               # source of specfile
+    target__run dist || die
+    specsrc="$(ini 1value "dist:rpmstuff")"
+    test -n "$specsrc" || die "dist:rpmstuff not specified"
+    test -f "$specsrc" || die "specfile template not found: $specsrc"
+    __rpmstuff__maybe_prefix_v0 "$specsrc"
+    build__file "$specsrc" "$specname" rpmstuff
+}
+
+__rpmstuff__maybe_prefix_v0() {
+    #
+    # Avoid "normalizes to zero" error
+    #
+    # Scripting on Fedora 38 contains new check, where the version
+    # is not allowed to be 0.0.0.
+    #
+    # We will disable this check for projects where our reported
+    # version is indeed 0.0.0, but only if it's also a devel version,
+    # in which case it has build data.
+    #
+    local file=$1
+    local tmp="$1.__rpmstuff__maybe_prefix_v0.tmp"
+    local version
+    version=$(build__cached semver)
+    case $version in
+        0.0.0+*)
+            warn "disabling zero-version rpmbuild check" \
+                 " .. hint: We're doing this only because we trust" \
+                 " .. hint: that this is an early devel version." \
+                 " .. hint: Make sure to bump at least to 0.0.1" \
+                 " .. hint: before release."
+            ;;
+        *)
+            return 0
+            ;;
+    esac
+    cp -ar "$file" "$tmp"
+    {
+        echo "%define _python_dist_allow_version_zero 1"
+        echo "# ^^ auto-added by mkit rpmstuff for early devel version"
+        echo ""
+        cat "$file"
+    } > "$tmp"
+    mv "$tmp" "$file"
+}

utils/mkit/stub

     #
     # Load core modules (or die)
     #
-    #shellcheck disable=SC1090
+    #shellcheck disable=SC1090,SC1091
     . "$MKIT_DIR/include/mkit.sh" \
      && . "$MKIT_DIR/include/vars.sh" \
      && return 0
             else
                 echo "(Nothing to say about this project.)"
             fi
+            echo ""
+            echo "See MAINTAINERS.md for instructions how to build and"
+            echo "maintain this MKit project."
+            ;;
+
+        MAINTAINERS.md)
+            local heading="$any_name - maintainer instructions"
+            echo "${heading^^}"
+            tr -c '=\n' '=' <<<"$heading"
+            echo ''
+            echo "<!--"
+            echo "    Note: This file has been auto-generated by MKit"
+            echo "    v$MKIT_VERSION when initializing the project."
+            echo "-->"
+            echo ''
+            echo "This project is using MKit for packaging and versioning"
+            echo "meta-data; this file describes how to do basic maintenance"
+            echo "operations."
+            echo ''
+            echo "MKit uses GNU Make as an interface, so all operations are"
+            echo "'make' targets and GNU Make takes care of the dependencies"
+            echo "between them.  For example, to install the project it's enough"
+            echo "to call 'make install'; GNU Make will call 'make built'"
+            echo "automatically if needed."
+            echo ""
+            echo ""
+            echo "Variables"
+            echo "---------"
+            echo ""
+            echo " *  \`DESTDIR\` - root of the installation destination"
+            echo " *  \`PREFIX\` - deployment prefix (often \`/usr\` or"
+            echo "    \`/usr/local\`)"
+            echo " *  \`MKIT_DRY\` - set to \`true\` to prevent MKit from making"
+            echo "    any changes"
+            echo " *  \`MKIT_DEBUG\` - set to \`true\` to have MKit display"
+            echo "    (lots of) debugging information"
+            echo ""
+            echo "See *utils/mkit/include/vars.sh* for full list oof supported"
+            echo "variables. (You can use \`sfdoc utils/mkit/include/vars.sh\`"
+            echo "if you have sfdoc installed.)"
+            echo ""
+            echo ""
+            echo "Building and installation"
+            echo "-------------------------"
+            echo ""
+            echo "These operations are allowed on any branch.  Assets built from"
+            echo "development branches will be marked using distinctive version"
+            echo "number containing timestamp, branch name and commit short-hash."
+            echo ""
+            echo " *  \`make\` - same as \`make build\`"
+            echo " *  \`make build\` - build project files"
+            echo " *  \`make install\` - install project to \`\$DESTDIR\`"
+            echo " *  \`make uninstall\` - uninstall project from \`\$DESTDIR\`"
+            echo " *  \`make rpmstuff\` - create RPM SPEC file and a source"
+            echo "    tarball"
+            echo " *  \`make debstuff\` - create 'debian' directory and a source"
+            echo "    tarball"
+            echo " *  \`make clean\` - remove any previously built assets".
+            echo ""
+            echo ""
+            echo "Versioning"
+            echo "----------"
+            echo ""
+            echo "These operations are only allowed on *release source branch*:"
+            echo ""
+            echo " *  \`make vbump\` - bump version and create bump commit"
+            echo " *  \`make release\` - create release tag"
+            echo ""
+            echo ""
+            echo "Recommended workflow"
+            echo "--------------------"
+            echo ""
+            echo ""
+            echo "### Development and testing ###"
+            echo ""
+            echo "Any branch can be used to create any kind of asset.  Assets"
+            echo "built from development branch will be marked using distinctive"
+            echo "version number in all MKit macros."
+            echo ""
+            echo "Development is done in branches as needed, but one branch"
+            echo "(often called *master*, *main* or *trunk*) is designated as"
+            echo "**release source** branch.  Only maintainer can push into this"
+            echo "branch and this is where maintainer creates the next release."
+            echo ""
+            echo ""
+            echo "### Versioning and releases ###"
+            echo ""
+            echo "After all development branches are merged and project is"
+            echo "considered ready for release, maintainer will create new"
+            echo "release.  This consists of three steps (only two of them are"
+            echo "assisted by MKit):"
+            echo ""
+            echo " 1. \`make vbump\` - will auto-edit [project:version] in"
+            echo "     mkit.ini and start creating **bump commit**."
+            echo ""
+            echo "    **Bump commit** is a special commit which consists of:"
+            echo ""
+            echo "     *  Bump of version in mkit.ini"
+            echo "     *  commit message providing rudimentary human"
+            echo "        readable summary of changes."
+            echo ""
+            echo "    \`make vbump\` target will cause bump of the *last*"
+            echo "    version fragment (Z, or PATCH in SemVer).  To bump other"
+            echo "    fragments, use \`make vbump_y\` or \`make vbump_x\` (MINOR"
+            echo "    or MAJOR in SemVer, respectively)."
+            echo ""
+            echo "    MKit will create a template of the message by scanning"
+            echo "    all commits since last release and invoke 'git commit' so"
+            echo "    that maintainer is presented with a window editing the"
+            echo "    commit message."
+            echo ""
+            echo "    Maintainer is responsible for finishing the commit message"
+            echo "    by:"
+            echo ""
+            echo "     *  Re-wording and merging the items as needed."
+            echo "     *  Adding any details, if needed."
+            echo "     *  Removing short hashes and file lists added by MKit"
+            echo "        (these are added only to make editing easier)."
+            echo ""
+            echo "    Once maintainer is happy with *bump commit* message,"
+            echo "    they can exit the editor and move on to next step."
+            echo ""
+            echo " 2. \`make release\` - will check if latest commit on current"
+            echo "    branch is a *bump commit*, and if yes, will create"
+            echo "    a corresponding **release tag**."
+            echo ""
+            echo "    **Release tags** are annotated tags (see *git-tag(1)*)"
+            echo "    formed by version number prefixed by letter \`v\` and are"
+            echo "    used by MKit to calculate version number when building"
+            echo "    assets.  Release tags contain the *bump commit* message"
+            echo "    as the annotation."
+            echo ""
+            echo "    If a *release destination* branch is specified as"
+            echo "    [project:reldst] in mkit.ini, MKit will also update that"
+            echo "    branch so that it points to the same commmit as the"
+            echo "    newly created release tag."
+            echo ""
+            echo " 3. Maintainer will push branches and commits to any shared"
+            echo "    remotes as needed."
+            echo ""
+            echo "    Warning: This is your last chance to fix any mistakes."
+            echo "    git tags are designed to be permanent, \"official\","
+            echo "    write-only objects and they will typically quickly spread"
+            echo "    to other clones.  *Don't count on getting rid of release"
+            echo "    tag*."
+            echo ""
+
             ;;
 
         */mkit.ini|mkit.ini)
                 echo "[dist]"
                 {
                     $MkLicense  && echo "tarball = LICENSE.md"
+                    $MkReadme   && echo "tarball = MAINTAINERS.md"
                     $MkMakefile && echo "tarball = Makefile"
                     $MkReadme   && echo "tarball = README.md"
                     echo "tarball = mkit.ini"
                 echo "[macros]"
                 {
                     echo "__${PackageName^^}_FOO__ = Barr.."
+                    echo "    __PROJECT_DESC_MAIN__ = MKIT_STUB_DESCRIPTION - replace this with your project"
+                    echo "    __PROJECT_DESC_MAIN__ = MKIT_STUB_DESCRIPTION .. description; this will appear"
+                    echo "    __PROJECT_DESC_MAIN__ = MKIT_STUB_DESCRIPTION .. in places like rpm -i"
                 } | reformat_section
                 echo ""
                 echo "[modes]"
             ;;
 
         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 'Name:           __MKIT_PROJ_PKGNAME__'
+            echo 'Version:        __MKIT_PROJ_VERSION__'
+            echo 'Release:        1%{?dist}'
+            echo 'Summary:        __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
             test -n "$VcsBrowser" && echo 'URL:        __MKIT_PROJ_VCS_BROWSER__'
-            $MkLicense && echo "License:    $License"
-            echo 'Source0:    %{name}-%{version}.tar.gz'
-            echo 'BuildArch:  noarch'
+            $MkLicense && echo "License:        $License"
+            echo 'Source0:        %{name}-%{version}.tar.gz'
+            echo 'BuildArch:      noarch'
+            echo 'BuildRequires:  make'
             echo ''
             echo 'Requires: MKIT_STUB_REQUIRES'
             echo '%description'
-            echo 'MKIT_STUB_DESCRIPTION'
+            echo '__PROJECT_DESC_MAIN__'
             echo ''
             echo '%prep'
             echo '%setup -q'
             echo '%changelog'
             echo ''
             echo '# specfile built with MKit __MKIT_MKIT_VERSION__'
+            echo "#  .. based on stub from: $MKIT_VERSION"
             ;;
 
         packaging/debian/copyright)
             echo 'Standards-Version: 3.9.2'
             echo 'Build-Depends:'
             echo ' debhelper (>= 9),'
+            echo ' make,'
             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 ' __PROJECT_DESC_MAIN__'
             echo ''
             echo '# control file built with MKit __MKIT_MKIT_VERSION__'
+            echo "#  .. based on stub from: $MKIT_VERSION"
             ;;
 
         packaging/debian/changelog)
             echo ''
             echo '%:'
             echo ''
-            echo '	dh $@'
+            echo '	PREFIX=/usr dh $@'
             echo ''
             echo 'override_dh_auto_install:'
             echo ''
-            echo '	make install PREFIX=/usr DESTDIR=debian/tmp'
+            echo '	make install DESTDIR=debian/tmp'
             ;;
 
         packaging/debian/source/format)
             if $MkReadme; then
             echo ""
             echo ""
-            echo "README.md"
-            echo "---------"
+            echo "README.md and MAINTAINERS.md"
+            echo "----------------------------"
             echo ""
             echo "Each serious project needs a serious README.  Which is why"
             echo "*stub* has created a 'stub' of one for you."
+            echo ""
+            echo "Furthermore MAINTAINERS.md is created to help maintainers"
+            echo "do basic MKit operations such as building assets and making"
+            echo "releases."
             fi
 
             echo ""
         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 "    -g            make git commits before and after"
         echo "                  (implies -y)"
         echo "    -y            don't ask, just do it"
         echo "    -R            skip creating README.md"
     deploy src/"$PackageName".skel
     $MkMakefile     && deploy Makefile
     $MkReadme       && deploy README.md
+    $MkReadme       && deploy MAINTAINERS.md
     $MkLicense      && deploy LICENSE.md
     $AutoClean      && deploy .mkit/autoclean
     $MkPackaging    && deploy_packaging