From f37129f4c6cc9e60f547fdfe0a28a984ddd8de73 Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Wed, 16 Nov 2022 22:16:21 +0300
Subject: Add support for package-config task manifest value

---
 doc/manual.cli | 300 +++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 183 insertions(+), 117 deletions(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 3b3bd4b..59b20c7 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -90,12 +90,12 @@ build logs hosted by the controller.
 
 \h#arch-machine-config|Configurations|
 
-The \c{bbot} architecture distinguishes between a \i{machine configuration}
-and a \i{build configuration}. The machine configuration captures the
-operating system, installed compiler toolchain, and so on. The same build
-machine may be used to \"generate\" multiple \i{build configurations}. For
-example, the same machine can normally be used to produce 32/64-bit and
-debug/optimized builds.
+The \c{bbot} architecture distinguishes between a \i{machine configuration},
+\i{build target configuration}, and a \i{build package configuration}. The
+machine configuration captures the operating system, installed compiler
+toolchain, and so on. The same build machine may be used to \"generate\"
+multiple \i{build target configurations}. For example, the same machine can
+normally be used to produce 32/64-bit and debug/optimized builds.
 
 The machine configuration is \i{approximately} encoded in its \i{machine
 name}. The machine name is a list of components separated with \c{-}.
@@ -156,22 +156,31 @@ linux_ubuntu_16.04-gcc_6.3
 aarch64_linux_debian_11-gcc_12.2
 \
 
-Similarly, the build configuration is encoded in a \i{configuration name}
-using the same overall format. As described in \l{#arch-controller Controller
-Logic}, build configurations are generated from machine configurations. As a
-result, it usually makes sense to have the first component identify the
-operating systems and the second component \- the toolchain with the rest
-identifying a particular build configuration variant, for example, optimized,
-sanitized, etc. For example:
+Similarly, the build target configuration is encoded in a \i{configuration
+name} using the same overall format. As described in \l{#arch-controller
+Controller Logic}, target configurations are generated from machine
+configurations. As a result, it usually makes sense to have the first
+component identify the operating systems and the second component \- the
+toolchain with the rest identifying a particular target configuration variant,
+for example, optimized, sanitized, etc. For example:
 
 \
 windows-vc_14-O2
 linux-gcc_6-O3_asan
 \
 
-While we can also specify the \c{<arch>} component in a build configuration,
-this information is best conveyed as part of \c{<target>} as described in
-\l{#arch-controller Controller Logic}.
+While we can also specify the \c{<arch>} component in a build target
+configuration, this information is best conveyed as part of \c{<target>} as
+described in \l{#arch-controller Controller Logic}.
+
+A package can be built in multiple package configurations per target
+configuration. A build package configuration normally specifies the package
+configuration variables that need to be used for the build. It may also
+include the information regarding the dependency packages which need to
+additionally be configured. The build package configurations originate from
+the package manifest \c{*-build-config}, \c{*-builds}, \c{*-build-include},
+and \c{*-build-exclude} values. See \l{bpkg#manifest-package Package Manifest}
+for more information on these values.
 
 \h#arch-machine-header|Machine Header Manifest|
 
@@ -348,7 +357,8 @@ repository-url: <repository-url>
 machine: <machine-name>
 target: <target-triplet>
 [environment]: <environment-name>
-[config]: <config-args>
+[target-config]: <tgt-config-args>
+[package-config]: <pkg-config-args>
 [host]: true|false
 [warning-regex]: <warning-regex>
 [interactive]: <breakpoint>
@@ -469,24 +479,50 @@ The name of the build environment to use. See \l{#arch-worker Worker Logic}
 for details.
 
 
-\h2#arch-task-config|\c{config}|
+\h2#arch-task-target-config|\c{target-config}|
 
 \
-[config]: <config-args>
+[target-config]: <tgt-config-args>
 \
 
-The additional configuration options and variables. A single level of quotes
+The additional target configuration options and variables. A single level of
+quotes (either single or double) is removed in each value before being passed
+to \c{bpkg}. For example, the following value:
+
+\
+target-config: config.cc.coptions=\"-O3 -stdlib='libc++'\"
+\
+
+Will be passed to \c{bpkg} as the following (single) argument:
+
+\
+config.cc.coptions=-O3 -stdlib='libc++'
+\
+
+Values can be separated with spaces or newlines. See \l{#arch-controller
+Controller Logic} for details.
+
+
+\h2#arch-task-package-config|\c{package-config}|
+
+\
+[package-config]: <pkg-config-args>
+\
+
+The primary package manifest \c{*-build-config} value for the build
+configuration the build task is issued for. See \l{bpkg#manifest-package
+Package Manifest} for more information on this value. A single level of quotes
 (either single or double) is removed in each value before being passed to
 \c{bpkg}. For example, the following value:
 
 \
-config: config.cc.coptions=\"-O3 -stdlib='libc++'\"
+package-config: \"?libcurl ~7.76.0\"
 \
 
 Will be passed to \c{bpkg} as the following (single) argument:
 
 \
-config.cc.coptions=-O3 -stdlib='libc++'
+?libcurl ~7.76.0
 \
 
 Values can be separated with spaces or newlines. See \l{#arch-controller
@@ -499,8 +535,9 @@ Controller Logic} for details.
 [host]: true|false
 \
 
-If \c{true}, then the build configuration is self-hosted. If not specified,
-\c{false} is assumed. See \l{#arch-controller Controller Logic} for details.
+If \c{true}, then the build target configuration is self-hosted. If not
+specified, \c{false} is assumed. See \l{#arch-controller Controller Logic} for
+details.
 
 
 \h2#arch-task-warning-regex|\c{warning-regex}|
@@ -924,20 +961,24 @@ 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
-breakpoint and normally as a prefix in the \c{<config-args>},
+breakpoint and normally as a prefix in the \c{<tgt-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 though some are assigned by the worker during the
-script execution (configuration directories, UUIDs, etc).
+script execution (configuration directories, UUIDs, etc). In particular, the
+\c{<pkg-config-vars>}, \c{<dependency-name>},
+\c{<dependency-version-constraint>}, and \c{<dep-config-vars>} values result
+from parsing the \l{#arch-task-package-config \c{package-config}} task
+manifest value.
 
 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.
+Some commands have no target 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
@@ -952,19 +993,21 @@ 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.
 
-Note finally that the worker adds the \c{config.<name>.develop=false}
-configuration variables for the main and external test packages at the
-\c{bpkg.configure.build} step to trigger their package skeleton creation and
-loading. This makes sure that these packages can be used as dependencies of
-dependents with configuration clauses. To keep the below listings concise,
-these variables are not shown.
+Note finally that if no configuration variables are specified in the main
+package configuration, then the worker adds the
+\c{config.<name>.develop=false} configuration variable for the main package at
+the \c{bpkg.configure.build} step to trigger its package skeleton creation and
+loading. It also adds this variable for external test packages at this step
+and for the same purpose. This makes sure that these packages can be used as
+dependencies of dependents with configuration clauses. To keep the below
+listings concise, these variables are not shown.
 
 Worker script for \c{target} packages:
 
 \
 # bpkg.create (bpkg.target.create : b.create, bpkg.create)
 #
-bpkg -V create <env-modules> <env-config-args> <config-args>
+bpkg -V create <env-modules> <env-config-args> <tgt-config-args>
 
 # bpkg.configure.add
 #
@@ -978,9 +1021,11 @@ bpkg -v fetch --trust <repository-fp>
 #   bpkg.global.configure.build,
 #   (bpkg.target.configure.build : b.configure, bpkg.configure.build))
 #
-bpkg -v build --configure-only <env-config-args> <config-args> \\
-     <package-name>/<package-version> \\
-     [<test-package-name>[ <test-version-constraint>]...]
+bpkg -v build --configure-only <env-config-args> <tgt-config-args> \\
+     [{ <pkg-config-vars> }+] <package-name>/<package-version> \\
+     [<test-package-name>[ <test-version-constraint>]...] \\
+     [([{ <dep-config-vars> }+] \\
+       ?[sys:]<dependency-name>[ <dependency-version-constraint>])...]
 
 # bpkg.update
 #
@@ -1020,14 +1065,14 @@ bpkg -v update <package-name>
   {
     # b.test-installed.create ( : b.create)
     #
-    b -V create <env-modules> <env-config-args> <config-args>
+    b -V create <env-modules> <env-config-args> <tgt-config-args>
 
     # For each test subproject:
     #
     {
       # b.test-installed.configure ( : b.configure)
       #
-      b -v configure
+      b -v configure [<pkg-config-vars>]
     }
 
     # b.test-installed.test
@@ -1043,7 +1088,7 @@ bpkg -v update <package-name>
     #   bpkg.test-separate-installed.create_for_target :
     #     bpkg.test-separate-installed.create)
     #
-    bpkg -V create <env-modules> <env-config-args> <config-args>
+    bpkg -V create <env-modules> <env-config-args> <tgt-config-args>
 
     # bpkg.test-separate-installed.configure.add (
     #  : bpkg.configure.add)
@@ -1060,7 +1105,7 @@ bpkg -v update <package-name>
     #   (bpkg.test-separate-installed.configure.build_for_target :
     #      bpkg.test-separate-installed.configure.build))
     #
-    bpkg -v build --configure-only <env-config-args> <config-args> \\
+    bpkg -v build --configure-only <env-config-args> <tgt-config-args> \\
          <test-package-name>[ <test-version-constraint>]... \\
          ?sys:<package-name>
 
@@ -1097,7 +1142,7 @@ Worker script for \c{host} packages:
   # bpkg.create (bpkg.host.create : b.create, bpkg.create)
   #
   bpkg -V create --type host -d <host-conf> \\
-       <env-modules> <env-config-args> <config-args>
+       <env-modules> <env-config-args> <tgt-config-args>
 }
 #
 # Otherwise:
@@ -1123,7 +1168,7 @@ bpkg -v fetch -d <host-conf> --trust <repository-fp>
   # bpkg.create (bpkg.target.create : b.create, bpkg.create)
   #
   bpkg -V create -d <install-conf> \\
-       <env-modules> <env-config-args> <config-args>
+       <env-modules> <env-config-args> <tgt-config-args>
 
   # [bpkg.link]
   #
@@ -1145,7 +1190,7 @@ bpkg -v fetch -d <host-conf> --trust <repository-fp>
   # bpkg.create (bpkg.target.create : b.create, bpkg.create)
   #
   bpkg -V create -d <target-conf> \\
-       <env-modules> <env-config-args> <config-args>
+       <env-modules> <env-config-args> <tgt-config-args>
 
   # [bpkg.create]
   #
@@ -1192,19 +1237,25 @@ bpkg -v fetch -d <host-conf> --trust <repository-fp>
 # - All parts have the same fallback step ids: b.configure and
 #   bpkg.configure.build.
 #
-bpkg -v build --configure-only <env-config-args> <config-args> \\
+bpkg -v build --configure-only <env-config-args> <tgt-config-args> \\
 \\
-{ --config-uuid <host-uuid> <env-config-args> <config-args> }+ \\
+{ --config-uuid <host-uuid> \\
+  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
-{ --config-uuid <install-uuid> <env-config-args> <config-args> }+ \\
+{ --config-uuid <install-uuid> \\
+  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
-{ --config-uuid <host-uuid> <env-config-args> <config-args> }+ \\
+{ --config-uuid <host-uuid> <env-config-args> <tgt-config-args> }+ \\
 { <runtime-test-package-name>[ test-version-constraint>]... } \\
 \\
-{ --config-uuid <target-uuid> <env-config-args> <config-args> }+ \\
-{ <buildtime-test-package-name>[ test-version-constraint>]... }
+{ --config-uuid <target-uuid> <env-config-args> <tgt-config-args> }+ \\
+{ <buildtime-test-package-name>[ test-version-constraint>]... } \\
+\\
+({ --config-uuid <host-uuid> [--config-uuid <install-uuid>] \\
+   [<dep-config-vars>] }+ \\
+ ?[sys:]<dependency-name>[ <dependency-version-constraint>])...
 
 # bpkg.update
 #
@@ -1257,14 +1308,14 @@ bpkg -v update -d <host-conf> <package-name>
   {
     # b.test-installed.create ( : b.create)
     #
-    b -V create <env-modules> <env-config-args> <config-args>
+    b -V create <env-modules> <env-config-args> <tgt-config-args>
 
     # For each test subproject:
     #
     {
       # b.test-installed.configure ( : b.configure)
       #
-      b -v configure
+      b -v configure [<pkg-config-vars>]
     }
 
     # b.test-installed.test
@@ -1281,7 +1332,7 @@ bpkg -v update -d <host-conf> <package-name>
     #     bpkg.test-separate-installed.create)
     #
     bpkg -V create --type host -d <host-conf> \\
-         <env-modules> <env-config-args> <config-args>
+         <env-modules> <env-config-args> <tgt-config-args>
 
     # If task manifest refers to any runtime tests, examples, or
     # benchmarks packages:
@@ -1307,7 +1358,7 @@ bpkg -v update -d <host-conf> <package-name>
       #     bpkg.test-separate-installed.create)
       #
       bpkg -V create -d <target-conf> \\
-           <env-modules> <env-config-args> <config-args>
+           <env-modules> <env-config-args> <tgt-config-args>
 
       # [bpkg.test-separate-installed.create]
       #
@@ -1339,7 +1390,7 @@ bpkg -v update -d <host-conf> <package-name>
     # Note that any of the runtime or build-time tests related parts
     # (but not both) may be omitted.
     #
-    bpkg -v build --configure-only <env-config-args> <config-args> \\
+    bpkg -v build --configure-only <env-config-args> <tgt-config-args> \\
     \\
     { --config-name <host-conf> }+ \\
     { <runtime-test-package-name>[ <test-version-constraint>]... } \\
@@ -1382,7 +1433,7 @@ Worker script for \c{module} packages:
   # bpkg.create (bpkg.module.create)
   #
   b -V create(<module-conf>, <env-modules>) config.config.load=~build2 \\
-     <env-config-args> <config-args>
+     <env-config-args> <tgt-config-args>
   bpkg -v create --existing --type build2 -d <module-conf>
 }
 #
@@ -1409,7 +1460,7 @@ bpkg -v fetch -d <module-conf> --trust <repository-fp>
   # bpkg.create (bpkg.module.create)
   #
   b -V create(<install-conf>, <env-modules>) \\
-     config.config.load=~build2 <env-config-args> <config-args>
+     config.config.load=~build2 <env-config-args> <tgt-config-args>
   bpkg -v create --existing --type build2 -d <install-conf>
 
   # bpkg.configure.add
@@ -1428,7 +1479,7 @@ bpkg -v fetch -d <module-conf> --trust <repository-fp>
   # bpkg.create (bpkg.target.create : b.create, bpkg.create)
   #
   bpkg -V create -d <target-conf> \\
-       <env-modules> <env-config-args> <config-args>
+       <env-modules> <env-config-args> <tgt-config-args>
 
   # [bpkg.create]
   #
@@ -1466,16 +1517,22 @@ bpkg -v fetch -d <module-conf> --trust <repository-fp>
 # - All parts have the same fallback step ids: b.configure and
 #   bpkg.configure.build.
 #
-bpkg -v build --configure-only <env-config-args> <config-args> \\
+bpkg -v build --configure-only <env-config-args> <tgt-config-args> \\
 \\
-{ --config-uuid <module-uuid> <env-config-args> <config-args> }+ \\
+{ --config-uuid <module-uuid> \\
+  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
-{ --config-uuid <install-uuid> <env-config-args> <config-args> }+ \\
+{ --config-uuid <install-uuid> \\
+  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
-{ --config-uuid <target-uuid> <env-config-args> <config-args> }+ \\
-{ <buildtime-test-package-name>[ test-version-constraint>]... }
+{ --config-uuid <target-uuid> <env-config-args> <tgt-config-args> }+ \\
+{ <buildtime-test-package-name>[ test-version-constraint>]... } \\
+\\
+({ --config-uuid <host-uuid> [--config-uuid <install-uuid>] \\
+   [<dep-config-vars>] }+ \\
+ ?[sys:]<dependency-name>[ <dependency-version-constraint>])...
 
 # bpkg.update
 #
@@ -1523,14 +1580,14 @@ bpkg -v update -d <module-conf> <package-name>
     #     bpkg.test-separate-installed.create)
     #
     bpkg -V create -d <target-conf> \\
-         <env-modules> <env-config-args> <config-args>
+         <env-modules> <env-config-args> <tgt-config-args>
 
     # bpkg.test-separate-installed.create (
     #   bpkg.test-separate-installed.create_for_module :
     #     bpkg.test-separate-installed.create)
     #
     bpkg -V create --type host -d <host-conf> \\
-         <env-modules> <env-config-args> <config-args>
+         <env-modules> <env-config-args> <tgt-config-args>
 
     # [bpkg.test-separate-installed.link]
     #
@@ -1553,7 +1610,7 @@ bpkg -v update -d <module-conf> <package-name>
     #   (bpkg.test-separate-installed.configure.build_for_module :
     #      bpkg.test-separate-installed.configure.build))
     #
-    bpkg -v build --configure-only <env-config-args> <config-args> \\
+    bpkg -v build --configure-only <env-config-args> <tgt-config-args> \\
     \\
     { --config-name <target-conf> }+ \\
     <buildtime-test-package-name>[ <test-version-constraint>]... \\
@@ -1635,49 +1692,50 @@ exec \"$@\" cc config.c=\"gcc-9 $mode\" config.cxx=\"g++-9 $mode\"
 \h#arch-controller|Controller Logic|
 
 A \c{bbot} controller that issues own build tasks maps available build
-machines (as reported by agents) to \i{build configurations} according to the
-\c{buildtab} configuration file. Blank lines and lines that start with \c{#}
-are ignored. All other lines in this file have the following format:
+machines (as reported by agents) to \i{build target configurations} according
+to the \c{buildtab} configuration file. Blank lines and lines that start with
+\c{#} are ignored. All other lines in this file have the following format:
 
 \
-<machine-pattern> <config> <target>[/<environment>] <classes> [<config-arg>]* [<warning-regex>]*
+<machine-pattern> <target-config> <target>[/<environment>] <classes> [<tgt-config-arg>]* [<warning-regex>]*
 
-<config-arg> = [<prefix>:](<variable>|<option>)
+<tgt-config-arg> = [<prefix>:](<variable>|<option>)
 <prefix> = <tool>[.<phase>][.<operation>[.<command>]]
 \
 
 Where \c{<machine-pattern>} is filesystem wildcard pattern that is matched
-against available machine names, \c{<config>} is the configuration name,
-\c{<target>} is the build target, optional \c{<environment>} is the build
-environment name, \c{<classes>} is a space-separated list of configuration
-classes that is matched against the package \c{builds} values, optional
-\c{<config-arg>} list is additional configuration options and variables, and
-optional \c{<warning-regex>} list is additional regular expressions that
-should be used to detect warnings in the logs.
-
-The build configurations can belong to multiple classes with their names
-reflecting some common configuration aspects, such as the operating system,
-compiler, build options, etc. Predefined class names are \c{default}, \c{all},
-\c{none}, \c{host}, and \c{build2}. The default configurations are built by
-default. A configuration must also belong to the \c{all} unless it is hidden.
-A configuration that is self-hosted must also belong to the \c{host} class
-and, if it is also self-hosted for build system modules, to the \c{build2}
-class. Valid custom class names must contain only alpha-numeric characters,
-\c{_}, \c{+}, \c{-}, and \c{.}, except as the first character for the last
-three. Class names that start with \c{_} are reserved for the future
+against available machine names, \c{<target-config>} is the target
+configuration name, \c{<target>} is the build target, optional
+\c{<environment>} is the build environment name, \c{<classes>} is a
+space-separated list of configuration classes that is matched against the
+package configuration \c{*-builds} values, optional \c{<tgt-config-arg>} list
+is additional configuration options and variables, and optional
+\c{<warning-regex>} list is additional regular expressions that should be used
+to detect warnings in the logs.
+
+The build target configurations can belong to multiple classes with their
+names reflecting some common configuration aspects, such as the operating
+system, compiler, build options, etc. Predefined class names are \c{default},
+\c{all}, \c{none}, \c{host}, and \c{build2}. The default target configurations
+are built by default. A configuration must also belong to the \c{all} unless
+it is hidden. A configuration that is self-hosted must also belong to the
+\c{host} class and, if it is also self-hosted for build system modules, to the
+\c{build2} class. Valid custom class names must contain only alpha-numeric
+characters, \c{_}, \c{+}, \c{-}, and \c{.}, except as the first character for
+the last three. Class names that start with \c{_} are reserved for the future
 hidden/special class functionality.
 
-Regular expressions must start with \c{~}, to be distinguished from
-configuration options and variables. Note that the \c{<config-arg>} and
-\c{<warning-regex>} lists have the same quoting semantics as in the \c{config}
-and the \c{warning-regex} value in the build task manifest. The matched
-machine name, the target, the environment name, configuration
-options/variables, and regular expressions are included into the build task
-manifest.
-
-Values in the \c{<config-arg>} 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
+Regular expressions must start with \c{~}, to be distinguished from target
+configuration options and variables. Note that the \c{<tgt-config-arg>} and
+\c{<warning-regex>} lists have the same quoting semantics as in the
+\c{target-config} and the \c{warning-regex} value in the build task
+manifest. The matched machine name, the target, the environment name,
+configuration options/variables, and regular expressions are included into the
+build task manifest.
+
+Values in the \c{<tgt-config-arg>} 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{*.create[_for_*]} steps. Note
 that options with values can only be specified using the single argument
 notation. For example:
@@ -1687,15 +1745,16 @@ bpkg:--fetch-timeout=600 bpkg.configure.fetch:--fetch-timeout=60 b:-j1
 \
 
 Note that each machine name is matched against every pattern and all the
-patterns that match produce a configuration. If a machine does not match any
-pattern, then it is ignored (meaning that this controller is not interested in
-testing its packages with this machine). If multiple machines match the same
-pattern, then only a single configuration using any of the machines is
-produced (meaning that this controller considers these machines equivalent).
+patterns that match produce a target configuration. If a machine does not
+match any pattern, then it is ignored (meaning that this controller is not
+interested in testing its packages with this machine). If multiple machines
+match the same pattern, then only a single target configuration using any of
+the machines is produced (meaning that this controller considers these
+machines equivalent).
 
 As an example, let's say we have a machine named \c{windows_10-vc_14.3}. If we
 wanted to test both 32 and 64-bit as well as debug and optimized builds, then
-we could have generated the following configurations:
+we could have generated the following target configurations:
 
 \
 windows*-msvc_14* windows-msvc_14-Z7 i686-microsoft-win32-msvc14.0 \"all default msvc i686 debug\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
@@ -1722,7 +1781,7 @@ aarch64_linux_debian_11*-gcc_12.2 linux_debian_11-gcc_12.2 aarch64-linux-gnu ...
 
 As another example, let's say we have \c{linux_fedora_25-gcc_6} and
 \c{linux_ubuntu_16.04-gcc_6}. If all we cared about is testing GCC 6 64-bit
-builds on Linux, then our configurations could look like this:
+builds on Linux, then our target configurations could look like this:
 
 \
 linux*-gcc_6 linux-gcc_6-g x86_64-linux-gnu \"all default gcc debug\" config.cc.coptions=-g
@@ -1730,11 +1789,12 @@ linux*-gcc_6 linux-gcc_6-g x86_64-linux-gnu \"all default gcc debug\" config.cc.
 linux*-gcc_6 linux-gcc_6-O3 x86_64-linux-gnu \"all default gcc optimized\" config.cc.coptions=-O3
 \
 
-A build configuration class can derive from another class in which case
-configurations that belong to the derived class are treated as also belonging
-to the base class (or classes, recursively). The derived and base class names
-are separated with \c{:} (no leading or trailing spaces allowed) and the base
-must be present in the first mentioning of the derived class. For example:
+A build target configuration class can derive from another class in which case
+target configurations that belong to the derived class are treated as also
+belonging to the base class (or classes, recursively). The derived and base
+class names are separated with \c{:} (no leading or trailing spaces allowed)
+and the base must be present in the first mentioning of the derived class. For
+example:
 
 \
 linux*-gcc_6 linux-gcc_6-g x86_64-linux-gnu \"all gcc-6+ debug\" config.cc.coptions=-g
@@ -1758,7 +1818,7 @@ linux*-gcc_6 linux-gcc_6 x86_64-linux-gnu \"all gcc-6+       \"
 linux*-gcc_8 linux-gcc_8 x86_64-linux-gnu \"all gcc-8+:gcc-7+\"
 \
 
-If the \c{<config-arg>} list contains the \c{config.install.root} variable
+If the \c{<tgt-config-arg>} list contains the \c{config.install.root} variable
 that applies to the \c{bpkg.create} step, then in addition to building and
 possibly running tests, the \c{bbot} worker will also test installing and
 uninstalling each package. Furthermore, if the package contains subprojects
@@ -1777,8 +1837,8 @@ preferable, it may not be always usable because of the potential conflicts
 with the already installed software, for example, by the system package
 manager.
 
-As an example, the following two configurations could be used to test system
-and private installations:
+As an example, the following two target configurations could be used to test
+system and private installations:
 
 \
 linux*-gcc* linux-gcc-sysinstall x86_64-linux-gnu \"all default gcc\" config.install.root=/usr config.install.sudo=sudo
@@ -1790,4 +1850,10 @@ 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, except for build system modules
 which supposedly don't install any executables.
+
+The \c{bbot} controller normally issues the build task by picking an unbuilt
+package configuration and one of the produced (via the machine names match)
+target configurations, which is not excluded from building due to this package
+configuration \c{*-builds}, \c{*-build-include}, and \c{*-build-exclude}
+manifest values.
 "
-- 
cgit v1.1