diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual.cli | 124 |
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. " |