Document Derivations and Deriving Paths

doc/manual/redirects.js

@@ -346,6 +346,9 @@ const redirects = {
     "scoping-rules": "scoping.html",
     "string-literal": "string-literals.html",
   },
+  "language/derivations.md": {
+    "builder-execution": "store/drv/building.md#builder-execution",
+  },
   "installation/installing-binary.html": {
     "linux": "uninstall.html#linux",
     "macos": "uninstall.html#macos",
@@ -372,6 +375,7 @@ const redirects = {
   "glossary.html": {
     "gloss-local-store": "store/types/local-store.html",
     "gloss-chroot-store": "store/types/local-store.html",
+    "gloss-store-derivation": "#gloss-derivation",
   },
 };
 

doc/manual/source/SUMMARY.md.in

@@ -22,6 +22,8 @@
   - [Store Object](store/store-object.md)
     - [Content-Addressing Store Objects](store/store-object/content-address.md)
   - [Store Path](store/store-path.md)
+  - [Derivation and Deriving Path](store/drv.md)
+  - [Building](store/building.md)
   - [Store Types](store/types/index.md)
 {{#include ./store/types/SUMMARY.md}}
 - [Nix Language](language/index.md)

doc/manual/source/command-ref/nix-build.md

@@ -37,11 +37,11 @@ directory containing at least a file named `default.nix`.
 
 `nix-build` is essentially a wrapper around
 [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix
-expression to a low-level [store derivation]) and [`nix-store
+expression to a low-level [derivation]) and [`nix-store
 --realise`](@docroot@/command-ref/nix-store/realise.md) (to build the store
 derivation).
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[derivation]: @docroot@/glossary.md#gloss-derivation
 
 > **Warning**
 >
@@ -80,7 +80,7 @@ except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](n
 
 ```console
 $ nix-build '<nixpkgs>' --attr firefox
-store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
+derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
 /nix/store/d18hyl92g30l...-firefox-1.5.0.7
 
 $ ls -l result

doc/manual/source/command-ref/nix-copy-closure.md

@@ -42,9 +42,9 @@ When using public key authentication, you can avoid typing the passphrase with `
 
 - `--include-outputs`
 
-  Also copy the outputs of [store derivation]s included in the closure.
+  Also copy the outputs of [derivation]s included in the closure.
 
-  [store derivation]: @docroot@/glossary.md#gloss-store-derivation
+  [derivation]: @docroot@/glossary.md#gloss-derivation
 
 - `--use-substitutes` / `-s`
 

doc/manual/source/command-ref/nix-env/install.md

@@ -26,7 +26,7 @@ The arguments *args* map to store paths in a number of possible ways:
   These are [realised], and the resulting output paths are installed.
   Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
 
-  [derivation]: @docroot@/glossary.md#gloss-derivation
+  [derivation expression]: @docroot@/glossary.md#gloss-derivation-expression
   [default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
   [realised]: @docroot@/glossary.md#gloss-realise
 
@@ -66,9 +66,9 @@ The arguments *args* map to store paths in a number of possible ways:
   This can be used to override the priority of the derivations being installed.
   This is useful if *args* are [store paths], which don't have any priority information.
 
-- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
+- If *args* are [store paths] to [derivations](@docroot@/glossary.md#gloss-derivation), then those derivations are [realised], and the resulting output paths are installed.
 
-- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
+- If *args* are [store paths] not to derivations, then these are [realised] and installed.
 
 - By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
   This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
@@ -198,7 +198,7 @@ To copy the store path with symbolic name `gcc` from another profile:
 $ nix-env --install --from-profile /nix/var/nix/profiles/foo gcc
 ```
 
-To install a specific [store derivation] (typically created by
+To install a specific [derivation] (typically created by
 `nix-instantiate`):
 
 ```console

doc/manual/source/command-ref/nix-env/query.md

@@ -125,7 +125,10 @@ derivation is shown unless `--no-name` is specified.
 
   - `--drv-path`
 
-    Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
+    Print the [store path] to the [derivation].
+
+    [store path]: @docroot@/glossary.md#gloss-store-path
+    [derivation]: @docroot@/glossary.md#gloss-derivation
 
   - `--out-path`
 

doc/manual/source/command-ref/nix-instantiate.md

@@ -1,6 +1,6 @@
 # Name
 
-`nix-instantiate` - instantiate store derivations from Nix expressions
+`nix-instantiate` - instantiate derivations from Nix expressions
 
 # Synopsis
 
@@ -17,13 +17,13 @@
 
 # Description
 
-The command `nix-instantiate` produces [store derivation]s from (high-level) Nix expressions.
+The command `nix-instantiate` produces [derivation]s from (high-level) Nix expressions.
 It evaluates the Nix expressions in each of *files* (which defaults to
 *./default.nix*). Each top-level expression should evaluate to a
 derivation, a list of derivations, or a set of derivations. The paths
-of the resulting store derivations are printed on standard output.
+of the resulting derivations are printed on standard output.
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[derivation]: @docroot@/glossary.md#gloss-derivation
 
 If *files* is the character `-`, then a Nix expression will be read from
 standard input.
@@ -42,8 +42,8 @@ standard input.
 - `--eval`
 
   Just parse and evaluate the input files, and print the resulting
-  values on standard output. No instantiation of store derivations
-  takes place.
+  values on standard output.
+  Derivations are not serialized and written to the store, but instead just hashed and discarded.
 
   > **Warning**
   >
@@ -133,7 +133,7 @@ standard input.
 
 # Examples
 
-Instantiate [store derivation]s from a Nix expression, and build them using `nix-store`:
+Instantiate [derivation]s from a Nix expression, and build them using `nix-store`:
 
 ```console
 $ nix-instantiate test.nix (instantiate)

doc/manual/source/command-ref/nix-store/query.md

@@ -26,14 +26,14 @@ symlink.
 
 - `--use-output` / `-u`
 
-  For each argument to the query that is a [store derivation], apply the
+  For each argument to the query that is a [derivation], apply the
   query to the output path of the derivation instead.
 
 - `--force-realise` / `-f`
 
   Realise each argument to the query first (see [`nix-store --realise`](./realise.md)).
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[derivation]: @docroot@/glossary.md#gloss-derivation
 
 # Queries
 
@@ -54,12 +54,12 @@ symlink.
   This query has one option:
 
     - `--include-outputs`
-      Also include the existing output paths of [store derivation]s,
+      Also include the existing output paths of [derivation]s,
       and their closures.
 
   This query can be used to implement various kinds of deployment. A
   *source deployment* is obtained by distributing the closure of a
-  store derivation. A *binary deployment* is obtained by distributing
+  derivation. A *binary deployment* is obtained by distributing
   the closure of an output path. A *cache deployment* (combined
   source/binary deployment, including binaries of build-time-only
   dependencies) is obtained by distributing the closure of a store
@@ -112,7 +112,7 @@ symlink.
   of the `dot` tool of AT\&T's [Graphviz
   package](http://www.graphviz.org/). This can be used to visualise
   dependency graphs. To obtain a build-time dependency graph, apply
-  this to a store derivation. To obtain a runtime dependency graph,
+  this to a derivation. To obtain a runtime dependency graph,
   apply it to an output path.
 
 - `--tree`
@@ -128,13 +128,13 @@ symlink.
   Prints the references graph of the store paths *paths* in the
   [GraphML](http://graphml.graphdrawing.org/) file format. This can be
   used to visualise dependency graphs. To obtain a build-time
-  dependency graph, apply this to a [store derivation]. To obtain a
+  dependency graph, apply this to a [derivation]. To obtain a
   runtime dependency graph, apply it to an output path.
 
 - `--binding` *name* / `-b` *name*
 
   Prints the value of the attribute *name* (i.e., environment
-  variable) of the [store derivation]s *paths*. It is an error for a
+  variable) of the [derivation]s *paths*. It is an error for a
   derivation to not have the specified attribute.
 
 - `--hash`

doc/manual/source/command-ref/nix-store/realise.md

@@ -11,10 +11,10 @@
 
 Each of *paths* is processed as follows:
 
-- If the path leads to a [store derivation]:
-  1. If it is not [valid], substitute the store derivation file itself.
+- If the path leads to a [derivation]:
+  1. If it is not [valid], substitute the derivation file itself.
   2. Realise its [output paths]:
-    - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure].
+    - Try to fetch from [substituters] the [store objects] associated with the output paths in the derivation's [closure].
       - With [content-addressed derivations] (experimental):
         Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database].
     - For any store paths that cannot be substituted, produce the required store objects:
@@ -23,11 +23,11 @@ Each of *paths* is processed as follows:
          <!-- TODO: Link to build process page #8888 -->
 - Otherwise, and if the path is not already valid: Try to fetch the associated [store objects] in the path's [closure] from [substituters].
 
-If no substitutes are available and no store derivation is given, realisation fails.
+If no substitutes are available and no derivation is given, realisation fails.
 
 [store paths]: @docroot@/store/store-path.md
 [valid]: @docroot@/glossary.md#gloss-validity
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[derivation]: @docroot@/glossary.md#gloss-derivation
 [output paths]: @docroot@/glossary.md#gloss-output-path
 [store objects]: @docroot@/store/store-object.md
 [closure]: @docroot@/glossary.md#gloss-closure
@@ -71,7 +71,7 @@ For non-derivation arguments, the argument itself is printed.
 
 # Examples
 
-This operation is typically used to build [store derivation]s produced by
+This operation is typically used to build [derivation]s produced by
 [`nix-instantiate`](@docroot@/command-ref/nix-instantiate.md):
 
 ```console

doc/manual/source/glossary.md

@@ -21,31 +21,35 @@
 
 - [derivation]{#gloss-derivation}
 
-  A description of a build task. The result of a derivation is a
-  store object. Derivations declared in Nix expressions are specified
-  using the [`derivation` primitive](./language/derivations.md). These are
-  translated into low-level *store derivations* (implicitly by
-  `nix-build`, or explicitly by `nix-instantiate`).
+  A single build task.
+  See [Derivation](@docroot@/store/drv.md#derivation) for details.
 
   [derivation]: #gloss-derivation
 
-- [store derivation]{#gloss-store-derivation}
+- [derivation path]{#gloss-derivation-path}
 
-  A [derivation] represented as a `.drv` file in the [store].
-  It has a [store path], like any [store object].
-  It is the [instantiated][instantiate] form of a derivation.
+  A [store path] which uniquely identifies a [derivation].
 
-  Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+  See [Referencing Derivations](@docroot@/store/drv.md#derivation-path) for details.
 
-  See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
+  Not to be confused with [deriving path].
 
-  [store derivation]: #gloss-store-derivation
+  [derivation path]: #gloss-derivation-path
+
+- [derivation expression]{#gloss-derivation-expression}
+
+  A description of a [derivation] in the Nix language.
+  The output(s) of a derivation are store objects.
+  Derivations are typically specified in Nix expressions using the [`derivation` primitive](./language/derivations.md).
+  These are translated into store layer *derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
+
+  [derivation expression]: #gloss-derivation-expression
 
 - [instantiate]{#gloss-instantiate}, instantiation
 
-  Save an evaluated [derivation] as a [store derivation] in the Nix [store].
+  Translate a [derivation expression] into a [derivation].
 
-  See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
+  See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a derivation from a Nix expression that evaluates to a derivation.
 
   [instantiate]: #gloss-instantiate
 
@@ -188,7 +192,7 @@
   >
   > The contents of a `.nix` file form a Nix expression.
 
-  Nix expressions specify [derivations][derivation], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
+  Nix expressions specify [derivation expressions][derivation expression], which are [instantiated][instantiate] into the Nix store as [derivations][derivation].
   These derivations can then be [realised][realise] to produce [outputs][output].
 
   > **Example**
@@ -246,18 +250,15 @@
 
 - [deriving path]{#gloss-deriving-path}
 
-  Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
-  This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
-  There are two forms:
+  Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
 
-  - *constant*: just a [store path]
-    It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
+  See [Deriving Path](./store/drv.md#deriving-path) for details.
 
-  - *output*: a pair of a [store path] to a [derivation] and an [output] name.
+  Not to be confused with [derivation path].
 
 - [deriver]{#gloss-deriver}
 
-  The [store derivation] that produced an [output path].
+  The [derivation] that produced an [output path].
 
   The deriver for an output path can be queried with the `--deriver` option to
   [`nix-store --query`](@docroot@/command-ref/nix-store/query.md).