diff options
| author | Lucio Andrés Illanes Albornoz <lucio@lucioillanes.de> | 2020-03-04 15:37:39 +0000 |
|---|---|---|
| committer | Lucio Andrés Illanes Albornoz <lucio@lucioillanes.de> | 2020-03-04 16:27:57 +0000 |
| commit | 6d9a3c055659820ad044fe8c4de07b8c194c8441 (patch) | |
| tree | 360ecc76e2dd9261f491031617ec05c64a2bdd69 /etc | |
| parent | 776d3c5cc2bef32615611902f2aa125cbd95b7f1 (diff) | |
| download | midipix_build-6d9a3c055659820ad044fe8c4de07b8c194c8441.tar.bz2 midipix_build-6d9a3c055659820ad044fe8c4de07b8c194c8441.tar.xz | |
subr/build_init.subr:buildp_init_env(): source subr/*.subr as early as possible (via duvallj.)
subr/build_init.subr:buildp_init_env(): correctly emit errors & exit given early initialisation failure.
etc/README.md: updated.
Diffstat (limited to 'etc')
| -rw-r--r-- | etc/README.md | 544 |
1 files changed, 337 insertions, 207 deletions
diff --git a/etc/README.md b/etc/README.md index c2f6d9df..83a850c5 100644 --- a/etc/README.md +++ b/etc/README.md @@ -1,207 +1,337 @@ -> N.B. If you're interested in building Midipix using this script, please join the project's -IRC channel #midipix on Freenode and ask for the address of the internal repositories. - -> N.B. If in doubt, consult the fault-tolerant & highly optimised 3D laser show-equipped -usage screen w/ ./build.sh -h or a hungry lion might eat you alive. - -# Table of Contents -[Building a midipix distribution](#building-a-midipix-distribution) -[Common tasks](#common-tasks) -[Fault-tolerant & highly optimised 3D laser show-equipped usage screen](#fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen) -[Non-exhaustive list of build variables](#non-exhaustive-list-of-build-variables) - -## Building a midipix distribution -A Midipix distribution consists of the following: -* the native Midipix toolchain, consisting of perk, gcc, its dependencies, - and binutils, -* musl, a lightweight, fast, simple, and free libc[1] used by Midipix, -* the Midipix runtime components that bridge the gap between the libc and the - executive subsystems of all Windows NT-derived Windows OS starting with and - including Windows XP, and -* a steadily increasing number of 3rd party open source packages, as expected in - any modern POSIX-compliant \*nix environment, including GNU coreutils, shells, - libraries such as ncurses, libressl, as well as Perl and Python. - -Install the build-time dependencies listed below, clone this repository, and run the -following command line within the latter: - -```shell -./build.sh -a nt64 -b release -D minipix,zipdist -P -v -``` - -### Build-time dependencies -* **Alpine Linux**: binutils bzip2 cmake coreutils curl findutils g++ gawk gcc git grep gzip libc-dev linux-headers lzip make musl-dev net-tools patch perl perl-xml-parser procps sed tar util-linux wget xz zip -* **Debian/-derived Linux**: binutils bzip2 clzip cmake coreutils curl findutils g++ gawk gcc git grep gzip hostname libc6-dev libxml-parser-perl lzma make patch perl procps sed tar util-linux wget xz-utils zip -* **OpenSUSE Linux**: binutils bzip2 cmake coreutils curl findutils gawk gcc gcc-c++ git grep gzip hostname linux-glibc-devel lzip make patch perl perl-XML-Parser procps sed tar util-linux wget xz zip - -> N.B. Busybox is not supported. - -> N.B. Some packages (*coreutils*, *grep*, and *tar*, among others) override -Alpine's BusyBox utilities of the same name, as the latter are either non- -conformant or defective. - -## Common tasks -Rebuild set of packages in isolation, along w/ their dependencies, if any, as needed, -or forcibly, respectively: -```shell -./build.sh [ ... ] -r mc,zsh -./build.sh [ ... ] -r \*mc,zsh -./build.sh [ ... ] -r \*\*mc,zsh -``` - -Restart the ``configure``, ``build``, and ``install`` steps of the ``coreutils`` package. -```shell -./build.sh -r coreutils:configure,build,install -``` - -Rebuild entire build group: -```shell -./build.sh [ ... ] -r ALL native_runtime -``` - -## 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] [-p jobs] [-P] [-r [*[*]]ALL|LAST|name[,..][:step,..]] [-R] [-v[v[v[v]]]] - [--as-needed] [--debug-minipix] [<group>[ ..]] - - -a nt32|nt64 Selects 32-bit or 64-bit architecture; defaults to nt64. - -b debug|release Selects debug or release build; 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 Show this screen. - -p jobs Enables parallelisation at group-level, whenever applicable. - -P 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 for convenience. - -r [*[*]]ALL[:step,..]|LAST|name[,..][:step,..] - Restart all packages/the specified comma-separated package(s) - completely or at optionally specified comma-separated step(s) - or restart the last failed package and resume build. - Prepend w/ `*' to automatically include dependencies and `**' to - forcibly rebuild all dependencies. - - Currently defined steps are: - fetch_wget, fetch_git, fetch_extract, - configure_patch_pre, configure_autotools, configure_patch, configure, - build, - install_subdirs, install_make, install_files, install_libs, install, and install_rpm. - -R Ignore build failures, skip printing package logs, and continue - building (relaxed mode.) - -v[v[v[v]]] Be verbose; -vv: always print package logs; -vvv: set xtrace during package builds; -vvvv: logs fileops. - --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. - <group>[ ..] One of: host_deps, host_deps_rpm, host_toolchain, host_tools, minipix, - native_packages, native_runtime, native_toolchain, and/or native_tools. -``` - -## Non-exhaustive list of build variables -The following variables are primarily defined in ``midipix.env`` and may be overriden -on a per-build basis on the command-line after the last argument, if any, e.g.: - -```shell -./build.sh -a nt64 -b release -D minipix,zipdist -P -v PREFIX_ROOT="${HOME}/midipix_tmp" -``` - -Furthermore, ``${HOME}/midipix_build.vars``, ``${HOME}/.midipix_build.vars``, and/or -``../midipix_build.vars`` are sourced during build initialisation and may contain -additional overrides, particularly ``${DEFAULT_GITROOT_HEAD}``. - -| Variable name | Default value | Description | -| ---------------- | ------------------------------- | ----------------------------------------------------------------------------- | -| ARCH | nt64 | Target 32-bit (nt32) or 64-bit (nt64) architecture | -| BUILD | debug | Build w/ debugging (debug) or release compiler flags | -| BUILD_DLCACHEDIR | ${PREFIX_ROOT}/dlcache | Absolute pathname to package downloads cache root directory | -| BUILD_WORKDIR | ${PREFIX}/tmp | Absolute pathname to temporary package build root directory | -| PREFIX | ${PREFIX_ROOT}/${ARCH}/${BUILD} | Absolute pathname to architecture- & build type-specific build root directory | -| PREFIX_CROSS | ${PREFIX}/${DEFAULT_TARGET} | Absolute pathname to toolchain root directory | -| PREFIX_MINGW32 | ${PREFIX}/x86_64-w64-mingw32 | Absolute pathname to MinGW toolchain root directory | -| PREFIX_MINIPIX | ${PREFIX}/minipix | Absolute pathname to minipix distribution root directory | -| PREFIX_NATIVE | ${PREFIX}/native | Absolute pathname to cross-compiled packages root directory | -| PREFIX_ROOT | ${HOME}/midipix | Absolute pathname to top-level directory | -| PREFIX_RPM | ${PREFIX}/rpm | Absolute pathname to package RPM archive root directory | - -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 build group the package pertains to and defined in its corresponding file beneath -``groups/``, or package-specific overrides defined either in the latter and/or in -its corresponding file beneath ``vars/``. Additionally, overrides may be specified -on a per-build basis on the command-line after the last argument, with each variable -prefixed w/ ``PKG_``, e.g.: ``./build.sh [ ... ] PKG_ZSH_CC="/bin/false"``. -The minimum set of package variables that must be provided is ``SHA256SUM, URL, VERSION`` -and ``URLS_GIT``, respectively. - -| Package variable name | Description | -| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| AR | Command- or pathname of toolchain library archive editor (ar(1)) | -| BASE_DIR | Absolute pathname to package build root directory beneath ${BUILD_WORKDIR} | -| BUILD_DIR | Directory name of package build directory beneath ${PKG_BASE_DIR} | -| BUILD_STEPS_DISABLE | List of build steps to disable during package build | -| BUILD_TYPE | Cross-compiled toolchain (cross,) host (host,) or cross-compiled package build type | -| CC | Command- or pathname of toolchain C compiler (cc(1)) | -| CFLAGS_BUILD_EXTRA | Additional C compiler flags during package (make(1)) build | -| CFLAGS_CONFIGURE | C compiler flags during package (autotools or similar) configuration | -| CFLAGS_CONFIGURE_EXTRA | Additional C compiler flags during package (GNU autotools or similar) configuration | -| CONFIG_CACHE | List of GNU autotools configuration cache variables | -| CONFIG_CACHE_EXTRA | Additional list of GNU autotools configuration cache variables | -| CONFIG_CACHE_LOCAL | Additional list of GNU autotools configuration cache variables | -| CONFIGURE | Command- or pathname to package (GNU autotools or similar) configuration script | -| CONFIGURE_ARGS | List of arguments to package (GNU autotools or similar) configuration script | -| CONFIGURE_ARGS_EXTRA | Additional list of arguments to package (GNU autotools or similar) configuration script | -| CXX | Command- or pathname of toolchain C++ compiler (c++(1)) | -| CXXFLAGS_CONFIGURE | List of C++ compiler flags during package (autotools or similar) configuration | -| CXXFLAGS_CONFIGURE_EXTRA | Additional list of C++ compiler flags during package (autotools or similar) configuration | -| DEPENDS | List of package-package dependencies | -| DESTDIR | Directory name of package installation destination directory beneath ${PKG_BASE_DIR} | -| DISABLED | Disable package | -| ENV_VARS_EXTRA | List of double colon-separated environment variable equality sign-separated name-value pairs to set during package build | -| FNAME | Filename of package archive file | -| FORCE_AUTORECONF | Forcibly run autoreconf -fiv prior to package (GNU autotools or similar) configuration | -| GITROOT | midipix packages Git URL prefix | -| INHERIT_FROM | Inherit variables from named package | -| INSTALL_FILES | Whitespace-separated list of files to manually install into the package installation destination directory beneath ${PKG_BASE_DIR} | -| INSTALL_FILES_DESTDIR | Whitespace-separated list of files to initialise the package installation destination directory beneath ${PKG_BASE_DIR} with | -| INSTALL_FILES_DESTDIR_EXTRA | Additional whitespace-separated list of files to initialise the package installation destination directory beneath ${PKG_BASE_DIR} with | -| INSTALL_TARGET | Name of package build make(1) installation target | -| INSTALL_TARGET_EXTRA | Additional name of package build make(1) installation target | -| IN_TREE | Build package in-tree within ${PKG_SUBDIR} | -| LDFLAGS_BUILD_EXTRA | Additional linker flags during package (make(1)) build | -| LDFLAGS_CONFIGURE | Linker flags during package (autotools or similar) configuration | -| LDFLAGS_CONFIGURE_EXTRA | Additional linker flags during package (autotools or similar) configuration | -| LIBTOOL | Command- or pathname of libtool | -| MAKE | Command line of make(1) | -| MAKEFLAGS_BUILD | List of make(1) flags during package (make(1)) build | -| MAKEFLAGS_BUILD_EXTRA | Additional list of make(1) flags during package (make(1)) build | -| MAKEFLAGS_INSTALL | List of make(1) flags during package (make(1)) installation | -| MAKEFLAGS_INSTALL_EXTRA | Additional list of make(1) flags during package (make(1)) installation | -| MAKE_INSTALL_VNAME | Variable name of make(1) installation destination directory variable during package (make(1)) installation | -| NO_CLEAN | Inhibit cleaning of package build directory beneath ${PKG_BASE_DIR} pre-finish | -| NO_CLEAN_BASE_DIR | Inhibit cleaning of package build root directory beneath ${BUILD_WORKDIR} | -| NO_LOG_VARS | Inhibit logging of build & package variables pre-package build | -| PATCHES_EXTRA | Additional list of patches to apply | -| PKG_CONFIG | Command- or pathname of pkg-config(1) | -| PKG_CONFIG_PATH | pkg-config(1) search path | -| PKGLIST_DISABLE | Inhibit inclusion into ${PREFIX}/pkglist.${PKG_BUILD_TYPE} | -| PREFIX | Absolute pathname of top-level installation directory and package search path | -| PYTHON | Command- or pathname of Python | -| RANLIB | Command- or pathname of toolchain library archive index generator (ranlib(1)) | -| RPM_DISABLE | Inhibit creation of RPM archive | -| SHA256SUM | SHA-256 message digest of package archive | -| SUBDIR | Name of extracted archive or git-{clone,pull}(1)'d directory | -| TARGET | Dash-separated {build,host,target} triplet | -| URL | URL to package archive | -| URLS_GIT | List of package Git URL(s) (*name*=*URL*@*branch*) | -| VERSION | Package version | - -## References -* ``Sun, 25 Apr 2016 09:04:08 +0000 [1]`` <a href="http://www.musl-libc.org/faq.html" id="r1">musl FAQ</a> - -vim:tw=0 +> N.B. If you're interested in building Midipix using this script, please join
+the project's IRC channel #midipix on Freenode and ask for the address of the
+internal repositories required in order to build Midipix.
+
+[//]: # "{{{ Table of contents"
+# Table of Contents
+
+1. [What is midipix, and how is it different?](#1-what-is-midipix-and-how-is-it-different)
+2. [Building a midipix distribution](#2-building-a-midipix-distribution)
+ 2.1. [Build-time dependencies](#2-1-build-time-dependencies)
+ 2.1.1. [Alpine-specific notate bene](2-1-1-alpine-specific-notate-bene)
+ 2.2. [Deployment](#2-2-deployment)
+ 2.3. [System requirements](#2-3-system-requirements)
+3. [Common tasks](#3-common-tasks)
+ 3.1. [Fault-tolerant & highly optimised 3D laser show-equipped usage screen](#3-1-fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen)
+5. [Build variables](#5-build-variables)
+ 5.1. [Package variables](#5-1-package-variables)
+6. [References](#6-references)
+
+[//]: "}}}"
+
+[//]: # "{{{ 1. What is midipix, and how is it different?"
+
+midipix[\[3](#r3)] is a development environment that lets you create programs for
+Windows using the standard C and POSIX APIs. No compromises made, no shortcuts
+taken.
+
+If you are interested in cross-platform programming that reclaims the notion of
+write once, compile everywhere; if you believe that the 'standard' in the C
+Standard Library should not be a null signifier; and if you like cooking your
+code without #ifdef hell and low-level minutiae, then this page is for you.
+
+midipix makes cross-platform programming better, simpler and faster,
+specifically by bringing a modern, conforming C Runtime Library to the Windows
+platform. While the idea itself is not new, the approach taken in midipix to
+code portability is radically different from that found in other projects.
+
+*(reproduced from [\[3](#r3)])*
+
+[Back to top](#table-of-contents)
+
+[//]: "}}}"
+
+[//]: # "{{{ 2. Building a midipix distribution"
+## 2. Building a midipix distribution
+
+A Midipix distribution consists of the following:
+* the native Midipix toolchain, consisting of perk, gcc, its dependencies,
+ and binutils,
+* musl, a lightweight, fast, simple, and free libc[\[1](#r1)] used by Midipix,
+* the Midipix runtime components that bridge the gap between the libc and the
+ executive subsystems of all Windows NT-derived Windows OS starting with and
+ including Windows XP, and
+* a steadily increasing number of 3rd party open source packages, as expected in
+ any modern POSIX-compliant \*nix environment, including GNU coreutils, shells,
+ libraries such as ncurses, libressl, as well as Perl and Python.
+
+Install the build-time dependencies listed in [2.1](#2-1-build-time-dependencies),
+clone this repository, and run the following command line:
+
+```shell
+./build.sh -a nt64 -b release -D minipix,zipdist -P -v
+```
+
+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 [\[3.1](#3-1-fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen)][\[5](#5-build-variables)][\[5.1](#5-1-package-variables)]
+for the list of available build variables and how to override them.
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+[//]: # "{{{ 2.1. Build-time dependencies"
+### 2.1. Build-time dependencies
+
+* **Alpine Linux**: binutils bzip2 cmake coreutils curl findutils g++ gawk gcc
+ git grep gzip libc-dev linux-headers lzip make musl-dev
+ net-tools patch perl perl-xml-parser procps sed tar
+ util-linux wget xz zip
+* **Debian/-derived Linux**: binutils bzip2 clzip cmake coreutils curl findutils
+ g++ gawk gcc git grep gzip hostname libc6-dev
+ libxml-parser-perl lzma make patch perl procps sed
+ tar util-linux wget xz-utils zip
+* **OpenSUSE Linux**: binutils bzip2 cmake coreutils curl findutils gawk gcc
+ gcc-c++ git grep gzip hostname linux-glibc-devel lzip make
+ patch perl perl-XML-Parser procps sed tar util-linux wget
+ xz zip
+
+> N.B. Busybox is not supported.
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+[//]: # "{{{ 2.1.1. Alpine-specific notate bene"
+#### 2.1.1. Alpine-specific notate bene
+
+Some packages (*coreutils*, *grep*, and *tar*, among others) override Alpine's
+BusyBox utilities of the same name, as the latter are either non-conformant or
+defective.
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+[//]: # "{{{ 2.2. Deployment"
+### 2.2. Deployment
+
+On successful completion of the build, a ZIP archive containing the Midipix
+distribution will be created. Extract its contents on the target machine, run
+``bash.bat``, and then ``/install.sh`` inside the resulting self-contained
+Midipix installation shell window.
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+[//]: # "{{{ 2.3. System requirements"
+### 2.3. System requirements
+
+The following system requirements are assessed on build hosts equipped with the
+following hardware at minimum:
+* Intel(R) Xeon(R) CPU W3520 @ 2.67GHz (8 cores)
+* 7200 RPM SATA 3.1 HDD
+* 6 GB RAM
+
+| Target architecture | Build type | Distribution kinds selected | Average build time | Disk space required |
+| ------------------- | ---------- | --------------------------- | ------------------ | ------------------- |
+| nt64 | debug | minipix,rpm,zipdist | 2 hours | 57.60 GB |
+| nt64 | release | minipix,rpm,zipdist | 1 hours 45 minutes | 35.16 GB |
+
+Package archive files and/or Git repositories additionally consume at least
+1.70 GB.
+
+*(last update: Wed, 04 Mar 2020 14:07:26 +0000)*
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+
+[//]: # "{{{ 3. Common tasks"
+## 3. Common tasks
+
+Rebuild set of packages in isolation, along w/ their dependencies, if any, as
+needed, or forcibly, respectively:
+```shell
+./build.sh [ ... ] -r mc,zsh
+./build.sh [ ... ] -r \*mc,zsh
+./build.sh [ ... ] -r \*\*mc,zsh
+```
+
+Restart the ``configure``, ``build``, and ``install`` steps of the ``coreutils``
+package.
+```shell
+./build.sh -r coreutils:configure,build,install
+```
+
+Rebuild entire build group:
+```shell
+./build.sh [ ... ] -r ALL native_runtime
+```
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+[//]: # "{{{ 3.1. Fault-tolerant & highly optimised 3D laser show-equipped usage screen"
+## 3.1. 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] [-p jobs] [-P] [-r [*[*]]ALL|LAST|name[,..][:step,..]] [-R] [-v[v[v[v]]]]
+ [--as-needed] [--debug-minipix] [<group>[ ..]]
+
+ -a nt32|nt64 Selects 32-bit or 64-bit architecture; defaults to nt64.
+ -b debug|release Selects debug or release build; 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 Show this screen.
+ -p jobs Enables parallelisation at group-level, whenever applicable.
+ -P 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 for convenience.
+ -r [*[*]]ALL[:step,..]|LAST|name[,..][:step,..]
+ Restart all packages/the specified comma-separated package(s)
+ completely or at optionally specified comma-separated step(s)
+ or restart the last failed package and resume build.
+ Prepend w/ `*' to automatically include dependencies and `**' to
+ forcibly rebuild all dependencies.
+
+ Currently defined steps are:
+ fetch_wget, fetch_git, fetch_extract,
+ configure_patch_pre, configure_autotools, configure_patch, configure,
+ build,
+ install_subdirs, install_make, install_files, install_libs, install, and install_rpm.
+ -R Ignore build failures, skip printing package logs, and continue
+ building (relaxed mode.)
+ -v[v[v[v]]] Be verbose; -vv: always print package logs; -vvv: set xtrace during package builds; -vvvv: logs fileops.
+ --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.
+ <group>[ ..] One of: host_deps, host_deps_rpm, host_toolchain, host_tools, minipix,
+ native_packages, native_runtime, native_toolchain, and/or native_tools.
+```
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+
+[//]: # "{{{ 5. Build variables"
+## 5. Build variables
+
+The following variables are primarily defined in ``midipix.env`` and may be
+overriden on a per-build basis on the command-line after the last argument,
+if any, e.g.:
+
+```shell
+./build.sh -a nt64 -b release -D minipix,zipdist -P -v PREFIX_ROOT="${HOME}/midipix_tmp"
+```
+
+Furthermore, ``${HOME}/midipix_build.vars``, ``${HOME}/.midipix_build.vars``,
+and/or ``../midipix_build.vars`` are sourced during build initialisation and
+may contain additional overrides, particularly ``${DEFAULT_GITROOT_HEAD}``.
+
+| Variable name | Default value | Description |
+| ---------------- | ------------------------------- | ----------------------------------------------------------------------------- |
+| ARCH | nt64 | Target 32-bit (nt32) or 64-bit (nt64) architecture |
+| BUILD | debug | Build w/ debugging (debug) or release compiler flags |
+| BUILD_DLCACHEDIR | ${PREFIX_ROOT}/dlcache | Absolute pathname to package downloads cache root directory |
+| BUILD_WORKDIR | ${PREFIX}/tmp | Absolute pathname to temporary package build root directory |
+| PREFIX | ${PREFIX_ROOT}/${ARCH}/${BUILD} | Absolute pathname to architecture- & build type-specific build root directory |
+| PREFIX_CROSS | ${PREFIX}/${DEFAULT_TARGET} | Absolute pathname to toolchain root directory |
+| PREFIX_MINGW32 | ${PREFIX}/x86_64-w64-mingw32 | Absolute pathname to MinGW toolchain root directory |
+| PREFIX_MINIPIX | ${PREFIX}/minipix | Absolute pathname to minipix distribution root directory |
+| PREFIX_NATIVE | ${PREFIX}/native | Absolute pathname to cross-compiled packages root directory |
+| PREFIX_ROOT | ${HOME}/midipix | Absolute pathname to top-level directory |
+| PREFIX_RPM | ${PREFIX}/rpm | Absolute pathname to package RPM archive root directory |
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+[//]: # "{{{ 5.1. Package variables"
+## 5.1. 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 build group the package pertains to and defined in its corresponding
+file beneath ``groups/``, or package-specific overrides defined either in the
+latter and/or in its corresponding file beneath ``vars/``. Additionally,
+overrides may be specified on a per-build basis on the command-line after the
+last argument, with each variable prefixed w/ ``PKG_``, e.g.: ``./build.sh
+[ ... ] PKG_ZSH_CC="/bin/false"``.
+
+The minimum set of package variables that must be provided is ``SHA256SUM, URL,
+VERSION`` and/or ``URLS_GIT``, respectively.
+
+| Package variable name | Description |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| AR | Command- or pathname of toolchain library archive editor (ar(1)) |
+| BASE_DIR | Absolute pathname to package build root directory beneath ${BUILD_WORKDIR} |
+| BUILD_DIR | Directory name of package build directory beneath ${PKG_BASE_DIR} |
+| BUILD_STEPS_DISABLE | List of build steps to disable during package build |
+| BUILD_TYPE | Cross-compiled toolchain (cross,) host (host,) or cross-compiled package build type |
+| CC | Command- or pathname of toolchain C compiler (cc(1)) |
+| CFLAGS_BUILD_EXTRA | Additional C compiler flags during package (make(1)) build |
+| CFLAGS_CONFIGURE | C compiler flags during package (autotools or similar) configuration |
+| CFLAGS_CONFIGURE_EXTRA | Additional C compiler flags during package (GNU autotools or similar) configuration |
+| CONFIG_CACHE | List of GNU autotools configuration cache variables |
+| CONFIG_CACHE_EXTRA | Additional list of GNU autotools configuration cache variables |
+| CONFIG_CACHE_LOCAL | Additional list of GNU autotools configuration cache variables |
+| CONFIGURE | Command- or pathname to package (GNU autotools or similar) configuration script |
+| CONFIGURE_ARGS | List of arguments to package (GNU autotools or similar) configuration script |
+| CONFIGURE_ARGS_EXTRA | Additional list of arguments to package (GNU autotools or similar) configuration script |
+| CXX | Command- or pathname of toolchain C++ compiler (c++(1)) |
+| CXXFLAGS_CONFIGURE | List of C++ compiler flags during package (autotools or similar) configuration |
+| CXXFLAGS_CONFIGURE_EXTRA | Additional list of C++ compiler flags during package (autotools or similar) configuration |
+| DEPENDS | List of package-package dependencies |
+| DESTDIR | Directory name of package installation destination directory beneath ${PKG_BASE_DIR} |
+| DISABLED | Disable package |
+| ENV_VARS_EXTRA | List of double colon-separated environment variable equality sign-separated name-value pairs to set during package build |
+| FNAME | Filename of package archive file |
+| FORCE_AUTORECONF | Forcibly run autoreconf -fiv prior to package (GNU autotools or similar) configuration |
+| GITROOT | midipix packages Git URL prefix |
+| INHERIT_FROM | Inherit variables from named package |
+| INSTALL_FILES | Whitespace-separated list of files to manually install into the package installation destination directory beneath ${PKG_BASE_DIR} |
+| INSTALL_FILES_DESTDIR | Whitespace-separated list of files to initialise the package installation destination directory beneath ${PKG_BASE_DIR} with |
+| INSTALL_FILES_DESTDIR_EXTRA | Additional whitespace-separated list of files to initialise the package installation destination directory beneath ${PKG_BASE_DIR} with |
+| INSTALL_TARGET | Name of package build make(1) installation target |
+| INSTALL_TARGET_EXTRA | Additional name of package build make(1) installation target |
+| IN_TREE | Build package in-tree within ${PKG_SUBDIR} |
+| LDFLAGS_BUILD_EXTRA | Additional linker flags during package (make(1)) build |
+| LDFLAGS_CONFIGURE | Linker flags during package (autotools or similar) configuration |
+| LDFLAGS_CONFIGURE_EXTRA | Additional linker flags during package (autotools or similar) configuration |
+| LIBTOOL | Command- or pathname of libtool |
+| MAKE | Command line of make(1) |
+| MAKEFLAGS_BUILD | List of make(1) flags during package (make(1)) build |
+| MAKEFLAGS_BUILD_EXTRA | Additional list of make(1) flags during package (make(1)) build |
+| MAKEFLAGS_INSTALL | List of make(1) flags during package (make(1)) installation |
+| MAKEFLAGS_INSTALL_EXTRA | Additional list of make(1) flags during package (make(1)) installation |
+| MAKE_INSTALL_VNAME | Variable name of make(1) installation destination directory variable during package (make(1)) installation |
+| NO_CLEAN | Inhibit cleaning of package build directory beneath ${PKG_BASE_DIR} pre-finish |
+| NO_CLEAN_BASE_DIR | Inhibit cleaning of package build root directory beneath ${BUILD_WORKDIR} |
+| NO_LOG_VARS | Inhibit logging of build & package variables pre-package build |
+| PATCHES_EXTRA | Additional list of patches to apply |
+| PKG_CONFIG | Command- or pathname of pkg-config(1) |
+| PKG_CONFIG_PATH | pkg-config(1) search path |
+| PKGLIST_DISABLE | Inhibit inclusion into ${PREFIX}/pkglist.${PKG_BUILD_TYPE} |
+| PREFIX | Absolute pathname of top-level installation directory and package search path |
+| PYTHON | Command- or pathname of Python |
+| RANLIB | Command- or pathname of toolchain library archive index generator (ranlib(1)) |
+| RPM_DISABLE | Inhibit creation of RPM archive |
+| SHA256SUM | SHA-256 message digest of package archive |
+| SUBDIR | Name of extracted archive or git-{clone,pull}(1)'d directory |
+| TARGET | Dash-separated {build,host,target} triplet |
+| URL | URL to package archive |
+| URLS_GIT | List of package Git URL(s) (*name*=*URL*@*branch*) |
+| VERSION | Package version |
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+
+[//]: # "{{{ 6. References"
+## 6. References
+
+* ``Sun, 25 Apr 2016 09:04:08 +0000 [1]`` <a href="https://www.musl-libc.org/faq.html" id="r1">musl FAQ</a>
+* ``Wed, 04 Mar 2020 12:57:39 +0000 [2]`` <a href="https://midipix.org/" id="r2">midipix</a>
+* ``Wed, 04 Mar 2020 13:36:19 +0000 [3]`` <a href="https://midipix.org/#sec-midipix" id="r3">midipix - what is midipix, and how is it different?</a>
+
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
+
+[modeline]: # ( vim: set ff=dos tw=0: )
|