WIP document derivations and deriving paths

And get rid of "store derivation" nonsense.

doc/manual/src/SUMMARY.md.in

@@ -22,6 +22,7 @@
   - [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)
   - [Store Types](store/types/index.md)
 {{#include ./store/types/SUMMARY.md}}
 - [Nix Language](language/index.md)

doc/manual/src/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/src/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-store-derivation
 
 - `--use-substitutes` / `-s`
 

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

@@ -25,7 +25,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
 
@@ -61,9 +61,9 @@ The arguments *args* map to store paths in a number of possible ways:
   The derivations returned by those function calls are installed.
   This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name.
 
-- 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.
@@ -193,7 +193,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/src/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/src/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 discarded.
 
   > **Warning**
   >
@@ -128,7 +128,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/src/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/src/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/src/glossary.md

@@ -21,31 +21,26 @@
 
 - [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@/doc/manual/src/store/drv.md#Derivation) for details.
 
   [derivation]: #gloss-derivation
 
-- [store derivation]{#gloss-store-derivation}
+- [derivation expression]{#gloss-derivation}
 
-  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 description of a [derivation] in the Nix language.
+  The result of a derivation is a store object.
+  Derivations are typically specified in Nix expressions using the [`derivation` primitive](./language/derivations.md).
+  These are translated into low-level *derivations* (implicitly by
+  `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
-  Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
-
-  See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
-
-  [store derivation]: #gloss-store-derivation
+  [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 +183,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**
@@ -257,7 +252,7 @@
 
 - [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).

doc/manual/src/language/derivations.md

@@ -4,9 +4,9 @@ The most important built-in function is `derivation`, which is used to describe
 a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths.
 
 It takes as input an attribute set, the attributes of which specify the inputs to the process.
-It outputs an attribute set, and produces a [store derivation] as a side effect of evaluation.
+It outputs an attribute set, and produces a [derivation] as a side effect of evaluation.
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[derivation]: @docroot@/glossary.md#gloss-derivation
 
 ## Input attributes
 
@@ -15,7 +15,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
 - [`name`]{#attr-name} ([String](@docroot@/language/types.md#type-string))
 
   A symbolic name for the derivation.
-  It is added to the [store path] of the corresponding [store derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path).
+  It is added to the [store path] of the corresponding [derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path).
 
   [store path]: @docroot@/store/store-path.md
 
@@ -28,7 +28,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
   > }
   > ```
   >
-  > The store derivation's path will be `/nix/store/<hash>-hello.drv`.
+  > The derivation's path will be `/nix/store/<hash>-hello.drv`.
   > The [output](#attr-outputs) paths will be of the form `/nix/store/<hash>-hello[-<output>]`
 
 - [`system`]{#attr-system} ([String](@docroot@/language/types.md#type-string))
@@ -182,7 +182,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
   > }
   > ```
   >
-  > The store derivation path will be `/nix/store/<hash>-example.drv`.
+  > The derivation path will be `/nix/store/<hash>-example.drv`.
   > The output paths will be
   > - `/nix/store/<hash>-example-lib`
   > - `/nix/store/<hash>-example-dev`

doc/manual/src/language/import-from-derivation.md

@@ -71,9 +71,10 @@ Boxes are data structures, arrow labels are transformations.
 |       evaluate       |             |                        |
 |          |           |             |                        |
 |          V           |             |                        |
-|    .------------.    |             |  .------------------.  |
-|    | derivation |----|-instantiate-|->| store derivation |  |
-|    '------------'    |             |  '------------------'  |
+|    .------------.    |             |                        |
+|    | derivation |    |             |     .------------.     |
+|    | expression |----|-instantiate-|---->| derivation |     |
+|    '------------'    |             |     '------------'     |
 |                      |             |           |            |
 |                      |             |        realise         |
 |                      |             |           |            |

doc/manual/src/language/string-interpolation.md

@@ -22,7 +22,7 @@ Rather than writing
 "--with-freetype2-library=" + freetype + "/lib"
 ```
 
-(where `freetype` is a [derivation]), you can instead write
+(where `freetype` is an [output path]), you can instead write
 
 [derivation]: @docroot@/glossary.md#gloss-derivation
 
@@ -148,7 +148,7 @@ An expression that is interpolated must evaluate to one of the following:
   - `__toString` must be a function that takes the attribute set itself and returns a string
   - `outPath` must be a string
 
-  This includes [derivations](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental).
+  This includes [derivation expressions](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental).
 
 A string interpolates to itself.
 

doc/manual/src/protocols/derivation-aterm.md

@@ -1,6 +1,6 @@
 # Derivation "ATerm" file format
 
-For historical reasons, [derivations](@docroot@/glossary.md#gloss-store-derivation) are stored on-disk in [ATerm](https://homepages.cwi.nl/~daybuild/daily-books/technology/aterm-guide/aterm-guide.html) format.
+For historical reasons, [derivations](@docroot@/glossary.md#gloss-derivation) are stored on-disk in [ATerm](https://homepages.cwi.nl/~daybuild/daily-books/technology/aterm-guide/aterm-guide.html) format.
 
 Derivations are serialised in one of the following formats: