path: root/doc/concepts/cache-pragma.org

* Action caching pragma

** Introduction: exit code, build failures, and caching

The exit code of a process is used to signal success or failure
of that process. By convention, 0 indicates success and any other
value indicates some form of failure.

Our tool expects all build actions to follow this convention. A
non-zero exit code of a regular build action has two consequences.
- As the action failed, the whole build is aborted and considered failed.
- As such a failed action can never be part of a successful build,
  it is (effectively) not cached.
This non-caching is achieved by rerequesting an action without
cache look up, if a failed action from cache is reported.

In particular, for building, we have the property that everything
that does not lead to aborting the build can (and will) be cached.
This property is justified as we expect build actions to behave in
a functional way.

** Test and run actions

Tests have a lot of similarity to regular build actions: a process is
run with given inputs, and the results are processed further (e.g.,
to create reports on test suites). However, they break the above
described connection between caching and continuation of the
build: we expect that some tests might be flaky (even though they
shouldn't be, of course) and hence only want to cache successful
tests. Nevertheless, we do want to continue testing after the first
test failure.

Another breakage of the functionality assumption of actions are
"run" actions, i.e., local actions that are executed either because
of their side effect on the host system, or because of their
non-deterministic results (e.g., monitoring some resource). Those
actions should never be cached, but if they fail, the build should
be aborted.

** Tainting

Targets that, directly or indirectly, depend on non-functional
actions are not regular targets. They are test targets, run targets,
benchmark results, etc; in any case, they are tainted in some way.
When adding high-level caching of targets, we will only support
caching for untainted targets.

To make everybody aware of their special nature, they are clearly
marked as such: tainted targets not generated by a tainted rule (e.g.,
a test rule) have to explicitly state their taintedness in their
attributes. This declaration also gives a natural way to mark targets
that are technically pure, but still should be used only in test,
e.g., a mock version of a larger library.

Besides being for tests only, there might be other reasons why a
target might not be fit for general use, e.g., configuration files
with accounts for developer access, or files under restrictive
licences. To avoid having to extend the framework for each new
use case, we allow arbitrary strings as markers for the kind of
taintedness of a target. Of course, a target can be tainted in more
than one way.

More precisely, rules can have ~"tainted"~ as an additional
property. Moreover ~"tainted"~ is another reserved keyword for
target arguments (like ~"type"~ and ~"arguments_config"~). In both
cases, the value has to be a list of strings, and the empty list
is assumed, if not specified.

A rule is tainted with the set of strings in its ~"tainted"~
property. A target is tainted with the union of the set of strings
of its ~"tainted"~ argument and the set of strings its generating
rule is tainted with.

Every target has to be tainted with (at least) the union of what
its dependencies are tainted with.

For tainted targets, the ~analyse~, ~build~, and ~install~ commands
report the set of strings the target is tainted with.

*** ~"may_fail"~ and ~"no_cache"~ properties of ~"ACTION"~

The ~"ACTION"~ function in the defining expression of a rule
have two additional (besides inputs, etc) parameters ~"may_fail"~
and ~"no_cache"~. Those are not evaluated and have to be lists
of strings (with empty assumed if the respective parameter is not
present). Only strings the defining rule is tainted with may occur
in that list. If the list is not empty, the corresponding may-fail
or no-cache bit of the action is set.

For actions with the ~"may_fail"~ bit set, the optional parameter
~"fail_message"~ with default value ~"action failed"~ is evaluated.
That message will be reported if the action returns a non-zero
exit value.

Actions with the no-cache bit set are never cached. If an action
with the may-fail bit set exits with non-zero exit value, the build
is continued if the action nevertheless managed to produce all
expected outputs. We continue to ignore actions with non-zero exit
status from cache.

*** Marking of failed artifacts

To simplify finding failures in accumulated reports, our tool
keeps track of artifacts generated by failed actions. More
precisely, artifacts are considered failed if one of the following
conditions applies.
- Artifacts generated by failed actions are failed.
- Tree artifacts containing a failed artifact are failed.
- Artifacts generated by an action taking a failed artifact as
  input are failed.
The identifiers used for built artifacts (including trees) remain
unchanged; in particular, they will only describe the contents and
not if they were obtained in a failed way.

When reporting artifacts, e.g., in the log file, an additional marker
is added to indicate that the artifact is a failed one. After every
~build~ or ~install~ command, if the requested artifacts contain
failed one, a different exit code is returned.

*** The ~install-cas~ subcommand

A typical workflow for testing is to first run the full test suite
and then only look at the failed tests in more details. As we don't
take failed actions from cache, installing the output can't be
done by rerunning the same target as ~install~ instead of ~build~.
Instead, the output has to be taken from CAS using the identifier
shown in the build log. To simplify this workflow, there is the
~install-cas~ subcommand that installs a CAS entry, identified by
the identifier as shown in the log to a given location or (if no
location is specified) to ~stdout~.