From f3c17ab56c9d06c2b99729c2e4b60e8fd19cbb37 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 18 Oct 2017 13:40:32 +0200
Subject: Document config option/variable prefix

---
 doc/manual.cli | 124 ++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 96 insertions(+), 28 deletions(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index aa0f92d..f18541f 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -287,7 +287,7 @@ repository: <repository-url>
 
 machine: <machine-name>
 target: <target-triplet>
-[config]: <config-vars>
+[config]: <config-args>
 [warning-regex]: <warning-regex>
 \
 
@@ -364,10 +364,10 @@ triplet} format as autotools for \c{target}, it is not flexible enough for
 \h2#arch-task-config|\c{config}|
 
 \
-[config]: <config-vars>
+[config]: <config-args>
 \
 
-The additional build system configuration variables. A single level of quotes
+The additional configuration options and variables. A single level of quotes
 (either single or double) is removed in each variable before being passed to
 \c{bpkg}. For example, the following value:
 
@@ -381,7 +381,9 @@ Will be passed to \c{bpkg} as the following (single) argument:
 config.cc.coptions=-O3 -stdlib='libc++'
 \
 
-Variables can be separated with spaces or newlines.
+Values can be separated with spaces or newlines. See \l{#arch-controller
+Controller Logic} for details.
+
 
 \h2#arch-task-warning-regex|\c{warning-regex}|
 
@@ -675,7 +677,7 @@ task response.
 The \c{bbot} worker builds each package in a \i{build environment} that is
 established for a particular build target. The environment has three
 components: the execution environment (environment variables, etc), build
-system modules, and configuration variables.
+system modules, as well as configuration options and variables.
 
 Setting up of the environment is performed by an executable (script, batch
 file, etc). Specifically, upon receiving a build task, the worker obtains its
@@ -696,23 +698,74 @@ The environment setup executable sets up the necessary execution environment
 for example by adjusting \c{PATH} or running a suitable \c{vcvars} batch file.
 It then re-executes itself as the \c{bbot} worker passing to it as command
 line arguments (in addition to worker options) the list of build system
-modules (\c{<env-modules>}) and the list of configuration variables
-(\c{<env-config-vars>}). The environment setup executable must execute the
+modules (\c{<env-modules>}) and the list of configuration options and variables
+(\c{<env-config-args>}). The environment setup executable must execute the
 \c{bbot} worker in the build directory as the current working directory.
 
 The re-executed \c{bbot} worker then proceeds to test the package from the
-repository by executing the following commands (\c{<>}-values are from the
-task manifest and environment):
+repository by executing the following commends, 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>} and \c{<env-config-args>} values as discussed
+in \l{#arch-controller Controller Logic}. The \c{<>}-values are from the task
+manifest and the environment:
 
 \
-bpkg -v create <env-module> <config-vars> <env-config-vars>
+# bpkg.configure.create
+#
+bpkg -v create <config-args> <env-modules> <env-config-args>
+
+# bpkg.configure.add
+#
 bpkg -v add <repository-url>
+
+# bpkg.configure.fetch
+#
 bpkg -v fetch --trust <repository-fp>
+
+# bpkg.configure.build
+#
 bpkg -v build --yes --configure-only <package-name>/<package-version>
+
+# bpkg.update.update
+#
 bpkg -v update <package-name>
+
+# bpkg.test.test
+#
 bpkg -v test <package-name>
+
+# if config.install.root is specified:
+#
+{
+  # bpkg.install.install
+  #
+  bpkg -v install <package-name>
+
+  # if package contains tests/ subproject:
+  #
+  {
+    # b.test-installed.create
+    #
+    b create <config-args> <env-modules> <env-config-args>
+
+    # b.test-installed.configure
+    #
+    b configure
+
+    # b.test-installed.test
+    #
+    b test
+  }
+}
+
+# bpkg.uninstall.uninstall
+#
+bpkg uninstall <package-name>
 \
 
+For details on configuring and testing installation refer to
+\l{#arch-controller Controller Logic}.
+
 As an example, the following POSIX shell script can be used to setup the
 environment for building C and C++ packages with GCC 6 on most Linux
 distributions.
@@ -747,22 +800,36 @@ machines (as reported by agents) to \i{build configurations} according to the
 are ignored. All other lines in this file have the following format:
 
 \
-<machine-pattern> <config> <target> [<config-vars>] [<warning-regex>]
+<machine-pattern> <config> <target> [<config-args>] [<warning-regex>]
+
+<config-args> = [<prefix>:](<variable>|<option>)
+<prefix> = <tool>[.<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{<config-vars>} is a list of additional build system configuration
-variables, and optional \c{<warning-regex>} is a list of additional regular
-expressions that should be used to detect warnings in the logs.
+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{<config-args>} is a list of
+additional configuration options and variables, and optional
+\c{<warning-regex>} is a list of additional regular expressions that should be
+used to detect warnings in the logs.
 
 Regular expressions must start with \c{~}, to be distinguished from
-configuration variables. Note that \c{<config-vars>} and \c{<warning-regex>}
-lists have the same quoting semantics as in the \c{config} and the
-\c{warning-regex} values in the build task manifest. The matched machine name,
-the target, configuration variables, and regular expressions are included into
-the build task manifest.
+configuration options and variables. Note that \c{<config-args>} and
+\c{<warning-regex>} lists have the same quoting semantics as in the \c{config}
+and the \c{warning-regex} values in the build task manifest. The matched
+machine name, the target, configuration options/variables, and regular
+expressions are included into the build task manifest.
+
+Values in \c{<config-args>} can be opionally prefixed with the \i{step id} or
+a leading portion thereof to restrict it to a specific step, operation, or
+tool in the \i{worked script} (\l{#arch-worker Worker Logic}). Unprefixed
+values only apply to the \c{bpkg.configure.create} and
+\c{b.test-installed.create} steps. Note that options with values can only be
+specified using a single argument notation. For example:
+
+\
+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
@@ -794,11 +861,12 @@ linux*-gcc_6 linux-gcc_6-debug x86_64-linux-gnu config.cc.coptions=-g
 linux*-gcc_6 linux-gcc_6-release x86_64-linux-gnu config.cc.coptions=-O3
 \
 
-If \c{<config-vars>} contains the \c{config.install.root} variable then, in
-addition to building and running tests, the \c{bbot} worker will also test
-installing and uninstalling each package. Furthermore, if the package contains
-the \c{tests} subdirectory that is a subproject, then the worker will
-additionally build and run tests against the installation.
+If \c{<config-args>} contains the \c{config.install.root} variable that
+applies to the \c{bpkg.configure.create} step, then in addition to building
+and running tests, the \c{bbot} worker will also test installing and
+uninstalling each package. Furthermore, if the package contains the \c{tests}
+subdirectory that is a subproject, then the worker will additionally build and
+run tests against the installation.
 
 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},
@@ -817,7 +885,7 @@ linux*-gcc* linux-gcc-sys x86_64-linux-gnu config.install.root=/usr config.insta
 linux*-gcc* linux-gcc-prv x86_64-linux-gnu config.install.root=/tmp/install config.cc.poptions=-I/tmp/install/include config.cc.loptions=-L/tmp/install/lib config.bin.rpath=/tmp/install/lib
 \
 
-Note also that while building and run tests against the installation the
+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.
 "
-- 
cgit v1.1