diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 60 |
1 files changed, 58 insertions, 2 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 8285366..d08a6ff 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -63,6 +63,15 @@ machines and sends this information as part of the request. The controller responds with a build task manifest that identifies a specific build machine to use. +In the task request the agent specifies if only non-interactive, interactive, +or both build kinds are supported. If interactive builds are supported, it +additionally provides the login information for interactive build sessions. If +the controller responds with an interactive build task, then its manifest +specifies the breakpoint the worker must stop the task execution at and prompt +the user whether to continue or abort the execution. The user can log into the +build machine, potentially perform some troubleshooting, and, when done, +either answer the prompt or just shutdown the machine. + If the controller has higher-level controllers (for example, \c{brep}), then it aggregates the available build machines from its agents and polls these controllers (just as an agent would), forwarding build tasks to suitable @@ -328,6 +337,7 @@ target: <target-triplet> [environment]: <environment-name> [config]: <config-args> [warning-regex]: <warning-regex> +[interactive]: <breakpoint> \ @@ -495,6 +505,21 @@ Note that this built-in list also covers GCC and Clang warnings (for the English locale). +\h2#arch-task-interactive|\c{interactive}| + +\ +[interactive]: <breakpoint> +\ + +The task execution step to stop at. Can only be present if the agent has +specified \c{interactive-mode} with either the \c{true} or \c{both} value in +the task request. + +The breakpoint can either be a primary step id of the worker script or the +special \c{error} or \c{warning} value. See \l{#arch-worker Worker Logic} for +details. + + \h#arch-result|Result Manifest| The result manifest describes a build result. The manifest synopsis is @@ -615,6 +640,8 @@ description of each value in subsequent sections. agent: <name> toolchain-name: <name> toolchain-version: <standard-version> +[interactive-mode]: false|true|both +[interactive-login]: <login> [fingerprint]: <agent-fingerprint> \ @@ -647,6 +674,28 @@ toolchain-version: <standard-version> The \c{build2} toolchain version being used by the agent. +\h2#arch-task-req-interactive-mode|\c{interactive-mode}| + +\ +[interactive-mode]: false|true|both +\ + +The agent's capability to perform build tasks only non-interactively +(\c{false}), only interactively (\c{true}), or both (\c{both}). + +If it is not specified, then the \c{false} value is assumed. + + +\h2#arch-task-req-interactive-login|\c{interactive-login}| + +\ +[interactive-login]: <login> +\ + +The login information for the interactive build session. Must be present only +if \c{interactive-mode} is specified with the \c{true} or \c{both} value. + + \h2#arch-task-req-fingerprint|\c{fingerprint}| \ @@ -742,8 +791,8 @@ The session id as returned by the controller in the task response. \ The answer to the private key challenge as posed by the controller in the task -response. It must be present only if the challenge value was present in the -task response. +response. It must be present only if the \c{challenge} value was present in +the task response. \h#arch-worker|Worker Logic| @@ -947,6 +996,13 @@ then its \c{dist} meta-operation is also tested as a part of the \c{bpkg[.*].configure.build} steps by re-distributing the source directory in the load distribution mode after configuration. +If the build is interactive, then the worker pauses its execution at the +specified breakpoint and prompts the user whether to continue or abort the +execution. If the breakpoint is a step id, then the worker pauses prior to +executing every command of the specified step. Otherwise, the breakpoint +denotes the result status and the worker pauses if the command results with +the specified or more critical status (see \l{#arch-result Result Manifest}). + As an example, the following POSIX shell script can be used to setup the environment for building C and C++ packages with GCC 9 on most Linux distributions. |