Document Store Derivations and Deriving Paths (#12290)

This is a big step documenting the store layer on its own, separately from the evaluator (and `builtins.derivation`).

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

src/libcmd/misc-store-flags.cc

@@ -120,7 +120,7 @@ Args::Flag contentAddressMethod(ContentAddressMethod * method)
 
     - [`text`](@docroot@/store/store-object/content-address.md#method-text):
       Like `flat`, but used for
-      [derivations](@docroot@/glossary.md#store-derivation) serialized in store object and
+      [derivations](@docroot@/glossary.md#gloss-store-derivation) serialized in store object and
       [`builtins.toFile`](@docroot@/language/builtins.html#builtins-toFile).
       For advanced use-cases only;
       for regular usage prefer `nar` and `flat`.

src/libexpr/primops.cc

@@ -1595,9 +1595,13 @@ static RegisterPrimOp primop_placeholder({
     .name = "placeholder",
     .args = {"output"},
     .doc = R"(
-      Return a placeholder string for the specified *output* that will be
-      substituted by the corresponding output path at build time. Typical
-      outputs would be `"out"`, `"bin"` or `"dev"`.
+      Return at
+      [output placeholder string](@docroot@/store/drv.md#output-placeholder)
+      for the specified *output* that will be substituted by the corresponding
+      [output path](@docroot@/glossary.md#gloss-output-path)
+      at build time.
+
+      Typical outputs would be `"out"`, `"bin"` or `"dev"`.
     )",
     .fun = prim_placeholder,
 });
@@ -2135,12 +2139,15 @@ static RegisterPrimOp primop_outputOf({
     .name = "__outputOf",
     .args = {"derivation-reference", "output-name"},
     .doc = R"(
-      Return the output path of a derivation, literally or using a placeholder if needed.
+      Return the output path of a derivation, literally or using an
+      [input placeholder string](@docroot@/store/drv.md#input-placeholder)
+      if needed.
 
       If the derivation has a statically-known output path (i.e. the derivation output is input-addressed, or fixed content-addresed), the output path will just be returned.
-      But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), a placeholder will be returned instead.
+      But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), an input placeholder will be returned instead.
 
-      *`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be a placeholder reference. If the derivation is produced by a derivation, you must explicitly select `drv.outPath`.
+      *`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be an input placeholder reference.
+      If the derivation is produced by a derivation, you must explicitly select `drv.outPath`.
       This primop can be chained arbitrarily deeply.
       For instance,
 
@@ -2150,9 +2157,9 @@ static RegisterPrimOp primop_outputOf({
         "out"
       ```
 
-      will return a placeholder for the output of the output of `myDrv`.
+      will return a input placeholder for the output of the output of `myDrv`.
 
-      This primop corresponds to the `^` sigil for derivable paths, e.g. as part of installable syntax on the command line.
+      This primop corresponds to the `^` sigil for [deriving paths](@docroot@/glossary.md#gloss-deriving-paths), e.g. as part of installable syntax on the command line.
     )",
     .fun = prim_outputOf,
     .experimentalFeature = Xp::DynamicDerivations,

src/libstore/globals.hh

@@ -189,7 +189,7 @@ public:
         this, SYSTEM, "system",
         R"(
           The system type of the current Nix installation.
-          Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in [`extra-platforms`](#conf-extra-platforms).
+          Nix will only build a given [store derivation](@docroot@/glossary.md#gloss-store-derivation) locally when its `system` attribute equals any of the values specified here or in [`extra-platforms`](#conf-extra-platforms).
 
           The default value is set when Nix itself is compiled for the system it will run on.
           The following system types are widely used, as Nix is actively supported on these platforms:
@@ -825,7 +825,7 @@ public:
         R"(
           System types of executables that can be run on this machine.
 
-          Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in the [`system` option](#conf-system).
+          Nix will only build a given [store derivation](@docroot@/glossary.md#gloss-store-derivation) locally when its `system` attribute equals any of the values specified here or in the [`system` option](#conf-system).
 
           Setting this can be useful to build derivations locally on compatible machines:
           - `i686-linux` executables can be run on `x86_64-linux` machines (set by default)

src/nix/derivation-show.cc

@@ -1,5 +1,5 @@
-// FIXME: integrate this with nix path-info?
-// FIXME: rename to 'nix store derivation show' or 'nix debug derivation show'?
+// FIXME: integrate this with `nix path-info`?
+// FIXME: rename to 'nix store derivation show'?
 
 #include "command.hh"
 #include "common-args.hh"

src/nix/search.md

@@ -62,8 +62,8 @@ R""(
 
 # Description
 
-`nix search` searches [*installable*](./nix.md#installables) (which can be evaluated, that is, a
-flake or Nix expression, but not a store path or store derivation path) for packages whose name or description matches all of the
+`nix search` searches [*installable*](./nix.md#installables) that can be evaluated, that is, a
+flake or Nix expression, but not a [store path] or [deriving path]) for packages whose name or description matches all of the
 regular expressions *regex*. For each matching package, It prints the
 full attribute name (from the root of the [installable](./nix.md#installables)), the version
 and the `meta.description` field, highlighting the substrings that
@@ -75,6 +75,9 @@ it avoids highlighting the entire name and description of every package.
 > Note that in this context, `^` is the regex character to match the beginning of a string, *not* the delimiter for
 > [selecting a derivation output](@docroot@/command-ref/new-cli/nix.md#derivation-output-selection).
 
+[store path]: @docroot@/glossary.md#gloss-store-path
+[deriving path]: @docroot@/glossary.md#gloss-deriving-path
+
 # Flake output attributes
 
 If no flake output attribute is given, `nix search` searches for