diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 80 |
1 files changed, 43 insertions, 37 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 4337627..8285366 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -779,9 +779,11 @@ modules (\c{<env-modules>}) 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 -prefix in the \c{<config-args>}, \c{<env-config-args>}, and \c{<env-modules>} -values as discussed in \l{#arch-controller Controller Logic}. The -\c{<>}-values are from the task manifest and the environment: +breakpoint as well as a prefix in the \c{<config-args>}, +\c{<env-config-args>}, and \c{<env-modules>} 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. \ # bpkg.create @@ -804,39 +806,41 @@ bpkg -v build --yes --configure-only <package-name>/<package-version> # bpkg -v update <package-name> -# if the test operation is supported by the package: +# If the test operation is supported by the package: # -# bpkg.test -# -bpkg -v test <package-name> +{ + # bpkg.test + # + bpkg -v test <package-name> +} -# for each package referred to by the tests, examples, or benchmarks +# For each package referred to by the tests, examples, or benchmarks # package manifest values and not excluded by the test-exclude task # manifest values: # { - # bpkg.configure.build + # bpkg.test-separate.configure.build (bpkg.configure.build) # bpkg -v build --yes --configure-only \\ '<package-name> [<version-constraint>]' - # bpkg.update + # bpkg.test-separate.update (bpkg.update) # bpkg -v update <package-name> - # bpkg.test + # bpkg.test-separate.test (bpkg.test) # bpkg -v test <package-name> } -# if config.install.root is specified: +# If config.install.root is specified: # { # bpkg.install # bpkg -v install <package-name> - # if the package contains subprojects that support the test + # If the package contains subprojects that support the test # operation: # { @@ -853,42 +857,39 @@ bpkg -v test <package-name> b -v test } - # if any of the tests, examples, or benchmarks package manifest + # If any of the tests, examples, or benchmarks package manifest # values are specified and are not all excluded by the test-exclude # task manifest values: # { - # bpkg.test-installed.create (fallback to bpkg.create if absent) + # bpkg.test-installed.create (bpkg.create) # bpkg -V create <env-modules> <env-config-args> <config-args> - # bpkg.test-installed.configure.add (fallback to - # bpkg.configure.add if absent) + # bpkg.test-installed.configure.add (bpkg.configure.add) # bpkg -v add <repository-url> - # bpkg.test-installed.configure.fetch (fallback to - # bpkg.configure.fetch if absent) + # bpkg.test-installed.configure.fetch (bpkg.configure.fetch) # bpkg -v fetch --trust <repository-fp> - # for each package referred to by the tests, examples, or + # For each package referred to by the tests, examples, or # benchmarks package manifest values and not excluded by the # test-exclude task manifest values: # { - # bpkg.test-installed.configure.build (fallback to - # bpkg.configure.build if absent) + # bpkg.test-separate-installed.configure.build ( + # bpkg.configure.build) # bpkg -v build --yes --configure-only \\ '<package-name> [<version-constraint>]' - # bpkg.test-installed.update (fallback to bpkg.update if - # absent) + # bpkg.test-separate-installed.update (bpkg.update) # bpkg -v update <package-name> - # bpkg.test-installed.test (fallback to bpkg.test if absent) + # bpkg.test-separate-installed.test (bpkg.test) # bpkg -v test <package-name> } @@ -907,39 +908,44 @@ 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 no associated \i{step id}: +Such commands, therefore, have associated step ids that can only be used +as breakpoints (listed in square brackets): \ -# +# [bpkg.module.create] # b -V create config.config.load=~build2 bpkg -v create --existing -# bpkg.configure.add +# bpkg.module.configure.add (bpkg.configure.add) # bpkg -v add <repository-url> -# bpkg.configure.fetch +# bpkg.module.configure.fetch (bpkg.configure.fetch) # bpkg -v fetch --trust <repository-fp> -# +# [bpkg.module.configure.build] # bpkg -v build --yes --configure-only <package-name>/<package-version> -# +# [bpkg.module.update] # bpkg -v update <package-name> -# if the test operation is supported by the package: +# If the test operation is supported by the package: # -bpkg -v test <package-name> +{ + # [bpkg.module.test] + # + bpkg -v test <package-name> +} \ 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} step by re-distributing the source directory in the -load distribution mode after configuration. +\c{bpkg[.*].configure.build} steps by re-distributing the source directory in +the load distribution mode after configuration. As an example, the following POSIX shell script can be used to setup the environment for building C and C++ packages with GCC 9 on most Linux @@ -985,7 +991,7 @@ are ignored. All other lines in this file have the following format: <machine-pattern> <config> <target>[/<environment>] <classes> [<config-arg>]* [<warning-regex>]* <config-arg> = [<prefix>:](<variable>|<option>) -<prefix> = <tool>[.phase][.<operation>[.<command>]] +<prefix> = <tool>[.<phase>][.<operation>[.<command>]] \ Where \c{<machine-pattern>} is filesystem wildcard pattern that is matched @@ -1093,7 +1099,7 @@ that support the test operation and/or refers to other packages via the \c{tests}, \c{examples}, or \c{benchmarks} manifest values which are not excluded by the \c{test-exclude} task manifest values, then the worker will additionally build such subprojects/packages against the installation and run -their tests (test installed phase). +their tests (test installed and test separate installed phases). Two types of installations can be tested: \i{system} and \i{private}. A system installation uses a well-known location, such as \c{/usr} or \c{/usr/local}, |