Use environment task manifest value to locate environment setup executable

1 files changed, 26 insertions, 13 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index 4182be5..b4fc15b 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -325,6 +325,7 @@ repository-url: <repository-url>
 
 machine: <machine-name>
 target: <target-triplet>
+[environment]: <environment-name>
 [config]: <config-args>
 [warning-regex]: <warning-regex>
 \
@@ -409,6 +410,16 @@ triplet} format as autotools for \c{target}, it is not flexible enough for
 \c{machine}.
 
 
+\h2#arch-task-environment|\c{environment}|
+
+\
+[environment]: <environment-name>
+\
+
+The name of the build environment to use. See \l{#arch-worker Worker Logic}
+for details.
+
+
 \h2#arch-task-config|\c{config}|
 
 \
@@ -728,11 +739,11 @@ components: the execution environment (environment variables, etc), build
 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
-target and looks for the environment setup executable with this name in a
-specific directory. If not found, then the worker looks for the executable
-called \c{default}. Not being able to locate the environment executable is an
-error.
+file, etc). Specifically, upon receiving a build task, if it specifies the
+environment name then the worker looks for the environment setup executable
+with this name in a specific directory and for the executable called
+\c{default} otherwise. Not being able to locate the environment executable is
+an error.
 
 Once the environment setup executable is determined, the worker re-executes
 itself as that executable passing to it as command line arguments the target
@@ -911,7 +922,7 @@ 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> <classes> [<config-arg>]* [<warning-regex>]*
+<machine-pattern> <config> <target>[/<environment>] <classes> [<config-arg>]* [<warning-regex>]*
 
 <config-arg> = [<prefix>:](<variable>|<option>)
 <prefix> = <tool>[.<operation>[.<command>]]
@@ -919,11 +930,12 @@ are ignored. All other lines in this file have the following format:
 
 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, \c{<classes>} is a space-separated list of
-configuration classes that is matched against the package \c{builds} values,
-optional \c{<config-arg>} list is additional configuration options and
-variables, and optional \c{<warning-regex>} list is additional regular
-expressions that should be used to detect warnings in the logs.
+\c{<target>} is the build target, optional \c{<environment>} is the build
+environment name, \c{<classes>} is a space-separated list of configuration
+classes that is matched against the package \c{builds} values, optional
+\c{<config-arg>} list is additional configuration options and variables, and
+optional \c{<warning-regex>} list is additional regular expressions that
+should be used to detect warnings in the logs.
 
 The build configurations can belong to multiple classes with their names
 reflecting some common configuration aspects, such as the operating system,
@@ -938,8 +950,9 @@ Regular expressions must start with \c{~}, to be distinguished from
 configuration options and variables. Note that the \c{<config-arg>} and
 \c{<warning-regex>} lists have the same quoting semantics as in the \c{config}
 and the \c{warning-regex} value in the build task manifest. The matched
-machine name, the target, configuration options/variables, and regular
-expressions are included into the build task manifest.
+machine name, the target, the environment name, configuration
+options/variables, and regular expressions are included into the build task
+manifest.
 
 Values in the \c{<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,