etc/README.md: updated.

1 files changed, 130 insertions, 122 deletions

diff --git a/etc/README.md b/etc/README.md
index 95ad13e5..948c2361 100644
--- a/etc/README.md
+++ b/etc/README.md
@@ -26,14 +26,14 @@ into account when deploying and using Midipix distributions.
 	3.3. [Addressing build failure](#33-addressing-build-failure)  

 	3.4. [Package archive files and Git repositories](#34-package-archive-files-and-git-repositories)  

 	3.5. [Patches and ``vars`` files](#35-patches-and-vars-files)  

-4. [Units reference](#4-units-reference)  

+4. [Reference](#4-reference)  

 	4.1. [Build steps](#41-build-steps)  

 	4.2. [Build variables](#42-build-variables)  

-	4.3. [Fault-tolerant & highly optimised 3D laser show-equipped usage screen](#43-fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen)  

-	4.4. [File installation DSL](#44-file-installation-dsl)  

-	4.5. [Package variables](#45-package-variables)  

-		4.5.1. [Package variable types](#451-package-variable-types)  

-		4.5.2. [Package variables](#452-package-variables)  

+	4.3. [File installation DSL](#43-file-installation-dsl)  

+	4.4. [Package variables](#44-package-variables)  

+		4.4.1. [Package variable types](#441-package-variable-types)  

+		4.4.2. [Package variables](#442-package-variables)  

+	4.5. [Fault-tolerant & highly optimised 3D laser show-equipped usage screen](#45-fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen)  

 	4.6. [``pkgtool.sh``](#46-pkgtoolsh)  

 5. [References](#5-references)  

 

@@ -93,7 +93,7 @@ and run the following command line:
 By default, the build will take place within ``${HOME}/midipix/nt64/release``

 and package archive files and/or Git repositores will be downloaded into

 ``${HOME}/midipix/dlcache``. Consult sections [4.2](#42-build-variables) and

-[4.5](#45-package-variables) for the list of available build/package variables

+[4.4](#44-package-variables) for the list of available build/package variables

 and how to override them.  

 Parallelisation is enabled by the above command line for both packages that can

 be built independently of each other and ``make(1)`` via ``-j``, limited to the

@@ -327,7 +327,7 @@ which are specified in this order.
   

 Pick a build group according to the criteria mentioned, add the package to the

 build group's list of contained packages in its corresponding file, and add the

-set of package variables required (see above and section [4.5](#45-package-variables).)  

+set of package variables required (see above and section [4.4](#44-package-variables).)  

 Consult section [3.5](#35-patches-and-vars-files) if the package to be added

 requires patches or additional code amending or replacing package build steps

 or the entire package build. Consult section [4.1](#41-build-steps) for a list

@@ -401,8 +401,8 @@ for a list of package build steps and how they are overriden.
 

 [//]: # "}}}"

 

-[//]: # "{{{ 4. Units reference"

-## 4. Units reference

+[//]: # "{{{ 4. Reference"

+## 4. Reference

 [//]: # "}}}"

 [//]: # "{{{ 4.1. Build steps"

 ## 4.1. Build steps

@@ -418,6 +418,14 @@ or composed in terms of prior and/or subsequent execution by a function named
 respectively, in the package's ``vars`` file. If a function named ``pkg_<package name>_all()``

 exists, it will override all build steps.  

   

+Build step functions receive the following arguments in the order specified:

+  

+| Name          | Description                                              |

+| ------------- | -------------------------------------------------------- |

+| \_group\_name | Package name                                             |

+| \_pkg\_name   | Group name                                               |

+| \_restart\_at | Optional list of build steps to restart package build at |

+  

 Build step status is tracked on a per-package basis by state files beneath

 ``${BUILD_WORKDIR}`` following the format ``.<package name>.<build step>``;

 package build completion corresponds to the pseudo-build step ``finish``.

@@ -477,112 +485,8 @@ env ARCH=nt64 BUILD_KIND=release PREFIX_ROOT="${HOME}/midipix_tmp" ./build.sh -D
 [Back to top](#table-of-contents)

 

 [//]: # "}}}"

-[//]: # "{{{ 4.3. Fault-tolerant & highly optimised 3D laser show-equipped usage screen"

-## 4.3. Fault-tolerant & highly optimised 3D laser show-equipped usage screen

-

-```

-usage: ./build.sh [-a nt32|nt64]  [-b debug|release]    [-C dir[,..]]  [-D kind[,..]]

-                  [-F ipv4|ipv6|offline]    [-h|--help] [-p jobs|-P]    [-r ALL|LAST]

-                  [-r [*[*[*]]]name[,..][:ALL|LAST|[^|<|<=|>|>=]step,..]]        [-R]

-		  [-v] [-V [+]tag|pat[,..]]

-

-                  [--as-needed] [--debug-minipix] [--reset-state]

-                  [--roar]      [[=]<group>|<variable name>=<variable override>[ ..]]

-

-        -a nt32|nt64        Selects 32-bit or 64-bit architecture; defaults to nt64.

-        -b debug|release    Selects debug or release build kind; defaults to debug.

-        -C dir[,..]         Clean build directory (build,) ${PREFIX} before processing build

-                            scripts (prefix,) source directory (src,) and/or destination

-                            directory (dest) after successful package builds.

-        -D kind[,..]        Produce minimal midipix distribution directory (minipix,) RPM

-                            binary packages (rpm,) and/or deployable distribution ZIP

-                            archive (zipdist.) zipdist implies minipix.

-        -F ipv4|ipv6|offline

-                            Force IPv4 (ipv4) or IPv6 (ipv6) when downloading package

-                            archives and/or Git repositories or don't download either at all

-                            (offline.)

-        -h|--help           Show short/full help screen, respectively.

-        -p jobs|-P          Enables parallelisation at group-level, whenever applicable.

-                            The maximum count of jobs defaults to the number of logical

-                            processors on the host system divided by two (2.)

-

-                            If -R is not specified and at least one (1) package fails to

-                            build, all remaining package builds will be forcibly aborted.

-

-        -r ALL|LAST         Restart all packages or the last failed package and resume

-                            build, resp.

-        -r [*[*[*]]]name[,..][:ALL|LAST|[^|<|<=|>|>=]step,..]

-                            Restart the specified comma-separated package(s) w/ inhibition

-                            of package build step state resetting completely (`ALL',) starting

-                            at the resp. last successfully executed build steps (`LAST',) or the

-                            specified comma-separated list of build steps, optionally subject

-                            concerning package name(s) and/or build step(s) to the below modifiers:

-

-                            Prepend name w/ `*' to automatically include dependencies, `**'

-                            to forcibly rebuild all dependencies, and `***' to forcibly

-                            rebuild all packages that depend on the specified package(s).

-

-                            Prepend step w/ `^' to filter build steps with, `<' or `<='

-                            to constrain build steps to below or below or equal with, resp.,

-                            `>' or `>=' to constrain build steps to above or above or equal

-                            with, resp.

-

-                            Currently defined build steps are:

-                            fetch_clean, fetch_download, fetch_extract, configure_clean,

-                            configure_patch_pre, configure_autotools, configure_patch,

-                            configure, build_clean, build, install_clean, install_subdirs,

-                            install_make, install_files, install_libs, install, install_rpm,

-                            and clean.

-

-                            Additionally, the following virtual steps are provided:

-                            @fetch, @configure, @build, @install, @clean, and finish.

-

-        -R                  Ignore build failures, skip printing package logs, and continue

-                            building (relaxed mode.)

-

-        -v                  Increase logging verbosity.

-        -V [+]tag|pat[,..]  Enable logging for messages with tag or pattern matching tags of:

-                            + (prefix)..: initialise tags with normal verbosity (implies normal) (see etc/build.theme,)

-                            all.........: log everything (see etc/build.theme,)

-                            clear|none..: log nothing,

-                            normal......: log at normal verbosity (see etc/build.theme,)

-                            verbose.....: log at increased verbosity (implies normal) (see etc/build.theme) (-v,)

-

-                            build.......: log package build logs,

-                            fileops.....: log RTL file operations,

-                            install.....: log RTL installation DSL operations,

-                            zipdist.....: log deployable distribution ZIP archive operations,

-                            xtrace......: set xtrace during package builds,

-

-                            fatal.......: fatal, unrecoverable errors,

-                            info........: informational messages,

-                            verbose.....: verbose informational messages,

-                            warning.....: warning messages possibly relating to imminent fatal, unrecoverable errors,

-

-                            build_*.....: general build messages (viz.: begin, finish, finish_time, vars,)

-                            group_*.....: build group messages (viz.: begin, finish,)

-                            pkg_*.......: package build messages (viz.: begin, finish, msg, skip, step, strip.)

-

-        --as-needed         Don't build unless the midipix_build repository has received

-                            new commits.

-        --debug-minipix     Don't strip(1) minipix binaries to facilitate debugging minipix.

-        --reset-state       Reset package build step state on exit.

-

-        <group>[ ..]        One of: dev_packages, dist, host_deps, host_deps_rpm,

-                            host_toolchain, host_tools, minipix, native_packages,

-                            native_runtime, native_toolchain, native_tools.

-

-                            Prepend w/ `=' to inhibit group-group dependency expansion.

-

-        <variable name>=<variable override>[ ..]

-                            Override build or package variable.

-```

-  

-[Back to top](#table-of-contents)

-

-[//]: # "}}}"

-[//]: # "{{{ 4.4. File installation DSL"

-## 4.4. File installation DSL

+[//]: # "{{{ 4.3. File installation DSL"

+## 4.3. File installation DSL

 

 File and directory installation, comprising e.g. copying, moving, creating

 symbolic links, setting owner and/or permission metadata, are expressed in

@@ -750,8 +654,8 @@ usage: rtl_install [-i] [-I ifs] [-n] [-p name=val] [-v] prefix spec_list
 [Back to top](#table-of-contents)

 

 [//]: # "}}}"

-[//]: # "{{{ 4.5. Package variables"

-### 4.5. Package variables

+[//]: # "{{{ 4.4. Package variables"

+### 4.4. Package variables

 

 The following variables are package-specific and receive their value from either

 top-level defaults defined in ``midipix.env``, build group-specific defaults from the

@@ -777,8 +681,8 @@ line, with each variable prefixed w/ ``PKG_``, e.g.:
 The minimum set of package variables that must be provided is ``SHA256SUM, URL,

 VERSION`` and/or ``URLS_GIT``, respectively.

 

-[//]: # "{{{ 4.5.1 Package variable types"

-## 4.5.1 Package variable types

+[//]: # "{{{ 4.4.1 Package variable types"

+## 4.4.1 Package variable types

 

 | Type definition               | Description                                                                                                                                  |

 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |

@@ -803,8 +707,8 @@ VERSION`` and/or ``URLS_GIT``, respectively.
 | URL(Git)			| Git URL in the format ``[subdir=]URL[@branch]``; see section [3.4](#34-package-archive-files-and-git-repositories)                           |

 

 [//]: # "}}}"

-[//]: # "{{{ 4.5.2 Package variables"

-## 4.5.2 Package variables

+[//]: # "{{{ 4.4.2 Package variables"

+## 4.4.2 Package variables

 

 | Package variable name        | Type             | Description                                                                                                                                |

 | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |

@@ -897,6 +801,110 @@ VERSION`` and/or ``URLS_GIT``, respectively.
 [Back to top](#table-of-contents)

 

 [//]: # "}}}"

+[//]: # "{{{ 4.5. Fault-tolerant & highly optimised 3D laser show-equipped usage screen"

+## 4.5. Fault-tolerant & highly optimised 3D laser show-equipped usage screen

+

+```

+usage: ./build.sh [-a nt32|nt64]  [-b debug|release]    [-C dir[,..]]  [-D kind[,..]]

+                  [-F ipv4|ipv6|offline]    [-h|--help] [-p jobs|-P]    [-r ALL|LAST]

+                  [-r [*[*[*]]]name[,..][:ALL|LAST|[^|<|<=|>|>=]step,..]]        [-R]

+		  [-v] [-V [+]tag|pat[,..]]

+

+                  [--as-needed] [--debug-minipix] [--reset-state]

+                  [--roar]      [[=]<group>|<variable name>=<variable override>[ ..]]

+

+        -a nt32|nt64        Selects 32-bit or 64-bit architecture; defaults to nt64.

+        -b debug|release    Selects debug or release build kind; defaults to debug.

+        -C dir[,..]         Clean build directory (build,) ${PREFIX} before processing build

+                            scripts (prefix,) source directory (src,) and/or destination

+                            directory (dest) after successful package builds.

+        -D kind[,..]        Produce minimal midipix distribution directory (minipix,) RPM

+                            binary packages (rpm,) and/or deployable distribution ZIP

+                            archive (zipdist.) zipdist implies minipix.

+        -F ipv4|ipv6|offline

+                            Force IPv4 (ipv4) or IPv6 (ipv6) when downloading package

+                            archives and/or Git repositories or don't download either at all

+                            (offline.)

+        -h|--help           Show short/full help screen, respectively.

+        -p jobs|-P          Enables parallelisation at group-level, whenever applicable.

+                            The maximum count of jobs defaults to the number of logical

+                            processors on the host system divided by two (2.)

+

+                            If -R is not specified and at least one (1) package fails to

+                            build, all remaining package builds will be forcibly aborted.

+

+        -r ALL|LAST         Restart all packages or the last failed package and resume

+                            build, resp.

+        -r [*[*[*]]]name[,..][:ALL|LAST|[^|<|<=|>|>=]step,..]

+                            Restart the specified comma-separated package(s) w/ inhibition

+                            of package build step state resetting completely (`ALL',) starting

+                            at the resp. last successfully executed build steps (`LAST',) or the

+                            specified comma-separated list of build steps, optionally subject

+                            concerning package name(s) and/or build step(s) to the below modifiers:

+

+                            Prepend name w/ `*' to automatically include dependencies, `**'

+                            to forcibly rebuild all dependencies, and `***' to forcibly

+                            rebuild all packages that depend on the specified package(s).

+

+                            Prepend step w/ `^' to filter build steps with, `<' or `<='

+                            to constrain build steps to below or below or equal with, resp.,

+                            `>' or `>=' to constrain build steps to above or above or equal

+                            with, resp.

+

+                            Currently defined build steps are:

+                            fetch_clean, fetch_download, fetch_extract, configure_clean,

+                            configure_patch_pre, configure_autotools, configure_patch,

+                            configure, build_clean, build, install_clean, install_subdirs,

+                            install_make, install_files, install_libs, install, install_rpm,

+                            and clean.

+

+                            Additionally, the following virtual steps are provided:

+                            @fetch, @configure, @build, @install, @clean, and finish.

+

+        -R                  Ignore build failures, skip printing package logs, and continue

+                            building (relaxed mode.)

+

+        -v                  Increase logging verbosity.

+        -V [+]tag|pat[,..]  Enable logging for messages with tag or pattern matching tags of:

+                            + (prefix)..: initialise tags with normal verbosity (implies normal) (see etc/build.theme,)

+                            all.........: log everything (see etc/build.theme,)

+                            clear|none..: log nothing,

+                            normal......: log at normal verbosity (see etc/build.theme,)

+                            verbose.....: log at increased verbosity (implies normal) (see etc/build.theme) (-v,)

+

+                            build.......: log package build logs,

+                            fileops.....: log RTL file operations,

+                            install.....: log RTL installation DSL operations,

+                            zipdist.....: log deployable distribution ZIP archive operations,

+                            xtrace......: set xtrace during package builds,

+

+                            fatal.......: fatal, unrecoverable errors,

+                            info........: informational messages,

+                            verbose.....: verbose informational messages,

+                            warning.....: warning messages possibly relating to imminent fatal, unrecoverable errors,

+

+                            build_*.....: general build messages (viz.: begin, finish, finish_time, vars,)

+                            group_*.....: build group messages (viz.: begin, finish,)

+                            pkg_*.......: package build messages (viz.: begin, finish, msg, skip, step, strip.)

+

+        --as-needed         Don't build unless the midipix_build repository has received

+                            new commits.

+        --debug-minipix     Don't strip(1) minipix binaries to facilitate debugging minipix.

+        --reset-state       Reset package build step state on exit.

+

+        <group>[ ..]        One of: dev_packages, dist, host_deps, host_deps_rpm,

+                            host_toolchain, host_tools, minipix, native_packages,

+                            native_runtime, native_toolchain, native_tools.

+

+                            Prepend w/ `=' to inhibit group-group dependency expansion.

+

+        <variable name>=<variable override>[ ..]

+                            Override build or package variable.

+```

+  

+[Back to top](#table-of-contents)

+

+[//]: # "}}}"

 [//]: # "{{{ 4.6. ``pkgtool.sh``"

 ## 4.6. ``pkgtool.sh``