aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2021-03-12 12:38:33 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2021-03-12 13:24:43 +0300
commit392c6003321047421467e07eac31e12875377ead (patch)
tree0f5046cfa64a8d7dca4c12b500d868fd5ecc8ff9 /doc/manual.cli
parent5ca542f427169b4fa049ff832184d23670887c64 (diff)
Add more step ids to worker script
Also rename bpkg.test-installed.{configure.build,update,test} to bpkg.test-separate-installed.*.
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli80
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},