Update MKit to v0.0.24

utils/mkit/include/build.sh

@@ -1,7 +1,9 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/ini.sh"   || die "cannot import ini.sh"
-. "$MKIT_DIR/include/facts.sh" || die "cannot import facts.sh"
+mkit_import ini
+mkit_import facts
 
 
 _build1() {
@@ -79,6 +81,7 @@ _expand_tokens() {
         done
         echo "s|__MKIT_PROJ_NAME__|$(ini 1value project:name | _qfs)|g;"
         echo "s|__MKIT_PROJ_CODENAME__|$(ini 1value project:codename | _qfs)|g;"
+        echo "s|__MKIT_PROJ_LICENSE__|$(ini 1value project:license | _qfs)|g;"
         echo "s|__MKIT_PROJ_PKGNAME__|$(ini 1value project:pkgname | _qfs)|g;"
         echo "s|__MKIT_PROJ_TAGLINE__|$(ini 1value project:tagline | _qfs)|g;"
         echo "s|__MKIT_PROJ_MAINTAINER__|$(ini 1value project:maintainer | _qfs)|g;"

utils/mkit/include/deploy.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
 
 _deploy_item() {
     #
@@ -26,13 +30,14 @@ _deploy_item() {
     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
+    local item                              # each in directory
     if test -d "$src"; then
-        _maybe mkdir -vp "$(dirname "$dst")"
-        _maybe cp -Tvr "$src" "$dst"
-        find "$dst" -type f \
-          | while read -r chmod_item; do
-                _maybe chmod "$mode" "$chmod_item"
+        find "$src" -type f \
+          | while read -r item; do
+                [[ $item =~ .skel$ ]] \
+                 && grep -q "${item%.skel}" "$MKIT_LOCAL/built.lst" \
+                 && continue
+                _deploy_item "$item" "$dst${item#$src}" "$mode"
             done
     else
         _maybe install -DTvm "$mode" "$src" "$dst"

utils/mkit/include/facts.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/ini.sh" || die "cannot import ini.sh"
+mkit_import ini
 
 git_bool() {
     #

utils/mkit/include/ini.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
 _ini_cat() {
     #
@@ -88,7 +90,7 @@ _ini_lskeys() {
     # List keys from a section
     #
     local sct=$1    # section of interest
-    _ini_grepsec "$sct" | cut -d= -f1 | sort | uniq
+    _ini_grepsec "$sct" | cut -d= -f1 | awk '!x[$0]++'
 }
 
 _ini_maybe_expand() {

utils/mkit/include/mkit.sh

@@ -1,9 +1,34 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/build.sh"  || die "cannot import build.sh"
-. "$MKIT_DIR/include/deploy.sh" || die "cannot import deploy.sh"
-. "$MKIT_DIR/include/release.sh" || die "cannot import release.sh"
-. "$MKIT_DIR/include/ini.sh"    || die "cannot import ini.sh"
+die() {
+    #
+    # Exit with message and non-zero exit status
+    #
+    echo "fatal: $*" >&2
+    exit 4
+}
+
+mkit_import() {
+    #
+    # Import mkit module $1.sh
+    #
+    # Check for module, source it and die with reasonable message if needed.
+    #
+    local modname=$1
+    local modpath
+    modpath="$MKIT_DIR/include/$modname.sh"
+    test -f "$modpath" || die "no such module: $modpath"
+    bash -n "$modpath" || die "bad syntax: $modpath"
+    #shellcheck disable=SC1090
+    . "$modpath" || die "failed to import: $modname"
+}
+
+mkit_import build
+mkit_import deploy
+mkit_import release
+mkit_import ini
 
 _valid_targets() {
     #
@@ -15,11 +40,13 @@ _valid_targets() {
     echo debstuff
     echo dist
     echo install
+    echo release
     echo release_x
     echo release_y
     echo release_z
     echo rpmstuff
     echo uninstall
+    echo vbump
     echo vbump_x
     echo vbump_y
     echo vbump_z
@@ -49,14 +76,6 @@ debug_var() {
     done
 }
 
-die() {
-    #
-    # Exit with message and non-zero exit status
-    #
-    echo "fatal: $*" >&2
-    exit 4
-}
-
 _compver() {
     #
     # True if version $1 matches our version
@@ -96,7 +115,7 @@ _chkiniversion() {
     ver_line=$(
         {
             head -3 "$MKIT_INI"
-            tac "$MKIT_INI" | tail -3
+            tail -3 "$MKIT_INI"
         } | grep -m 1 -E '^# *mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
     )
     test -n "$ver_line" \

utils/mkit/include/release.sh

@@ -1,7 +1,9 @@
 #!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
 
-. "$MKIT_DIR/include/ini.sh"   || die "cannot import ini.sh"
-. "$MKIT_DIR/include/facts.sh" || die "cannot import facts.sh"
+mkit_import ini
+mkit_import facts
 
 _bump_version() {
     #
@@ -89,6 +91,7 @@ _release() {
     #
     local rlevel=$1     # release level (x, y or z)
     local newtag        # new tag
+    local relsrc        # release source branch (if any)
     local reldst        # release destination branch (if any)
 
     _relck git_present
@@ -105,9 +108,10 @@ _release() {
     $MKIT_DRY && return
     git tag -m "$(_release_msg)" "$newtag"
 
+    relsrc=$(ini 1value project:relsrc)
     reldst=$(ini 1value project:reldst)
-    debug_var reldst
-    if test -n "$reldst"; then
+    debug_var relsrc reldst
+    if test -n "$reldst" && test "$reldst" != "$relsrc"; then
         git branch -f "$reldst" "$newtag"
     fi
 }
@@ -167,6 +171,13 @@ _vbump_gitmsg() {
         '
 }
 
+release() {
+    #
+    # Perform release on Z level
+    #
+    _release z
+}
+
 release_x() {
     #
     # Perform release on X level
@@ -188,6 +199,13 @@ release_z() {
     _release z
 }
 
+vbump() {
+    #
+    # Perform version bump on Z level
+    #
+    _vbump z
+}
+
 vbump_x() {
     #
     # Perform version bump on X level

utils/mkit/include/vars.sh

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

utils/mkit/make

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

utils/mkit/mkit.mk

@@ -27,7 +27,7 @@ install: all
 	@$(MKIT_DIR)/make install
 
 release:
-	@$(MKIT_DIR)/make release_z
+	@$(MKIT_DIR)/make release
 
 release_x:
 	@$(MKIT_DIR)/make release_x
@@ -42,7 +42,7 @@ uninstall:
 	@$(MKIT_DIR)/make uninstall
 
 vbump:
-	@$(MKIT_DIR)/make vbump_z
+	@$(MKIT_DIR)/make vbump
 
 vbump_x:
 	@$(MKIT_DIR)/make vbump_x
@@ -53,4 +53,4 @@ vbump_y:
 vbump_z:
 	@$(MKIT_DIR)/make vbump_z
 
-.PHONY: all clean dist rpmstuff install uninstall release_x release_y release_z vbump_x vbump_y vbump_z
+.PHONY: all clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z

utils/mkit/stub

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