From 6c5fad831329c6949a858a956fea117c4736f08d Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Tue, 2 Nov 2021 20:46:23 +0300 Subject: Document worker scripts --- doc/manual.cli | 609 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 550 insertions(+), 59 deletions(-) diff --git a/doc/manual.cli b/doc/manual.cli index 38b52e0..86b90ba 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -917,14 +917,38 @@ modules (\c{}) and the list of configuration options and variables The re-executed \c{bbot} worker then proceeds to test the package from the repository by executing the following commands, collectively called a \i{worker script}. Each command has a unique \i{step id} that can be used as a -breakpoint as well as a prefix in the \c{}, +breakpoint and normally as a prefix in the \c{}, \c{}, and \c{} values as discussed in -\l{#arch-controller Controller Logic}. Some step ids have fallback step ids -(listed in parenthesis) which are used in the absence of the primary step id -values. The \c{<>}-values are from the task manifest and the environment. +\l{#arch-controller Controller Logic}. The \c{<>}-values are from the task +manifest and the environment though some are assigned by the worker during the +script execution (configuration directories, UUIDs, etc). + +Some prefix step ids have fallback step ids which are used in the absence of +the primary step id values. If the prefix step id differs from the breakpoint +step id and/or has the fallback step ids, then they are listed in parenthesis: +the prefix id before the colon and the fallback ids after it. + +Some commands have no configuration or environment options or variables. Such +commands have only breakpoint step ids associated, which are listed in square +brackets. + +Note that the worker script varies for different primary package types. The +\c{bbot} worker classifies the primary package based on the configuration type +in which it is built: \c{module} (build system module packages), \c{host} +(packages such as source code generators, marked with the \c{requires: host} +manifest value; see \l{bpkg#manifest-package Package Manifest} for details), +and \c{target} (all other packages). + +Note also that the \c{*.configure.build} step configures potentially multiple +packages (primary package, tests, etc) in potentially multiple configurations +by always using the \c{bpkg.global.configure.build} prefix step id for global +(as opposed to package-specific) \l{bpkg-pkg-build(1)} options. The +\c{bpkg.global.configure.build} prefix id has no fallback ids. + +Worker script for \c{target} packages: \ -# bpkg.create +# bpkg.create (bpkg.target.create : b.create, bpkg.create) # bpkg -V create @@ -936,9 +960,13 @@ bpkg -v add # bpkg -v fetch --trust -# bpkg.configure.build +# bpkg.configure.build ( +# bpkg.global.configure.build, +# (bpkg.target.configure.build : b.configure, bpkg.configure.build)) # -bpkg -v build --yes --configure-only / +bpkg -v build --configure-only \\ + / \\ + [[ ]...] # bpkg.update # @@ -952,20 +980,15 @@ bpkg -v update bpkg -v test } -# For each package referred to by the tests, examples, or benchmarks -# package manifest values not excluded by the bbot controller: +# For each (runtime) tests, examples, or benchmarks package referred +# to by the task manifest: # { - # bpkg.test-separate.configure.build (bpkg.configure.build) - # - bpkg -v build --yes --configure-only \\ - ' []' - - # bpkg.test-separate.update (bpkg.update) + # bpkg.test-separate.update ( : bpkg.update) # bpkg -v update - # bpkg.test-separate.test (bpkg.test) + # bpkg.test-separate.test ( : bpkg.test) # bpkg -v test } @@ -981,51 +1004,61 @@ bpkg -v update # operation: # { - # b.test-installed.create + # b.test-installed.create ( : b.create) # b -V create - # b.test-installed.configure + # For each test subproject: # - b -v configure + { + # b.test-installed.configure ( : b.configure) + # + b -v configure + } # b.test-installed.test # b -v test } - # If any of the tests, examples, or benchmarks package manifest - # values are not excluded by the bbot controller: + # If task manifest refers to any (runtime) tests, examples, or + # benchmarks packages. # { - # bpkg.test-installed.create (bpkg.create) + # bpkg.test-separate-installed.create ( + # bpkg.test-separate-installed.create_for_target : + # bpkg.test-separate-installed.create) # bpkg -V create - # bpkg.test-installed.configure.add (bpkg.configure.add) + # bpkg.test-separate-installed.configure.add ( + # : bpkg.configure.add) # bpkg -v add - # bpkg.test-installed.configure.fetch (bpkg.configure.fetch) + # bpkg.test-separate-installed.configure.fetch ( + # : bpkg.configure.fetch) # bpkg -v fetch --trust - # For each package referred to by the tests, examples, or - # benchmarks package manifest values not excluded by the - # bbot controller: + # bpkg.test-separate-installed.configure.build ( + # bpkg.global.configure.build, + # (bpkg.test-separate-installed.configure.build_for_target : + # bpkg.test-separate-installed.configure.build)) # - { - # bpkg.test-separate-installed.configure.build ( - # bpkg.configure.build) - # - bpkg -v build --yes --configure-only \\ - ' []' + bpkg -v build --configure-only \\ + [ ]... \\ + ?sys: - # bpkg.test-separate-installed.update (bpkg.update) + # For each (runtime) tests, examples, or benchmarks package + # referred to by the task manifest: + # + { + # bpkg.test-separate-installed.update ( : bpkg.update) # bpkg -v update - # bpkg.test-separate-installed.test (bpkg.test) + # bpkg.test-separate-installed.test ( : bpkg.test) # bpkg -v test } @@ -1041,47 +1074,505 @@ bpkg -v update # This step id can only be used as a breakpoint. \ -For details on configuring and testing installation refer to -\l{#arch-controller Controller Logic}. +Worker script for \c{host} packages: + +\ +# If configuration is self-hosted: +# +{ + # bpkg.create (bpkg.host.create : b.create, bpkg.create) + # + bpkg -V create --type host -d \\ + +} +# +# Otherwise: +# +{ + # [bpkg.create] + # + b -V create(, cc) config.config.load=~host + bpkg -v create --existing --type host -d +} + +# bpkg.configure.add +# +bpkg -v add -d + +# bpkg.configure.fetch +# +bpkg -v fetch -d --trust + +# If configuration is self-hosted and config.install.root is specified: +# +{ + # bpkg.create (bpkg.target.create : b.create, bpkg.create) + # + bpkg -V create -d \\ + + + # [bpkg.link] + # + bpkg -v link -d + + # bpkg.configure.add + # + bpkg -v add -d + + # bpkg.configure.fetch + # + bpkg -v fetch -d --trust +} + +# If task manifest refers to any build-time tests, examples, or +# benchmarks packages: +# +{ + # bpkg.create (bpkg.target.create : b.create, bpkg.create) + # + bpkg -V create -d \\ + + + # [bpkg.create] + # + b -V create(, cc) config.config.load=~build2 + bpkg -v create --existing --type build2 -d + + # [bpkg.link] + # + bpkg -v link -d + bpkg -v link -d + bpkg -v link -d + + # If configuration is self-hosted and config.install.root is + # specified: + # + { + # [bpkg.link] + # + bpkg -v link -d + } + + # bpkg.configure.add + # + bpkg -v add -d + + # bpkg.configure.fetch + # + bpkg -v fetch -d --trust +} + +# bpkg.configure.build (bpkg.global.configure.build) +# +# Notes: +# +# - Some parts may be omitted. +# +# - Parts related to different configurations have different prefix +# step ids: +# +# bpkg.host.configure.build for +# bpkg.target.configure.build for +# bpkg.target.configure.build for +# +# - All parts have the same fallback step ids: b.configure and +# bpkg.configure.build. +# +bpkg -v build --configure-only \\ +\\ +{ --config-uuid }+ \\ +/ \\ +\\ +{ --config-uuid }+ \\ +/ \\ +\\ +{ --config-uuid }+ \\ +{ [ test-version-constraint>]... } \\ +\\ +{ --config-uuid }+ \\ +{ [ test-version-constraint>]... } + +# bpkg.update +# +bpkg -v update -d + +# If the test operation is supported by the package: +# +{ + # bpkg.test + # + bpkg -v test -d +} + +# If configuration is self-hosted, then for each runtime tests, +# examples, or benchmarks package referred to by the task manifest: +# +{ + # bpkg.test-separate.update ( : bpkg.update) + # + bpkg -v update -d + + # bpkg.test-separate.test ( : bpkg.test) + # + bpkg -v test -d +} + +# For each build-time tests, examples, or benchmarks package referred +# to by the task manifest: +# +{ + # bpkg.test-separate.update ( : bpkg.update) + # + bpkg -v update -d + + # bpkg.test-separate.test ( : bpkg.test) + # + bpkg -v test -d +} + +# If configuration is self-hosted and config.install.root is specified: +# +{ + # bpkg.install + # + bpkg -v install -d + + # If the package contains subprojects that support the test + # operation: + # + { + # b.test-installed.create ( : b.create) + # + b -V create + + # For each test subproject: + # + { + # b.test-installed.configure ( : b.configure) + # + b -v configure + } + + # b.test-installed.test + # + b -v test + } + + # If task manifest refers to any tests, examples, or benchmarks + # packages: + # + { + # bpkg.test-separate-installed.create ( + # bpkg.test-separate-installed.create_for_host : + # bpkg.test-separate-installed.create) + # + bpkg -V create --type host -d \\ + + + # If task manifest refers to any runtime tests, examples, or + # benchmarks packages: + # + { + # bpkg.test-separate-installed.configure.add ( + # : bpkg.configure.add) + # + bpkg -v add -d + + # bpkg.test-separate-installed.configure.fetch ( + # : bpkg.configure.fetch) + # + bpkg -v fetch -d --trust + } + + # If task manifest refers to any build-time tests, examples, or + # benchmarks packages: + # + { + # bpkg.test-separate-installed.create ( + # bpkg.test-separate-installed.create_for_host : + # bpkg.test-separate-installed.create) + # + bpkg -V create -d \\ + + + # [bpkg.test-separate-installed.create] + # + b -V create(, cc) config.config.load=~build2 + bpkg -v create --existing --type build2 -d + + # [bpkg.test-separate-installed.link] + # + bpkg -v link -d + bpkg -v link -d + bpkg -v link -d + + # bpkg.test-separate-installed.configure.add ( + # : bpkg.configure.add) + # + bpkg -v add -d + + # bpkg.test-separate-installed.configure.fetch ( + # : bpkg.configure.fetch) + # + bpkg -v fetch -d --trust + } + + # bpkg.test-separate-installed.configure.build ( + # bpkg.global.configure.build, + # (bpkg.test-separate-installed.configure.build_for_host : + # bpkg.test-separate-installed.configure.build)) + # + # Note that any of the runtime or build-time tests related parts + # (but not both) may be omitted. + # + bpkg -v build --configure-only \\ + \\ + { --config-name }+ \\ + { [ ]... } \\ + \\ + { --config-name }+ \\ + [ ]... \\ + \\ + ?sys: + + # For each tests, examples, or benchmarks package referred + # to by the task manifest: + # + { + # bpkg.test-separate-installed.update ( : bpkg.update) + # + bpkg -v update + + # bpkg.test-separate-installed.test ( : bpkg.test) + # + bpkg -v test + } + } + + # bpkg.uninstall + # + bpkg -v uninstall -d +} + +# end +# +# This step id can only be used as a breakpoint. +\ -If the package is a build system module, then it is built and tested (using -the bundled tests) in a separate configuration that mimics the one used to -build \c{build2} itself. Note that the configuration and environment options -and variables are not passed to commands that may affect this configuration. -Such commands, therefore, have associated step ids that can only be used -as breakpoints (listed in square brackets): +Worker script for \c{module} packages: \ -# [bpkg.module.create] +# If configuration is self-hosted: +# +{ + # bpkg.create (bpkg.module.create) + # + b -V create(, ) config.config.load=~build2 \\ + + bpkg -v create --existing --type build2 -d +} # -b -V create config.config.load=~build2 -bpkg -v create --existing +# Otherwise: +# +{ + # [bpkg.create] + # + b -V create(, cc) config.config.load=~build2 + bpkg -v create --existing --type build2 -d +} -# bpkg.module.configure.add (bpkg.configure.add) +# bpkg.configure.add # -bpkg -v add +bpkg -v add -d -# bpkg.module.configure.fetch (bpkg.configure.fetch) +# bpkg.configure.fetch # -bpkg -v fetch --trust +bpkg -v fetch -d --trust -# [bpkg.module.configure.build] +# If configuration is self-hosted and config.install.root is specified: # -bpkg -v build --yes --configure-only / +{ + # bpkg.create (bpkg.module.create) + # + b -V create(, ) \\ + config.config.load=~build2 + bpkg -v create --existing --type build2 -d + + # bpkg.configure.add + # + bpkg -v add -d -# [bpkg.module.update] + # bpkg.configure.fetch + # + bpkg -v fetch -d --trust +} + +# If task manifest refers to any (build-time) tests, examples, or +# benchmarks packages: # -bpkg -v update +{ + # bpkg.create (bpkg.target.create : b.create, bpkg.create) + # + bpkg -V create -d \\ + + + # [bpkg.create] + # + b -V create(, cc) config.config.load=~host + bpkg -v create --existing --type host -d + + # [bpkg.link] + # + bpkg -v link -d + bpkg -v link -d + bpkg -v link -d + + # bpkg.configure.add + # + bpkg -v add -d + + # bpkg.configure.fetch + # + bpkg -v fetch -d --trust +} + +# bpkg.configure.build (bpkg.global.configure.build) +# +# Notes: +# +# - Some parts may be omitted. +# +# - Parts related to different configurations have different prefix +# step ids: +# +# bpkg.module.configure.build for +# bpkg.target.configure.build for +# bpkg.target.configure.build for +# +# - All parts have the same fallback step ids: b.configure and +# bpkg.configure.build. +# +bpkg -v build --configure-only \\ +\\ +{ --config-uuid }+ \\ +/ \\ +\\ +{ --config-uuid }+ \\ +/ \\ +\\ +{ --config-uuid }+ \\ +{ [ test-version-constraint>]... } + +# bpkg.update +# +bpkg -v update -d # If the test operation is supported by the package: # { - # [bpkg.module.test] + # bpkg.test # - bpkg -v test + bpkg -v test -d +} + +# For each (build-time) tests, examples, or benchmarks package referred +# to by the task manifest: +# +{ + # bpkg.test-separate.update ( : bpkg.update) + # + bpkg -v update -d + + # bpkg.test-separate.test ( : bpkg.test) + # + bpkg -v test -d +} + +# If configuration is self-hosted and config.install.root is specified: +# +{ + # bpkg.install + # + bpkg -v install -d + + # If task manifest refers to any (build-time) tests, examples, or + # benchmarks packages: + # + { + # [bpkg.test-separate-installed.create] + # + b -V create(, cc) config.config.load=~build2 + bpkg -v create --existing --type build2 -d + + # bpkg.test-separate-installed.create ( + # bpkg.test-separate-installed.create_for_module : + # bpkg.test-separate-installed.create) + # + bpkg -V create -d \\ + + + # bpkg.test-separate-installed.create ( + # bpkg.test-separate-installed.create_for_module : + # bpkg.test-separate-installed.create) + # + bpkg -V create --type host -d \\ + + + # [bpkg.test-separate-installed.link] + # + bpkg -v link -d + bpkg -v link -d + bpkg -v link -d + + # bpkg.test-separate-installed.configure.add ( + # : bpkg.configure.add) + # + bpkg -v add -d + + # bpkg.test-separate-installed.configure.fetch ( + # : bpkg.configure.fetch) + # + bpkg -v fetch -d --trust + + # bpkg.test-separate-installed.configure.build ( + # bpkg.global.configure.build, + # (bpkg.test-separate-installed.configure.build_for_module : + # bpkg.test-separate-installed.configure.build)) + # + bpkg -v build --configure-only \\ + \\ + { --config-name }+ \\ + [ ]... \\ + \\ + ?sys: + + # For each (build-time) tests, examples, or benchmarks package + # referred to by the task manifest: + # + { + # bpkg.test-separate-installed.update ( : bpkg.update) + # + bpkg -v update -d + + # bpkg.test-separate-installed.test ( : bpkg.test) + # + bpkg -v test -d + } + } + + # bpkg.uninstall + # + bpkg -v uninstall -d } + +# end +# +# This step id can only be used as a breakpoint. \ +For details on configuring and testing installation refer to +\l{#arch-controller Controller Logic}. + If a primary or test package comes from a version control-based repository, then its \c{dist} meta-operation is also tested as a part of the \c{bpkg[.*].configure.build} steps by re-distributing the source directory in @@ -1173,8 +1664,7 @@ manifest. Values in the \c{} list can be opionally prefixed with the \i{step id} or a leading portion thereof to restrict it to a specific step, operation, phase, or tool in the \i{worker script} (see \l{#arch-worker Worker -Logic}). Unprefixed values only apply to the \c{bpkg.create}, -\c{b.test-installed.create}, and \c{bpkg.test-installed.create} steps. Note +Logic}). Unprefixed values only apply to the \c{*.create[_for_*]} steps. Note that options with values can only be specified using the single argument notation. For example: @@ -1271,5 +1761,6 @@ linux*-gcc* linux-gcc-prvinstall x86_64-linux-gnu \"all default gcc\" config.ins Note also that while building and running tests against the installation the worker makes the \c{bin} subdirectory of \c{config.install.root} the first -entry in the \c{PATH} environment variable. +entry in the \c{PATH} environment variable, except for build system modules +which supposedly don't install any executables. " -- cgit v1.1