Add more step ids to worker script

Also rename bpkg.test-installed.{configure.build,update,test} to
bpkg.test-separate-installed.*.

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},