From 76e2d168f8f13ff4381da1f0664b88bc6a543bd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luc=C3=ADa=20Andrea=20Illanes=20Albornoz?= Date: Mon, 13 Mar 2023 10:57:25 +0100 Subject: etc/README.md: updated. --- etc/README.md | 252 ++++++++++++++++++++++++++++++---------------------------- 1 file changed, 130 insertions(+), 122 deletions(-) (limited to 'etc') 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__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 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] [[=]|=[ ..]] - - -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. - - [ ..] 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. - - =[ ..] - 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 | | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | @@ -896,6 +800,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] [[=]|=[ ..]] + + -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. + + [ ..] 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. + + =[ ..] + Override build or package variable. +``` + +[Back to top](#table-of-contents) + [//]: # "}}}" [//]: # "{{{ 4.6. ``pkgtool.sh``" ## 4.6. ``pkgtool.sh`` -- cgit v1.2.3