From 2af2c4f092aa7efffe839ec615c06d22cf43cc3b Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Tue, 16 Mar 2021 20:21:59 +0300
Subject: Add support for interactive builds

---
 doc/manual.cli | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

(limited to 'doc')

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.
-- 
cgit v1.1