summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorKlaus Aehlig <klaus.aehlig@huawei.com>2023-07-10 13:33:28 +0200
committerKlaus Aehlig <klaus.aehlig@huawei.com>2023-07-12 11:50:13 +0200
commit711de5ed45d06d28a67a8fecedb1985b264b1bcf (patch)
tree57cbcd3173f8186ece0e4bec12951c6040a75525 /doc
parent85938804a4a043c75cc4ca51a64ee789e55ba7cb (diff)
downloadjustbuild-711de5ed45d06d28a67a8fecedb1985b264b1bcf.tar.gz
Execution properties are no longer a future design
... but an implemented concept. Update the documentation accordingly.
Diffstat (limited to 'doc')
-rw-r--r--doc/concepts/execution-properties.md (renamed from doc/future-designs/execution-properties.md)56
-rw-r--r--doc/future-designs/service-target-cache.md5
2 files changed, 22 insertions, 39 deletions
diff --git a/doc/future-designs/execution-properties.md b/doc/concepts/execution-properties.md
index 7cb9e682..3fa4b070 100644
--- a/doc/future-designs/execution-properties.md
+++ b/doc/concepts/execution-properties.md
@@ -28,12 +28,11 @@ requires a single build executing actions on two (or more) platforms.
#### Calls to foreign build systems
Often, third-party dependencies that natively build with a different
-build system and don't change to often (yet often enough to not
+build system and don't change too often (yet often enough to not
have them part of the build image) are simply put in a single
action, so that they get built only once, and then stay in cache for
everyone. This is precisely, what our `rules-cc` rules like
-`["CC/foreign/make",
-"library"]` and `["CC/foreign/cmake", "library"]` do.
+`["CC/foreign/make", "library"]` and `["CC/foreign/cmake", "library"]` do.
For those compound actions, we of course expect them to run longer
than normal actions that only consist of a single compiler or linker
@@ -52,30 +51,13 @@ require a lengthy sequence of interactions to get into the situation
that is to be tested, or to verify the absence of degrading of the
service under high load or extended usage.
-Status Quo
-----------
-
-Action can at the moment specify
-
- - the actual action, i.e., inputs, outputs, and the command vector,
- - the environment variables,
- - a property that the action can fail (e.g., for test actions), and
- - a property that the action is not to be taken from cache (e.g.,
- testing for flakiness).
+Interfaces related to action-controlled execution properties
+------------------------------------------------------------
-No other properties can be set by the action itself. In particular,
-remote-execution properties and timeout are equal for all actions of a
-build.
+### Properties of the `"ACTION"` function
-Proposed changes
-----------------
-
-### Extension of the `"ACTION"` function
-
-We propose to extend the `"ACTION"` function available in the rule
-definition by the following attributes. All of the new attributes are
-optional, and the default is taken to reflect the status quo. Hence, the
-proposed changes are backwards compatible.
+The `"ACTION"` function available in the rule definition also has
+the following attributes. All of those attributes are optional.
#### `"execution properties"`
@@ -88,7 +70,7 @@ remote-execution properties specified at the invocation of the build
precedence).
Local execution continues to any execution properties specified.
-However, with the auxiliary change to `just` described later, such
+However, with the dispatch functionality of `just` described later, such
execution properties can also influence a build that is local by
default.
@@ -101,23 +83,23 @@ build (the default value, or whatever is specified on the command
line) is multiplied by the given factor and taken as timeout for
this action. This applies for both, local and remote builds.
-### Extension to the built-in `"generic"` built-in rule
+### Execution properties of the the built-in `"generic"` rule
As the built-in `"generic"` rule basically is there to allow the
-definition of an action in an ad-hoc fashion, it will be extended
-in the same way. More precisely, the fields `"timeout scaling"` and
-`"execution properties"` will be added and are taken as additional
-arguments to the underlying action, with the same semantics as the
-respective fields of the `"ACTION"` constructor.
+definition of an action in an ad-hoc fashion, it also provides the
+same attributes. More precisely, the fields `"timeout scaling"`
+and `"execution properties"` are taken as additional arguments to
+the underlying action, with the same semantics as the respective
+fields of the `"ACTION"` constructor.
-### `just` to support dispatching based on remote-execution properties
+### `just` dispatching based on remote-execution properties
In simple setups, like using `just execute`, the remote execution is not
capable of dispatching to different workers based on remote-execution
properties. To nevertheless have the benefits of using different
-execution environments, `just` will allow an optional configuration file
+execution environments, `just` allows an optional configuration file
to be passed on the command line via a new option
-`--endpoint-configuration`. This configuration file will contain a list
+`--endpoint-configuration`. This configuration file contains a list
of pairs of remote-execution properties and remote-execution endpoints.
The first matching entry (i.e., the first entry where the
remote-execution property map coincides with the given map when
@@ -130,7 +112,3 @@ When connecting a non-standard remote-execution endpoint, `just` will
ensure that the applicable CAS of that endpoint will have all the needed
artifacts for that action. It will also transfer all result artifacts
back to the CAS of the default remote-execution endpoint.
-
-`just serve` (once implemented) will also support this new option. As
-with the default execution endpoint, there is the understanding that the
-client uses the same configuration as the `just serve` endpoint.
diff --git a/doc/future-designs/service-target-cache.md b/doc/future-designs/service-target-cache.md
index 941115e9..ffb25203 100644
--- a/doc/future-designs/service-target-cache.md
+++ b/doc/future-designs/service-target-cache.md
@@ -50,6 +50,11 @@ The associated remote-execution endpoint can well be the same process
simultaneously acting as `just execute`. In fact, this is the default if
no remote-execution endpoint is specified.
+`just serve` will also support the `--endpoint-configuration`
+option. As with the default execution endpoint, there is the
+understanding that the client uses the same configuration as the
+`just serve` endpoint.
+
### Protocol
Communication is handled via `grpc` exchanging `proto` buffers