aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2021-03-16 20:21:59 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2021-03-26 20:00:31 +0300
commit2af2c4f092aa7efffe839ec615c06d22cf43cc3b (patch)
treee84676dbf273602fdf1f3541171df9dad7060daf /doc/manual.cli
parent392c6003321047421467e07eac31e12875377ead (diff)
Add support for interactive builds
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli60
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.