diff options
Diffstat (limited to 'etc/README.md')
| -rw-r--r-- | etc/README.md | 78 |
1 files changed, 59 insertions, 19 deletions
diff --git a/etc/README.md b/etc/README.md index 908675bf..5d16ed47 100644 --- a/etc/README.md +++ b/etc/README.md @@ -324,16 +324,48 @@ build group e.g. the ``dev_packages`` build group, as long as the default set of groups or as overriden on the command line does not entail group membership conflicts. Build groups files beneath ``groups.d/`` named ``[0-9][0-9][0-9].<group name>.group`` -contain package variable defaults, the alphabetically sorted list of contained -packages in ``<upper case group name>_PACKAGES``, and their package variables +contain package variable defaults, optionally the alphabetically sorted list of contained +packages, if any, in ``<upper case group name>_PACKAGES``, and their package variables sorted alphabetically with the exception of ``${PKG_DEPENDS}`` (if present,) ``${PKG_SHA256SUM}``, ``${PKG_URL}``, and ``${PKG_VERSION}``, and/or ``${PKG_URLS_GIT}``, -which are specified in this order. +which are specified in this order. Build group files require the following epilogue, the +parameters enclosed in square brackets being optional: + +```shell +ex_pkg_register_group "<group name>" "${RTL_FILEOP_SOURCE_FNAME}" [["owner|copy"] ["auto|noauto"]]; + +# vim:filetype=sh textwidth=0 +``` + +If ``copy`` is specified, the build group will copy all of its packages from their respective +build groups without taking ownership thereof, if ``owner`` is specified, the default, the build +group owns all of its packages. If ``noauto`` is specified, the build group will not be added to +the list of build groups to build by default, if ``auto`` is specified, the build group will be +added to the list of build groups to build by default. -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.4](#44-package-variables).) -Consult section [3.5](#35-patches-and-vars-files) if the package to be added +If a build group that specifies ``copy`` should copy all of its build group variables from another +build group, use the following code: + +```shell +ex_pkg_copy_group_vars "<source group name>" "<destination group name>"; +``` + +Additionally, single package files may be added beneath ``groups.d/[0-9][0-9][0-9].<group name>.d/``, +named ``<package name>.package`` containing the package's variables, with the following epilogue, +the parameters enclosed in square brackets being optional: + +```shell +ex_pkg_register "<package_name>" "${RTL_FILEOP_SOURCE_FNAME}" ["<group name>"]; + +# vim:filetype=sh textwidth=0 +``` + +1. Pick a build group according to the criteria mentioned and specifiy the set of package +variables required (see above and section [4.4](#44-package-variables)) in either the +corresponding group file or a single package file; in the former case, do also add the +package to the build group's list of contained packages. + +2. 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 of package build steps and how they are overriden. @@ -667,8 +699,9 @@ usage: rtl_install [-i] [-I ifs] [-n] [-p name=val] [-v] prefix spec_list The following variables are package-specific and receive their value from either top-level defaults defined in ``vars.env.d/*.env``, build group-specific defaults from the build group the package pertains to and defined in its corresponding file beneath -``groups.d/``, or package-specific overrides defined either in the latter and/or in its -corresponding file beneath ``vars/``, with one of the following prefixes: +``groups.d/`` or ``groups.d/[0-9][0-9][0-9].<group name>.d/``, or package-specific overrides +defined either in the latter and/or in its corresponding file beneath ``vars/``, with one of +the following prefixes: | Variable name prefix | | ------------------------------------------------- | @@ -829,7 +862,8 @@ usage: ./build.sh [-a nt32|nt64] [-b debug|release] [-C dir[,..]] [-D kind[ [-v] [-V [+]tag|pat[,..]] [--as-needed] [--debug-minipix] [--reset-state] [--roar] - [--theme theme] [[=]<group>|<variable name>=<variable override>[ ..]] + [--theme theme] + [[=]<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. @@ -873,7 +907,8 @@ usage: ./build.sh [-a nt32|nt64] [-b debug|release] [-C dir[,..]] [-D kind[ 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, install_rpm, and clean. + install_make, install_files, install, install_rpm, + and clean. Additionally, the following virtual steps are provided: @fetch, @configure, @build, @install, @clean, and finish. @@ -910,11 +945,9 @@ usage: ./build.sh [-a nt32|nt64] [-b debug|release] [-C dir[,..]] [-D kind[ --reset-state Reset package build step state on exit. --theme theme Set theme. - <group>[ ..] One of: - host_tools, host_deps, host_deps_rpm, - cross_toolchain, host_toolchain, - native_packages, native_runtime, native_toolchain, native_tools, - minipix, dist, dev_packages + <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. @@ -929,7 +962,7 @@ usage: ./build.sh [-a nt32|nt64] [-b debug|release] [-C dir[,..]] [-D kind[ ## 4.6. ``pkgtool.sh`` ``` -usage: ./pkgtool.sh [-a nt32|nt64] [-b debug|release] [-e|-f|-i|-m <dname> -M <dname>|-p|-r|-R|-t] +usage: ./pkgtool.sh [-a nt32|nt64] [-b debug|release] [-e|-f|-i|-m <dname> -M <dname>|-p|-r|-t] [--theme theme] [-v] [<variable name>=<variable override>[ ..]] name[,name..] @@ -943,8 +976,7 @@ usage: ./pkgtool.sh [-a nt32|nt64] [-b debug|release] [-e|-f|-i|-m <dname> -M <d Specify "" or '' as <dname> to default to the defaults in ${HOME}/pkgtool.vars, if present. -p <log_fname> Profile last build. - -r List reverse dependencies of single named package. - -R List recursive reverse dependencies of single named package. + -r List recursive reverse dependencies of single named package. -t Produce tarball of package build root directory and build log file for the purpose of distribution given build failure. -v Increase verbosity. @@ -968,6 +1000,14 @@ by setting ``ARG_MIRROR_DNAME_GIT=...``. [//]: # "{{{ 4.7. Bourne shell coding rules" ## 4.7. Bourne shell coding rules +> N.B. Input sanitisation is mandatory whenever input may form part of a parameter name, most usually +when indexing with input as a key into a (pseudo-)hash, e.g. PKG_ZSH_<...input...>; failing to do so +may introduce security vulnerabilities (e.g.: $(arbitrary_command) and ${arbitrary_variable} facilitating +code execution and information disclosure, resp.) +Do not use this code and these coding rules if this is not possible or impractical. + +*(reproduced from [[shrtl](https://github.com/lalbornoz/shrtl/blob/master/README.md)])* + If no rationale is specified for any specific point, the rationale is avoidance of undefined behaviour and/or implicit behaviour contingent on often subtle special cases, both of which are prone to cause hard to debug or even diagnose bugs. |