Document built-in rules

2 files changed, 124 insertions, 2 deletions

diff --git a/doc/concepts/built-in-rules.org b/doc/concepts/built-in-rules.org
new file mode 100644
index 00000000..0be32019
--- /dev/null
+++ b/doc/concepts/built-in-rules.org
@@ -0,0 +1,118 @@
+* Built-in rules
+
+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.
+
+** ~"export"~
+
+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.
+
+** ~"install"~
+
+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.
+
+** ~"generic"~
+
+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"~, ~"outs"~, and ~"env"~ are evaluated fields
+where ~"cmds"~ and ~"outs"~ have to evalaute to a list of strings,
+and ~"env"~ has to evaluate to a map of strings. During their
+evaluation, the functions ~"outs"~ and ~"runfiles"~ can be used to
+access the logical paths of the artifcats and runfiles, respectively,
+of a target specified in ~"deps"~. Here, ~"env"~ specifies the
+environment in which the action is carried out and ~"outs"~ the
+outputs, the action has to produce. 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
+~"outs"~) of this action. Runfiles and provider map are empty.
+
+** ~"file_gen"~
+
+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.
diff --git a/doc/concepts/rules.org b/doc/concepts/rules.org
index f5cfdd8c..a8837ae9 100644
--- a/doc/concepts/rules.org
+++ b/doc/concepts/rules.org
@@ -1,4 +1,4 @@
-* Rules
+* User-defined Rules
 
 Targets are defined in terms of high-level concepts like "libraries",
 "binaries", etc. In order to translate these high-level definitions
@@ -9,7 +9,11 @@ single point how all targets of a given type are built.
 
 Rules are defined in rules files (by default named ~RULES~). Those
 contain a JSON object mapping rule names to their rule definition.
-For rules, the same naming scheme as for targets applies.
+For rules, the same naming scheme as for targets applies. However,
+built-in rules (always named by a single string) take precedence
+in naming; to explicitly refer to a rule defined in the current
+module, the module has to be specified, possibly by a relative
+path, e.g., ~["./", ".", "install"]~.
 
 ** Basic components of a rule