aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli79
1 files changed, 78 insertions, 1 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 93ba6f0..38b52e0 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -198,10 +198,13 @@ summary: Windows 10 build 1607 with VC 14 update 3
id: <machine-id>
\
-The uniquely machine version/revision/build identifies. For virtual machines
+The unique machine version/revision/build identifier. For virtual machines
this can be the disk image checksum. For a container this can be UUID that is
re-generated every time a container filesystem is altered.
+Note that we assume that a different machine identifier is assigned on any
+change that may affect the build result.
+
\h2#arch-machine-header-name|\c{name}|
@@ -334,6 +337,7 @@ repository-url: <repository-url>
[tests]: <dependency-package>
[examples]: <dependency-package>
[benchmarks]: <dependency-package>
+[dependency-checksum]: <checksum>
machine: <machine-name>
target: <target-triplet>
@@ -342,6 +346,7 @@ target: <target-triplet>
[host]: true|false
[warning-regex]: <warning-regex>
[interactive]: <breakpoint>
+[worker-checksum]: <checksum>
\
@@ -382,6 +387,7 @@ The repository type (see \c{repository-url} for details). Alternatively, the
repository type can be specified as part of the URL scheme. See
\l{bpkg-repository-types(1)} for details.
+
\h2#arch-task-trust|\c{trust}|
\
@@ -413,6 +419,16 @@ excluded from building due to their \c{builds}, \c{build-include}, and
\c{build-exclude} manifest values.
+\h2#arch-task-dependency-checksum|\c{dependency-checksum}|
+
+\
+[dependency-checksum]: <checksum>
+\
+
+The package dependency checksum received as a part of the previous build task
+result (see \l{#arch-result Result Manifest}).
+
+
\h2#arch-task-machine|\c{machine}|
\
@@ -532,6 +548,16 @@ special \c{error} or \c{warning} value. See \l{#arch-worker Worker Logic} for
details.
+\h2#arch-task-worker-checksum|\c{worker-checksum}|
+
+\
+[worker-checksum]: <checksum>
+\
+
+The worker checksum received as a part of the previous build task result (see
+\l{#arch-result Result Manifest}).
+
+
\h#arch-result|Result Manifest|
The result manifest describes a build result. The manifest synopsis is
@@ -556,6 +582,9 @@ status: <status>
[install-log]: <text>
[test-installed-log]: <text>
[uninstall-log]: <text>
+
+[worker-checksum]: <checksum>
+[dependency-checksum]: <checksum>
\
@@ -586,6 +615,7 @@ status: <status>
The overall (cumulative) build result status. Valid values are:
\
+skip # Package update and subsequent operations were skipped.
success # All operations completed successfully.
warning # One or more operations completed with warnings.
error # One or more operations completed with errors.
@@ -606,6 +636,12 @@ abnormally, for example, due to the package manager or build system crash.
Note that the overall \c{status} value should appear before any per-operation
\c{*-status} values.
+The \c{skip} status indicates that the received from the controller build task
+checksums have not changed and the task execution has therefore been skipped
+under the assumtion that it would have produced the same result. See
+\c{agent-checksum}, \c{worker-checksum}, and \c{dependency-checksum} for
+details.
+
\h2#arch-result-x-status|\c{*-status}|
@@ -640,6 +676,26 @@ the list of supported operation names refer to the \c{*-status} value
description.
+\h2#arch-result-dependency-checksum|\c{dependency-checksum}|
+
+\
+[dependency-checksum]: <checksum>
+\
+
+The package dependency checksum obtained as a byproduct of the package
+configuration operation. See \l{bpkg-pkg-build(1)} command's
+\c{--rebuild-checksum} option for details.
+
+
+\h2#arch-result-worker-checksum|\c{worker-checksum}|
+
+\
+[worker-checksum]: <checksum>
+\
+
+The version of the worker logic used to perform the package build task.
+
+
\h#arch-task-req|Task Request Manifest|
An agent (or controller acting as an agent) sends a task request to its
@@ -734,6 +790,7 @@ subsequent sections.
session: <id>
[challenge]: <text>
[result-url]: <url>
+[agent-checksum]: <checksum>
\
@@ -771,6 +828,16 @@ private key and then \c{base64}-encoding the result.
The URL to POST (upload) the result request to.
+\h2#arch-task-res-agent-checksum|\c{agent-checksum}|
+
+\
+[agent-checksum]: <checksum>
+\
+
+The agent checksum received as a part of the previous build task result
+request (see \l{#arch-result-req Result Request Manifest}).
+
+
\h#arch-result-req|Result Request Manifest|
On completion of a task an agent (or controller acting as an agent) sends the
@@ -784,6 +851,7 @@ description of each value in subsequent sections.
\
session: <id>
[challenge]: <text>
+[agent-checksum]: <checksum>
\
@@ -807,6 +875,15 @@ response. It must be present only if the \c{challenge} value was present in
the task response.
+\h2#arch-result-req-agent-checksum|\c{agent-checksum}|
+
+\
+[agent-checksum]: <checksum>
+\
+
+The version of the agent logic used to perform the package build task.
+
+
\h#arch-worker|Worker Logic|
The \c{bbot} worker builds each package in a \i{build environment} that is