diff options
Diffstat (limited to 'etc')
-rw-r--r-- | etc/README.md | 78 | ||||
-rw-r--r-- | etc/build.msgs.en | 3 | ||||
-rw-r--r-- | etc/build.usage | 5 | ||||
-rw-r--r-- | etc/build.usage.short | 5 | ||||
-rw-r--r-- | etc/pkgtool.msgs.en | 1 | ||||
-rw-r--r-- | etc/pkgtool.usage | 5 |
6 files changed, 69 insertions, 28 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. diff --git a/etc/build.msgs.en b/etc/build.msgs.en index ddacb97b..30545eb2 100644 --- a/etc/build.msgs.en +++ b/etc/build.msgs.en @@ -12,7 +12,8 @@ MSG_build_killed_pids="1;Killed PID(s): %s"; MSG_build_reset_pkg_state="1;Reset package state for: %s"; MSG_build_resolved_deps="1;Resolved \`%s' dependencies."; MSG_build_resolving_deps="1;Resolving \`%s' dependencies..."; -MSG_build_unknown_dep="2;Error: dependency \`%s' of \`%s' unknown."; +MSG_build_unknown_dep="2;Warning: dependency \`%s' of \`%s' unknown."; +MSG_build_unknown_deps="0;Warning: packages with unknown dependencies."; MSG_group_begin="4;[%3d%% ] [%03d/%03d] Starting \`%s' build group..."; MSG_group_finish="4;[%3d%% ] [%03d/%03d] Finished \`%s' build group."; diff --git a/etc/build.usage b/etc/build.usage index ed3c7df6..0f8dfddb 100644 --- a/etc/build.usage +++ b/etc/build.usage @@ -4,7 +4,8 @@ [90m[[33m-[93mv[90m] [[33m-[93mV [90m[[93m+[90m][93mtag[90m|[93mpat[90m[[93m,[90m..][90m][0m [90m[[33m--[93mas-needed[90m] [[33m--[93mdebug-minipix[90m] [[33m--[93mreset-state[90m] [[33m--[93mroar[90m][0m - [90m[[33m--[93mtheme theme[90m] [[[93m=[90m][90m<[93mgroup[90m>|<[93mvariable name[90m>[93m=[90m<[93mvariable override[90m>[ ..]][0m + [90m[[33m--[93mtheme theme[90m] + [[[93m=[90m][90m<[93mgroup[90m[[93m,[90m..][ ..][90m>|<[93mvariable name[90m>[93m=[90m<[93mvariable override[90m>[ ..]][0m [33m-[93ma nt32[90m|[93mnt64[0m [96mSelects 32-bit or 64-bit architecture; defaults to [93mnt64[96m.[0m [33m-[93mb debug[90m|[93mrelease[0m [96mSelects debug or release build kind; defaults to [93mdebug[96m.[0m @@ -86,7 +87,7 @@ [33m--[93mreset-state[0m [96mReset package build step state on exit.[0m [33m--[93mtheme theme[0m [96mSet theme.[0m - [90m<[93mgroup[90m>[ ..][96m One of: [93mdev_packages[90m,[93m dist[90m,[93m host_deps[90m,[93m host_deps_rpm[90m,[0m + [90m<[93mgroup[90m>[[93m,[90m..][ ..][96m One of: [93mdev_packages[90m,[93m dist[90m,[93m host_deps[90m,[93m host_deps_rpm[90m,[0m [93mhost_toolchain[90m,[93m host_tools[90m,[93m minipix[90m,[93m native_packages[90m,[0m [93mnative_runtime[90m,[93m native_toolchain[90m,[93m native_tools[90m.[0m diff --git a/etc/build.usage.short b/etc/build.usage.short index fc966991..192b9e43 100644 --- a/etc/build.usage.short +++ b/etc/build.usage.short @@ -4,7 +4,8 @@ [90m[[33m-[93mv[90m] [[33m-[93mV [90m[[93m+[90m][93mtag[90m|[93mpat[90m[[93m,[90m..][90m][0m [90m[[33m--[93mas-needed[90m] [[33m--[93mdebug-minipix[90m] [[33m--[93mreset-state[90m] [[33m--[93mroar[90m][0m - [90m[[33m--[93mtheme theme[90m] [[[93m=[90m][90m<[93mgroup[90m>|<[93mvariable name[90m>[93m=[90m<[93mvariable override[90m>[ ..]][0m + [90m[[33m--[93mtheme theme[90m] + [[[93m=[90m][90m<[93mgroup[90m[[93m,[90m..][ ..][90m>|<[93mvariable name[90m>[93m=[90m<[93mvariable override[90m>[ ..]][0m [33m-[93ma nt32[90m|[93mnt64[0m [96mSelects 32-bit or 64-bit architecture; defaults to [93mnt64[96m.[0m [33m-[93mb debug[90m|[93mrelease[0m [96mSelects debug or release build kind; defaults to [93mdebug[96m.[0m @@ -14,7 +15,7 @@ [33m-[93mr [90m[[93m*[90m[[93m*[90m[[93m*[90m]]][93mname[90m[[93m,[90m..][[93m:ALL[90m|[93mLAST[90m|[[93m^[90m|[93m<[90m|[93m<=[90m|[93m>[90m|[93m>=[90m][93mstep,[90m..][0m [33m-[93mv[90m [96mIncrease logging verbosity.[0m - [90m<[93mgroup[90m>[ ..][96m One of: [93mdev_packages[90m,[93m dist[90m,[93m host_deps[90m,[93m host_deps_rpm[90m,[0m + [90m<[93mgroup[90m>[[93m,[90m..][ ..][96m One of: [93mdev_packages[90m,[93m dist[90m,[93m host_deps[90m,[93m host_deps_rpm[90m,[0m [93mhost_toolchain[90m,[93m host_tools[90m,[93m minipix[90m,[93m native_packages[90m,[0m [93mnative_runtime[90m,[93m native_toolchain[90m,[93m native_tools[90m.[0m diff --git a/etc/pkgtool.msgs.en b/etc/pkgtool.msgs.en index 1fe000f0..05331ab6 100644 --- a/etc/pkgtool.msgs.en +++ b/etc/pkgtool.msgs.en @@ -24,7 +24,6 @@ MSG_mirror_pkg_skip_no_urls="1;Package \`%s' has neither archive nor Git URL(s), MSG_rdepends_pkg_deps_rev_none="1;Package \`%s' has no reverse dependencies."; MSG_rdepends_pkgs_deps_rev_disabled="2;Reverse dependencies of \`%s' (disabled packages:) [0m%s"; -MSG_rdepends_pkgs_deps_rev="2;Reverse dependencies of \`%s': [0m%s"; MSG_rdepends_pkgs_deps_rev_recurse="2;Recursive reverse dependencies of \`%s': %s"; MSG_tarball_created="2;Created compressed tarball of \`%s' and \`%s_stderrout.log'."; diff --git a/etc/pkgtool.usage b/etc/pkgtool.usage index 7fc7e77b..a07f8e47 100644 --- a/etc/pkgtool.usage +++ b/etc/pkgtool.usage @@ -1,4 +1,4 @@ -[97musage[90m: [33m./[93mpkgtool.sh [90m[[33m-[93ma nt32[90m|[93mnt64[90m] [[33m-[93mb [93mdebug[90m|[93mrelease[90m] [[33m-[93me[90m|[33m-[93mf[90m|[33m-[93mi[90m|[33m-[93mm [90m<[93mdname[90m> [33m-[93mM [90m<[93mdname[90m>|[33m-[93mp[90m|[33m-[93mr[90m|[33m-[93mR[90m|[33m-[93mt[90m][0m +[97musage[90m: [33m./[93mpkgtool.sh [90m[[33m-[93ma nt32[90m|[93mnt64[90m] [[33m-[93mb [93mdebug[90m|[93mrelease[90m] [[33m-[93me[90m|[33m-[93mf[90m|[33m-[93mi[90m|[33m-[93mm [90m<[93mdname[90m> [33m-[93mM [90m<[93mdname[90m>|[33m-[93mp[90m|[33m-[93mr[90m|[33m-[93mt[90m][0m [90m[[93m--theme theme[90m] [90m[[33m-[93mv[90m][0m [90m[<[93mvariable name[90m>[93m=[90m<[93mvariable override[90m>[ ..]] [93mname[90m[,[93mname[90m..][0m @@ -12,8 +12,7 @@ [96mSpecify "" or '' as <dname> to default to the defaults in[0m [93m${HOME}/pkgtool.vars[96m, if present.[0m [33m-[93mp [90m<[93mlog_fname[90m>[0m [96mProfile last build.[0m - [33m-[93mr [96mList reverse dependencies of single named package.[0m - [33m-[93mR [96mList recursive reverse dependencies of single named package.[0m + [33m-[93mr [96mList recursive reverse dependencies of single named package.[0m [33m-[93mt [96mProduce tarball of package build root directory and build log[0m [96mfile for the purpose of distribution given build failure.[0m [33m-[93mv [96mIncrease verbosity.[0m |