Targets are defined in TARGETS files. Each target file is a single
JSON object. If the target name is contained as a key in that
object, the corresponding value defines the target; otherwise it is
implicitly considered a source file. The target definition itself
is a JSON object as well. The mandatory key "type" specifies
the rule defining the target; the meaning of the remaining keys
depends on the rule defining the target.
There are a couple of rules built in, all named by a single string. The user can define additional rules (and, in fact, we expect the majority of targets to be defined by user-defined rules); referring to them in a qualified way (with module) will always refer to those even if new built-in rules are added later (as built-in rules will always be only named by a single string).
The following rules are built in. Built-in rules can have a special syntax.
The "export" rule evaluates a given target in a specified
configuration. More precisely, the field "target" has to name a single
target (not a list of targets), the field "flexible_config" a list
of strings, treated as variable names, and the field "fixed_config"
has to be a map that is taken unevaluated. It is a requirement that
the domain of the "fixed_config" and the "flexible_config" be
disjoint. The optional fields "doc" and "config_doc" can be used
to describe the target and the "flexible_config", respectively.
To evaluate an "export" target, first the configuration is
restricted to the "flexible_config" and then the union with the
"fixed_config" is built. The target specified in "target" is
then evaluated. It is a requirement that this target be untainted.
The result is the result of this evaluation; artifacts, runfiles,
and provides map are forwarded unchanged.
The main point of the "export" rule is, that the relevant part
of the configuration can be determined without having to analyze
the target itself. This makes such rules eligible for target-level
caching (provided the content of the repository as well as all
reachable ones can be determined cheaply). This eligibility is also
the reason why it is good practice to only depend on "export"
targets of other repositories.
The "install" rules allows to stage artifacts (and runfiles) of
other targets in a different way. More precisely, a new stage (i.e.,
map of artifacts with keys treated as file names) is constructed
in the following way.
The runfiles from all targets in the "deps" field are taken; the
"deps" field is an evaluated field and has to evaluate to a list
of targets. It is an error, if those runfiles conflict.
The "files" argument is a special form. It has to be a map, and
the keys are taken as paths. The values are evaluated and have
to evaluate to a single target. That target has to have a single
artifact or no artifacts and a single run file. In this way, "files"
defines a stage; this stage overlays the runfiles of the "deps"
and conflicts are ignored.
Finally, the "dirs" argument has to evaluate to a list of
pairs (i.e., lists of length two) with the first argument a target
name and the second argument a string, taken as directory name. For
each entry, both, runfiles and artifacts of the specified target
are staged to the specified directory. It is an error if a conflict
with the stage constructed so far occurs.
Both, runfiles and artifacts of the "install" target are the stage
just described. An "install" target always has an empty provides
map. Any provided information of the dependencies is discarded.
The "generic" rules allows to define artifacts as the output
of an action. This is mainly useful for ad-hoc constructions; for
anything occuring more often, a proper user-defined rule is usually
the better choice.
The "deps" argument is evaluated and has to evaluate to a list
of target names. The runfiles and artifacts of these targets form
the inputs of the action. Conflicts are not an error and resolved
by giving precedence to the artifacts over the runfiles; conflicts
within artifacts or runfiles are resolved in a latest-wins fashion
using the order of the targets in the evaluated "deps" argument.
The fields "cmds", "out_dirs", "outs", and "env" are evaluated
fields where "cmds", "out_dirs", and "outs" have to evaluate to
a list of strings, and "env" has to evaluate to a map of
strings. During their evaluation, the functions "out_dirs", "outs"
and "runfiles" can be used to access the logical paths of the
directories, artifacts and runfiles, respectively, of a target
specified in "deps". Here, "env" specifies the environment in
which the action is carried out. "out_dirs" and "outs" define the
output directories and files, respectively, the action has to
produce. Since some artifacts are to be produced, at least one of
"out_dirs" or "outs" must be a non-empty list of strings. It is an
error if one or more paths are present in both the "out_dirs" and
"outs". Finally, the strings in "cmds" are extended by a newline
character and joined, and command of the action is interpreting this
string by sh.
The artifacts of this target are the outputs (as declared by
"out_dirs" and "outs") of this action. Runfiles and provider map
are empty.
The "file_gen" rule allows to specify a file with a given content.
To be able to accurately report about file names of artifacts
or runfiles of other targets, they can be specified in the field
"deps" which has to evaluate to a list of targets. The names
of the artifacts and runfiles of a target specified in "deps"
can be accessed through the functions "outs" and "runfiles",
respectively, during the evaluation of the arguments "name" and
"data" which have to evaluate to a single string.
Artifacts and runfiles of a "file_gen" target are a singleton map
with key the result of evaluating "name" and value a (non-executable)
file with content the result of evaluating "data". The provides
map is empty.
The "configure" rule allows to configure a target with a given configuration.
Similar to the "export" rule, the field "target" must name a single target
(not a list). The "config" field is evaluated and must result in a map, which
is used as configuration for the given target.
This rule uses the given configuration to overlay the current environment for
evaluating the given target, and thereby performs a configuration transition. It
forwards all results (artifacts/runfiles/provides map) of the configured target
to the upper context. The result of a target that uses this rule is the result
of the target given in the "target" field (the configured target).