From 8c54405d78b87b8756106eceec0a53ef0225d05e Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Fri, 24 Mar 2023 20:32:25 +0300
Subject: Add support for package build config worker steps and steps
 enabling/disabling

---
 doc/manual.cli | 133 +++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 87 insertions(+), 46 deletions(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 4e5a3c0..b50ad77 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -964,13 +964,15 @@ 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{<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). In particular, the
-\c{<pkg-config-opts>}, \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.
+\l{#arch-controller Controller Logic} as well as in the \c{<pkg-config-args>}
+values (see below). 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). In particular, the
+\c{<pkg-config-args>} (prefixed global options and variables),
+\c{<pkg-config-opts>} (unprefixed options), \c{<pkg-config-vars>} (unprefixed
+variables), \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
@@ -1008,7 +1010,8 @@ Worker script for \c{target} packages:
 \
 # bpkg.create (bpkg.target.create : b.create, bpkg.create)
 #
-bpkg -V create <env-modules> <env-config-args> <tgt-config-args>
+bpkg -V create <env-modules> \\
+     <env-config-args> <tgt-config-args> <pkg-config-args>
 
 # bpkg.configure.add
 #
@@ -1023,7 +1026,8 @@ bpkg -v fetch --trust <repository-fp>
 #   (bpkg.target.configure.build : b.configure, bpkg.configure.build))
 #
 bpkg -v build --configure-only \\
-     [<pkg-config-opts>] <env-config-args> <tgt-config-args> \\
+     <env-config-args> <tgt-config-args> <pkg-config-args> \\
+     [<pkg-config-opts>] \\
      [{ <pkg-config-vars> }+] <package-name>/<package-version> \\
      [<test-package-name>[ <test-version-constraint>]...] \\
      [([{ <dep-config-vars> }+] \\
@@ -1068,7 +1072,8 @@ bpkg -v update <package-name>
   {
     # b.test-installed.create ( : b.create)
     #
-    b -V create <env-modules> <env-config-args> <tgt-config-args>
+    b -V create <env-modules> \\
+      <env-config-args> <tgt-config-args> <pkg-config-args>
 
     # For each test subproject:
     #
@@ -1091,7 +1096,8 @@ 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> <tgt-config-args>
+    bpkg -V create <env-modules> \\
+         <env-config-args> <tgt-config-args> <pkg-config-args>
 
     # bpkg.test-separate-installed.configure.add (
     #  : bpkg.configure.add)
@@ -1108,7 +1114,8 @@ 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> <tgt-config-args> \\
+    bpkg -v build --configure-only \\
+         <env-config-args> <tgt-config-args> <pkg-config-args> \\
          <test-package-name>[ <test-version-constraint>]... \\
          ?sys:<package-name>/<package-version>
 
@@ -1144,8 +1151,8 @@ 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> <tgt-config-args>
+  bpkg -V create --type host -d <host-conf> <env-modules> \\
+       <env-config-args> <tgt-config-args> <pkg-config-args>
 }
 #
 # Otherwise:
@@ -1170,8 +1177,8 @@ 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> <tgt-config-args>
+  bpkg -V create -d <install-conf> <env-modules> \\
+       <env-config-args> <tgt-config-args> <pkg-config-args>
 
   # [bpkg.link]
   #
@@ -1192,8 +1199,8 @@ 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> <tgt-config-args>
+  bpkg -V create -d <target-conf> <env-modules> \\
+       <env-config-args> <tgt-config-args> <pkg-config-args>
 
   # [bpkg.create]
   #
@@ -1241,20 +1248,25 @@ bpkg -v fetch -d <host-conf> --trust <repository-fp>
 #   bpkg.configure.build.
 #
 bpkg -v build --configure-only \\
-[<pkg-config-opts>] <env-config-args> <tgt-config-args> \\
+<env-config-args> <tgt-config-args> <pkg-config-args> \\
+[<pkg-config-opts>] \\
 \\
 { --config-uuid <host-uuid> \\
-  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> \\
+  [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
 { --config-uuid <install-uuid> \\
-  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> \\
+  [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
-{ --config-uuid <host-uuid> <env-config-args> <tgt-config-args> }+ \\
+{ --config-uuid <host-uuid> \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> }+ \\
 { <runtime-test-package-name>[ test-version-constraint>]... } \\
 \\
-{ --config-uuid <target-uuid> <env-config-args> <tgt-config-args> }+ \\
+{ --config-uuid <target-uuid> \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> }+ \\
 { <buildtime-test-package-name>[ test-version-constraint>]... } \\
 \\
 ({ --config-uuid <host-uuid> [--config-uuid <install-uuid>] \\
@@ -1312,7 +1324,8 @@ bpkg -v update -d <host-conf> <package-name>
   {
     # b.test-installed.create ( : b.create)
     #
-    b -V create <env-modules> <env-config-args> <tgt-config-args>
+    b -V create <env-modules> \\
+      <env-config-args> <tgt-config-args> <pkg-config-args>
 
     # For each test subproject:
     #
@@ -1335,8 +1348,8 @@ bpkg -v update -d <host-conf> <package-name>
     #   bpkg.test-separate-installed.create_for_host :
     #     bpkg.test-separate-installed.create)
     #
-    bpkg -V create --type host -d <host-conf> \\
-         <env-modules> <env-config-args> <tgt-config-args>
+    bpkg -V create --type host -d <host-conf> <env-modules> \\
+         <env-config-args> <tgt-config-args> <pkg-config-args>
 
     # If task manifest refers to any runtime tests, examples, or
     # benchmarks packages:
@@ -1361,8 +1374,8 @@ bpkg -v update -d <host-conf> <package-name>
       #   bpkg.test-separate-installed.create_for_host :
       #     bpkg.test-separate-installed.create)
       #
-      bpkg -V create -d <target-conf> \\
-           <env-modules> <env-config-args> <tgt-config-args>
+      bpkg -V create -d <target-conf> <env-modules> \\
+           <env-config-args> <tgt-config-args> <pkg-config-args>
 
       # [bpkg.test-separate-installed.create]
       #
@@ -1394,7 +1407,8 @@ 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> <tgt-config-args> \\
+    bpkg -v build --configure-only \\
+    <env-config-args> <tgt-config-args> <pkg-config-args> \\
     \\
     { --config-name <host-conf> }+ \\
     { <runtime-test-package-name>[ <test-version-constraint>]... } \\
@@ -1437,7 +1451,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> <tgt-config-args>
+    <env-config-args> <tgt-config-args> <pkg-config-args>
   bpkg -v create --existing --type build2 -d <module-conf>
 }
 #
@@ -1464,7 +1478,8 @@ 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> <tgt-config-args>
+    config.config.load=~build2 \\
+    <env-config-args> <tgt-config-args> <pkg-config-args>
   bpkg -v create --existing --type build2 -d <install-conf>
 
   # bpkg.configure.add
@@ -1482,8 +1497,8 @@ 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> <tgt-config-args>
+  bpkg -V create -d <target-conf> <env-modules> \\
+       <env-config-args> <tgt-config-args> <pkg-config-args>
 
   # [bpkg.create]
   #
@@ -1522,17 +1537,21 @@ bpkg -v fetch -d <module-conf> --trust <repository-fp>
 #   bpkg.configure.build.
 #
 bpkg -v build --configure-only \\
-[<pkg-config-opts>] <env-config-args> <tgt-config-args> \\
+<env-config-args> <tgt-config-args> <pkg-config-args> \\
+[<pkg-config-opts>] \\
 \\
 { --config-uuid <module-uuid> \\
-  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> \\
+  [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
 { --config-uuid <install-uuid> \\
-  <env-config-args> <tgt-config-args> [<pkg-config-vars>] }+ \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> \\
+  [<pkg-config-vars>] }+ \\
 <package-name>/<package-version> \\
 \\
-{ --config-uuid <target-uuid> <env-config-args> <tgt-config-args> }+ \\
+{ --config-uuid <target-uuid> \\
+  <env-config-args> <tgt-config-args> <pkg-config-args> }+ \\
 { <buildtime-test-package-name>[ test-version-constraint>]... } \\
 \\
 ({ --config-uuid <host-uuid> [--config-uuid <install-uuid>] \\
@@ -1584,15 +1603,15 @@ bpkg -v update -d <module-conf> <package-name>
     #   bpkg.test-separate-installed.create_for_module :
     #     bpkg.test-separate-installed.create)
     #
-    bpkg -V create -d <target-conf> \\
-         <env-modules> <env-config-args> <tgt-config-args>
+    bpkg -V create -d <target-conf> <env-modules> \\
+         <env-config-args> <tgt-config-args> <pkg-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> <tgt-config-args>
+    bpkg -V create --type host -d <host-conf> <env-modules> \\
+         <env-config-args> <tgt-config-args> <pkg-config-args>
 
     # [bpkg.test-separate-installed.link]
     #
@@ -1615,7 +1634,8 @@ 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> <tgt-config-args> \\
+    bpkg -v build --configure-only \\
+    <env-config-args> <tgt-config-args> <pkg-config-args> \\
     \\
     { --config-name <target-conf> }+ \\
     <buildtime-test-package-name>[ <test-version-constraint>]... \\
@@ -1704,7 +1724,8 @@ to the \c{buildtab} configuration file. Blank lines and lines that start with
 \
 <machine-pattern> <target-config> <target>[/<environment>] <classes> [<tgt-config-arg>]* [<warning-regex>]*
 
-<tgt-config-arg> = [<prefix>:](<variable>|<option>)
+<tgt-config-arg> = [[+|-]<prefix>:](<variable>|<option>) | \\
+                   (+|-)<prefix>:
 <prefix> = <tool>[.<phase>][.<operation>[.<command>]]
 \
 
@@ -1741,12 +1762,32 @@ 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
+Logic}). The prefix can optionally begin with the \c{+} or \c{-} character (in
+this case the argument can be omitted) to enable or disable the respective
+step. The steps which can be enabled or disabled are:
+
+\
+bpkg.update
+bpkg.test
+bpkg.test-separate.update
+bpkg.test-separate.test
+bpkg.bindist                        # Disabled by default.
+bpkg.install                        # Disabled if bpkg.bindist is enabled.
+bbot.sys-install                    # Disabled if bpkg.bindist is disabled.
+b.test-installed.test
+bpkg.test-separate-installed.update
+bpkg.test-separate-installed.test
+\
+
+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:
 
 \
-bpkg:--fetch-timeout=600 bpkg.configure.fetch:--fetch-timeout=60 b:-j1
+bpkg:--fetch-timeout=600                \\
+bpkg.configure.fetch:--fetch-timeout=60 \\
++bpkg.bindist:                          \\
+b:-j1
 \
 
 Note that each machine name is matched against every pattern and all the
-- 
cgit v1.1