aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2017-10-18 13:40:32 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2017-10-18 13:40:32 +0200
commitf3c17ab56c9d06c2b99729c2e4b60e8fd19cbb37 (patch)
treecf7b8d1275d24fe7822665c9f4554473de292ed2 /doc/manual.cli
parentecbfab741aed81feb3d71f8f36f97efa2260316b (diff)
Document config option/variable prefix
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli124
1 files changed, 96 insertions, 28 deletions
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.
"