doc: Convert orgmode files to markdown

1 files changed, 0 insertions, 167 deletions

diff --git a/doc/concepts/built-in-rules.org b/doc/concepts/built-in-rules.org
deleted file mode 100644
index 9463b10c..00000000
--- a/doc/concepts/built-in-rules.org
+++ /dev/null
@@ -1,167 +0,0 @@
-* 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 occurring 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.
-
-** ~"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.
-
-** ~"tree"~
-
-The ~"tree"~ rule allows to specify a tree out of the artifact
-stage of given targets. More precisely, the deps field ~"deps"~
-has to evaluate to a list of targets. For each target, runfiles
-and artifacts are overlayed in an artifacts-win fashion and
-the union of the resulting stages is taken; it is an error if conflicts
-arise in this way. The resulting stage is transformed into a tree.
-Both, artifacts and runfiles of the ~"tree"~ target are a singleton map
-with the key the result of evaluating ~"name"~ (which has to evaluate to
-a single string) and value that tree.
-
-
-** ~"configure"~
-
-The ~"configure"~ rule allows to configure a target with a given
-configuration. The field ~"target"~ is evaluated and the result
-of the evaluation 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).
-
-As a full configuration transition is performed, the same care has
-to be taken when using this rule as when writing a configuration
-transition in a rule. Typically, this rule is used only at a
-top-level target of a project and configures only variables internally
-to the project. In any case, when using non-internal targets as
-dependencies (i.e., targets that a caller of the ~"configure"~
-potentially might use as well), care should be taken that those
-are only used in the initial configuration. Such preservation of
-the configuration is necessary to avoid conflicts, if the targets
-depended upon are visible in the ~"configure"~ target itself, e.g.,
-as link dependency (which almost always happens when depending on a
-library). Even if a non-internal target depended upon is not visible
-in the ~"configure"~ target itself, requesting it in a modified
-configuration causes additional overhead by increasing the target
-graph and potentially the action graph.