Add --fake-machine and machine-less agent/worker test

1 files changed, 24 insertions, 16 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index 2b2fc21..b96ddd9 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -494,18 +494,19 @@ 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
-name (or empty value if not specified) and the path to the \c{bbot} worker to
-be executed once the environment is setup. The environment setup executable is
-executed in the build directory as its current working directory. The build
+name (or empty value if not specified), the path to the \c{bbot} worker to be
+executed once the environment is setup, and any additional options that need
+to be propagated to the re-executed worker. The environment setup executable
+is executed in the build directory as its current working directory. The build
 directory contains the build task \c{manifest} file.
 
 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 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 \c{bbot} worker in the build directory as the
-current working directory.
+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
+\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
@@ -520,23 +521,30 @@ bpkg -v update <package-name>
 bpkg -v test <package-name>
 \
 
-As an example, the following bash script can be used to setup the environment
-for building C and C++ packages with GCC 6 on most Linux distributions.
+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.
 
 \
-#! /usr/bin/env bash
+#!/bin/sh
 
-# $1 - target
-# $2 - bbot executable
+# Environment setup script for C/C++ compilation with GCC 6.
+#
+# $1  - target
+# $2  - bbot executable
+# $3+ - bbot options
 
-trap \"exit 1\" ERR
+set -e # Exit on errors.
 
-if [ -n \"$1\" ]; then
-  echo \"unknown target $1\" 1>&2
+t=\"$1\"
+shift
+
+if test -n \"$t\"; then
+  echo \"unknown target: $t\" 1>&2
   exit 1
 fi
 
-exec \"$2\" cc config.c=gcc-6
+exec \"$@\" cc config.c=gcc-6 config.cxx=g++-6
 \
 
 \h#arch-controller|Controller Logic|