WIP document derivations and deriving paths

And get rid of "store derivation" nonsense.

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

doc/manual/source/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/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
+  values on standard output.
-  takes place.
+  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/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]:
+- If the path leads to a [derivation]:
-  1. If it is not [valid], substitute the store derivation file itself.
+  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,26 @@
 
 - [derivation]{#gloss-derivation}
 
-  A description of a build task. The result of a derivation is a
+  A single build task.
-  store object. Derivations declared in Nix expressions are specified
+  See [Derivation](@docroot@/doc/manual/src/store/drv.md#Derivation) for details.
-  using the [`derivation` primitive](./language/derivations.md). These are
-  translated into low-level *store derivations* (implicitly by
-  `nix-build`, or explicitly by `nix-instantiate`).
 
   [derivation]: #gloss-derivation
 
-- [store derivation]{#gloss-store-derivation}
+- [derivation expression]{#gloss-derivation}
 
-  A [derivation] represented as a `.drv` file in the [store].
+  A description of a [derivation] in the Nix language.
-  It has a [store path], like any [store object].
+  The result of a derivation is a store object.
-  It is the [instantiated][instantiate] form of a derivation.
+  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`
+  [derivation expression]: #gloss-derivation-expression
-
-  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
 
 - [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/source/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/source/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/source/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/source/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:
 

doc/manual/source/release-notes/rl-0.8.md

@@ -39,29 +39,29 @@ Nix 0.8 has the following improvements:
     notion of “closure store expressions” is gone (and so is the notion
     of “successors”); the file system references of a store path are now
     just stored in the database.
-    
+
     For instance, given any store path, you can query its closure:
-    
+
         $ nix-store -qR $(which firefox)
         ... lots of paths ...
-    
+
     Also, Nix now remembers for each store path the derivation that
     built it (the “deriver”):
-    
+
         $ nix-store -qR $(which firefox)
         /nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv
-    
+
     So to see the build-time dependencies, you can do
-    
+
         $ nix-store -qR $(nix-store -qd $(which firefox))
-    
+
     or, in a nicer format:
-    
+
         $ nix-store -q --tree $(nix-store -qd $(which firefox))
-    
+
     File system references are also stored in reverse. For instance, you
     can query all paths that directly or indirectly use a certain Glibc:
-    
+
         $ nix-store -q --referrers-closure \
             /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
 
@@ -92,28 +92,28 @@ Nix 0.8 has the following improvements:
   - `nix-channel` has new operations `--list` and `--remove`.
 
   - New ways of installing components into user environments:
-    
+
       - Copy from another user environment:
-        
+
             $ nix-env -i --from-profile .../other-profile firefox
-    
+
-      - Install a store derivation directly (bypassing the Nix
+      - Install a derivation directly (bypassing the Nix
         expression language entirely):
-        
+
             $ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv
-        
+
         (This is used to implement `nix-install-package`, which is
         therefore immune to evolution in the Nix expression language.)
-    
+
       - Install an already built store path directly:
-        
+
             $ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1
-    
+
       - Install the result of a Nix expression specified as a
         command-line argument:
-        
+
             $ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'
-        
+
         The difference with the normal installation mode is that `-E`
         does not use the `name` attributes of derivations. Therefore,
         this can be used to disambiguate multiple derivations with the
@@ -127,7 +127,7 @@ Nix 0.8 has the following improvements:
   - Implemented a concurrent garbage collector. It is now always safe to
     run the garbage collector, even if other Nix operations are
     happening simultaneously.
-    
+
     However, there can still be GC races if you use `nix-instantiate`
     and `nix-store
                     --realise` directly to build things. To prevent races, use the
@@ -147,13 +147,13 @@ Nix 0.8 has the following improvements:
 
   - The behaviour of the garbage collector can be changed globally by
     setting options in `/nix/etc/nix/nix.conf`.
-    
+
       - `gc-keep-derivations` specifies whether deriver links should be
         followed when searching for live paths.
-    
+
       - `gc-keep-outputs` specifies whether outputs of derivations
         should be followed when searching for live paths.
-    
+
       - `env-keep-derivations` specifies whether user environments
         should store the paths of derivations when they are added (thus
         keeping the derivations alive).

doc/manual/source/release-notes/rl-2.0.md

@@ -8,13 +8,13 @@ The following incompatible changes have been made:
     It has been superseded by the binary cache substituter mechanism
     since several years. As a result, the following programs have been
     removed:
-    
+
       - `nix-pull`
-    
+
       - `nix-generate-patches`
-    
+
       - `bsdiff`
-    
+
       - `bspatch`
 
   - The “copy from other stores” substituter mechanism
@@ -58,26 +58,26 @@ This release has the following new features:
     `nix-build`, `nix-shell -p`, `nix-env -qa`, `nix-instantiate
     --eval`, `nix-push` and `nix-copy-closure`. It has the following
     major features:
-    
+
       - Unlike the legacy commands, it has a consistent way to refer to
         packages and package-like arguments (like store paths). For
         example, the following commands all copy the GNU Hello package
         to a remote machine:
-        
+
             nix copy --to ssh://machine nixpkgs.hello
-        
+
             nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
-        
+
             nix copy --to ssh://machine '(with import <nixpkgs> {}; hello)'
-        
+
         By contrast, `nix-copy-closure` only accepted store paths as
         arguments.
-    
+
       - It is self-documenting: `--help` shows all available
         command-line arguments. If `--help` is given after a subcommand,
         it shows examples for that subcommand. `nix
                                                                         --help-config` shows all configuration options.
-    
+
       - It is much less verbose. By default, it displays a single-line
         progress indicator that shows how many packages are left to be
         built or downloaded, and (if there are running builds) the most
@@ -85,7 +85,7 @@ This release has the following new features:
         last few lines of builder output. The full build log can be
         retrieved using `nix
                                                                         log`.
-    
+
       - It
         [provides](https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba)
         all `nix.conf` configuration options as command line flags. For
@@ -93,122 +93,122 @@ This release has the following new features:
                                                                         http-connections 100` you can write `--http-connections 100`.
         Boolean options can be written as `--foo` or `--no-foo` (e.g.
         `--no-auto-optimise-store`).
-    
+
       - Many subcommands have a `--json` flag to write results to stdout
         in JSON format.
-    
+
     > **Warning**
-    > 
+    >
     > Please note that the `nix` command is a work in progress and the
     > interface is subject to change.
-    
+
     It provides the following high-level (“porcelain”) subcommands:
-    
+
       - `nix build` is a replacement for `nix-build`.
-    
+
       - `nix run` executes a command in an environment in which the
         specified packages are available. It is (roughly) a replacement
         for `nix-shell
                                                                         -p`. Unlike that command, it does not execute the command in a
         shell, and has a flag (`-c`) that specifies the unquoted command
         line to be executed.
-        
+
         It is particularly useful in conjunction with chroot stores,
         allowing Linux users who do not have permission to install Nix
         in `/nix/store` to still use binary substitutes that assume
         `/nix/store`. For example,
-        
+
             nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!'
-        
+
         downloads (or if not substitutes are available, builds) the GNU
         Hello package into `~/my-nix/nix/store`, then runs `hello` in a
         mount namespace where `~/my-nix/nix/store` is mounted onto
         `/nix/store`.
-    
+
       - `nix search` replaces `nix-env
                                                                         -qa`. It searches the available packages for occurrences of a
         search string in the attribute name, package name or
         description. Unlike `nix-env -qa`, it has a cache to speed up
         subsequent searches.
-    
+
       - `nix copy` copies paths between arbitrary Nix stores,
         generalising `nix-copy-closure` and `nix-push`.
-    
+
       - `nix repl` replaces the external program `nix-repl`. It provides
         an interactive environment for evaluating and building Nix
         expressions. Note that it uses `linenoise-ng` instead of GNU
         Readline.
-    
+
       - `nix upgrade-nix` upgrades Nix to the latest stable version.
         This requires that Nix is installed in a profile. (Thus it won’t
         work on NixOS, or if it’s installed outside of the Nix store.)
-    
+
       - `nix verify` checks whether store paths are unmodified and/or
         “trusted” (see below). It replaces `nix-store --verify` and
         `nix-store
                                                                         --verify-path`.
-    
+
       - `nix log` shows the build log of a package or path. If the
         build log is not available locally, it will try to obtain it
         from the configured substituters (such as
         [cache.nixos.org](https://cache.nixos.org/), which now
         provides build logs).
-    
+
       - `nix edit` opens the source code of a package in your editor.
-    
+
       - `nix eval` replaces `nix-instantiate --eval`.
-    
+
       - `nix
                                                                         why-depends` shows why one store path has another in its
         closure. This is primarily useful to finding the causes of
         closure bloat. For example,
-        
+
             nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev
-        
+
         shows a chain of files and fragments of file contents that cause
         the VLC package to have the “dev” output of `libdrm` in its
         closure — an undesirable situation.
-    
+
       - `nix path-info` shows information about store paths, replacing
         `nix-store -q`. A useful feature is the option `--closure-size`
         (`-S`). For example, the following command show the closure
         sizes of every path in the current NixOS system closure, sorted
         by size:
-        
+
             nix path-info -rS /run/current-system | sort -nk2
-    
+
       - `nix optimise-store` replaces `nix-store --optimise`. The main
         difference is that it has a progress indicator.
-    
+
     A number of low-level (“plumbing”) commands are also available:
-    
+
       - `nix ls-store` and `nix
                                                                         ls-nar` list the contents of a store path or NAR file. The
         former is primarily useful in conjunction with remote stores,
         e.g.
-        
+
             nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
-        
+
         lists the contents of path in a binary cache.
-    
+
       - `nix cat-store` and `nix
                                                                         cat-nar` allow extracting a file from a store path or NAR file.
-    
+
       - `nix dump-path` writes the contents of a store path to stdout in
         NAR format. This replaces `nix-store --dump`.
-    
+
       - `nix
-                                                                        show-derivation` displays a store derivation in JSON format.
+                                                                        show-derivation` displays a derivation in JSON format.
         This is an alternative to `pp-aterm`.
-    
+
       - `nix
                                                                         add-to-store` replaces `nix-store
                                                                         --add`.
-    
+
       - `nix sign-paths` signs store paths.
-    
+
       - `nix copy-sigs` copies signatures from one store to another.
-    
+
       - `nix show-config` shows all configuration options and their
         current values.
 
@@ -224,11 +224,11 @@ This release has the following new features:
     `nix-copy-closure`, `nix-push` and substitution are all instances
     of the general notion of copying paths between different kinds of
     Nix stores.
-    
+
     Stores are specified using an URI-like syntax, e.g.
     <https://cache.nixos.org/> or <ssh://machine>. The following store
     types are supported:
-    
+
       - `LocalStore` (stori URI `local` or an absolute path) and the
         misnamed `RemoteStore` (`daemon`) provide access to a local Nix
         store, the latter via the Nix daemon. You can use `auto` or the
@@ -236,63 +236,63 @@ This release has the following new features:
         whether you have write permission to the Nix store. It is no
         longer necessary to set the `NIX_REMOTE` environment variable to
         use the Nix daemon.
-        
+
         As noted above, `LocalStore` now supports chroot builds,
         allowing the “physical” location of the Nix store (e.g.
         `/home/alice/nix/store`) to differ from its “logical” location
         (typically `/nix/store`). This allows non-root users to use Nix
         while still getting the benefits from prebuilt binaries from
         [cache.nixos.org](https://cache.nixos.org/).
-    
+
       - `BinaryCacheStore` is the abstract superclass of all binary
         cache stores. It supports writing build logs and NAR content
         listings in JSON format.
-    
+
       - `HttpBinaryCacheStore` (`http://`, `https://`) supports binary
         caches via HTTP or HTTPS. If the server supports `PUT` requests,
         it supports uploading store paths via commands such as `nix
                                                                         copy`.
-    
+
       - `LocalBinaryCacheStore` (`file://`) supports binary caches in
         the local filesystem.
-    
+
       - `S3BinaryCacheStore` (`s3://`) supports binary caches stored in
         Amazon S3, if enabled at compile time.
-    
+
       - `LegacySSHStore` (`ssh://`) is used to implement remote builds
         and `nix-copy-closure`.
-    
+
       - `SSHStore` (`ssh-ng://`) supports arbitrary Nix operations on a
         remote machine via the same protocol used by `nix-daemon`.
 
   - Security has been improved in various ways:
-    
+
       - Nix now stores signatures for local store paths. When paths are
         copied between stores (e.g., copied from a binary cache to a
         local store), signatures are propagated.
-        
+
         Locally-built paths are signed automatically using the secret
         keys specified by the `secret-key-files` store option.
         Secret/public key pairs can be generated using `nix-store
                                                                         --generate-binary-cache-key`.
-        
+
         In addition, locally-built store paths are marked as “ultimately
         trusted”, but this bit is not propagated when paths are copied
         between stores.
-    
+
       - Content-addressable store paths no longer require signatures —
         they can be imported into a store by unprivileged users even if
         they lack signatures.
-    
+
       - The command `nix verify` checks whether the specified paths are
         trusted, i.e., have a certain number of trusted signatures, are
         ultimately trusted, or are content-addressed.
-    
+
       - Substitutions from binary caches
         [now](https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b)
         require signatures by default. This was already the case on
         NixOS.
-    
+
       - In Linux sandbox builds, we
         [now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b)
         use `/build` instead of `/tmp` as the temporary build directory.
@@ -309,7 +309,7 @@ This release has the following new features:
     hash or commit hash is specified. For example, calls to
     `builtins.fetchGit` are only allowed if a `rev` attribute is
     specified.
-    
+
     The goal of this feature is to enable true reproducibility and
     traceability of builds (including NixOS system configurations) at
     the evaluation level. For example, in the future, `nixos-rebuild`
@@ -367,21 +367,21 @@ This release has the following new features:
     log will be shown if a build fails.
 
   - Networking has been improved:
-    
+
       - HTTP/2 is now supported. This makes binary cache lookups [much
         more
         efficient](https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92).
-    
+
       - We now retry downloads on many HTTP errors, making binary caches
         substituters more resilient to temporary failures.
-    
+
       - HTTP credentials can now be configured via the standard `netrc`
         mechanism.
-    
+
       - If S3 support is enabled at compile time, <s3://> URIs are
         [supported](https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b)
         in all places where Nix allows URIs.
-    
+
       - Brotli compression is now supported. In particular,
         [cache.nixos.org](https://cache.nixos.org/) build logs are now compressed
         using Brotli.
@@ -431,9 +431,9 @@ The Nix language has the following new features:
   - Derivation attributes can now reference the outputs of the
     derivation using the `placeholder` builtin function. For example,
     the attribute
-    
+
         configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}";
-    
+
     will cause the `configureFlags` environment variable to contain the
     actual store paths corresponding to the `out` and `dev` outputs.
 
@@ -444,7 +444,7 @@ The following builtin functions are new or extended:
     Nixpkgs, which fetches at build time and cannot be used to fetch Nix
     expressions during evaluation. A typical use case is to import
     external NixOS modules from your configuration, e.g.
-    
+
         imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ];
 
   - Similarly, `builtins.fetchMercurial` allows you to fetch Mercurial
@@ -485,7 +485,7 @@ The Nix build environment has the following changes:
     builder via the file `.attrs.json` in the builder’s temporary
     directory. This obviates the need for `passAsFile` since JSON files
     have no size restrictions, unlike process environments.
-    
+
     [As a convenience to Bash
     builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699),
     Nix writes a script named `.attrs.sh` to the builder’s directory

doc/manual/source/release-notes/rl-2.13.md

@@ -22,7 +22,7 @@
   accurate error locations. A short excerpt of the trace is now shown by
   default when an error occurs.
 
-* Allow explicitly selecting outputs in a store derivation installable, just like we can do with other sorts of installables.
+* Allow explicitly selecting outputs in a derivation installable, just like we can do with other sorts of installables.
   For example,
   ```shell-session
   # nix build /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^dev

doc/manual/source/release-notes/rl-2.15.md

@@ -11,7 +11,7 @@
   As the choice of hash formats is no longer binary, the `--base16` flag is also added
   to explicitly specify the Base16 format, which is still the default.
 
-* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [store derivation](@docroot@/glossary.md#gloss-store-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
+* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [derivation](@docroot@/glossary.md#gloss-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
 
   The new `^` syntax for store paths introduced in Nix 2.13 allows explicitly referencing output paths of a derivation.
   Using this is better and more clear than relying on the now-removed `.drv` special handling.

doc/manual/source/store/drv.md

@@ -0,0 +1,172 @@
+# Derivation and Deriving Path
+
+So far, we have covered "inert" store objects.
+But the point of the Nix store layer is to be a build system.
+Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
+
+This is where Nix distinguishes itself.
+*Derivations* represent individual build steps, and *deriving paths* are needed to to the *outputs* of those build steps.
+The two concepts need to be introduced together because, as described below, each depends on the other.
+
+## Derivation
+
+What is natural Unix analog for a build step *in action*?
+Answer: a process that will eventually exit, leaving behind some output date.
+What is the natural way to *plan* such a step?
+An `execve` system call.
+
+A derivation consists of:
+
+ - A (base) name
+
+ - A set of *outputs*, consisting of names and possibly other data
+
+ - A set of *inputs*, a set of deriving paths
+
+ - Everything needed for an `execve` system call:
+   1. Path to executable
+   2. A list of arguments (except for `argv[0]`, which is taken from the path in the usual way)
+   3. A set of environment variables.
+
+ - A two-component "system" name (e.g. `x86_64-linux`) where the executable is to run.
+
+The path and list/set elements of the other two will presumably consist wholly or partly of store paths.
+But just as we stored the references contained in the file data separately for store objects, so we store the set of inputs separately.
+
+The last bit of information is to take advantage of the fact that Nix allows *heterogenous* build plans, were not all steps can be run on the same machine or same sort of machine.
+
+The process's job is to produce the outputs, but have no other important side effects.
+The rules around this will be discussed in following sections.
+
+### Output name
+
+Most outputs are named `drv.name + '-' + outputName`.
+However, an output named "out" is just has name `drv.name`.
+This is to allow derivations with a single output to avoid a superfluous `-<outputName>` in their single output's name when no disambiguation is needed.
+
+### Placeholder
+
+TODO
+
+### Referencing
+
+Derivations are always referred to by the store path of the store object they are encoded to.
+The store path name is the derivation name with `.drv` suffixed at the end.
+The store path digest we will explain in a following section after we go over the different variants of derivations, as the exact algorithm depends on them.
+Suffice to say for now, it is (a form of) content addressing based on the derivation and its inputs.
+
+## Deriving path
+
+Deriving references are close to their abstract version, but using `StorePath` as the type of all references, matching the end of the previous subsection.
+
+In pseudo code:
+
+```idris
+type OutputName = String
+
+data DerivingPath
+  = ConstantPath { path : StorePath }
+  | Output {
+      drv    : StorePath,
+      output : OutputName,
+    }
+```
+
+## Encoding
+
+### Derivation
+
+- The name is not encoded, because we can just get it from the store object!
+
+:::{.note}
+Brief amusing history of PP-ATerm
+:::
+
+#### `inputSrcs` vs `inputDrvs`
+
+### Deriving Path
+
+Constant deriving paths are encoded simply as the underlying store path is.
+Thus, we see that every encoded store path is also a valid encoded (constant) deriving path.
+
+Output deriving paths are encoded by
+
+- encoding of a store path referring to a derivation
+
+- a separator (`^` or `!` depending on context)
+
+- the name of an output
+
+An example would be:
+
+```
+/nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^out
+```
+
+This parses like so:
+
+```
+/nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^out
+|------------------------------------------------------------| |-|
+store path (usual encoding)                                    output name
+                                                          |--|
+                                                          note the ".drv"
+```
+
+## Extending the model to be higher-order
+
+**Experimental feature**: [`dynamic-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations)
+
+We can apply the same extension discussed for the abstract model to the concrete model.
+Again, only the data type for Deriving Paths needs to be modified.
+Derivations are the same except for using the new extended deriving path data type.
+
+```idris
+type OutputName = String
+
+data DerivingPath
+  = ConstantPath { storeObj : StorePath }
+  | Output {
+      drv    : DerivingPath, -- changed
+      output : OutputName,
+    }
+```
+
+Now, the `drv` field of `BuiltObject` is itself a `DerivingPath` instead of an `StorePath`.
+
+Under this extended model, `DerivingPath`s are thus inductively built up from an `ConstantPath`, contains in 0 or more outer `Outputs`.
+
+### Encoding
+
+The encoding is adjusted in a very simplest way, merely displaying the same
+
+```
+/nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^foo.drv^bar.drv^out
+|----------------------------------------------------------------------------| |-|
+inner deriving path (usual encoding)                                           output name
+|--------------------------------------------------------------------| |-----|
+even more inner deriving path (usual encoding)                         output name
+|------------------------------------------------------------| |-----|
+innermost constant store path (usual encoding)                 output name
+```
+
+## Extra extensions
+
+### `__structuredAttrs`
+
+Historically speaking, most users of Nix made GNU Bash with a script the command run, regardless of what they were doing.
+Bash variable are automatically created from env vars, but bash also supports array and string-keyed map variables in addition to string variables.
+People also usually create derivations using language which also support these richer data types.
+It was thus desired a way to get this data from the language "planning" the derivation to language to bash, the language evaluated at "run time".
+
+`__structuredAttrs` does this by smuggling inside the core derivation format a map of named richer data.
+At run time, this becomes two things:
+
+1. A JSON file containing that map.
+2. A bash script setting those variables.
+
+The bash command can be passed a script which will "source" that Nix-created bash script, setting those variables with the richer data.
+The outer script can then do whatever it likes with those richer variables as input.
+
+However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers.
+We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer.

src/libcmd/command.cc

@@ -144,7 +144,7 @@ MixOperateOnOptions::MixOperateOnOptions()
     addFlag({
         .longName = "derivation",
         .description =
-            "Operate on the [store derivation](@docroot@/glossary.md#gloss-store-derivation) rather than its outputs.",
+            "Operate on the [derivation](@docroot@/glossary.md#gloss-derivation) rather than its outputs.",
         .category = installablesCategory,
         .handler = {&operateOn, OperateOn::Derivation},
     });

src/libcmd/installables.hh

@@ -24,7 +24,7 @@ enum class Realise {
     /**
      * Don't build the derivation.
      *
-     * Postcondition: the store derivation exists.
+     * Postcondition: the derivation exists.
      */
     Derivation,
     /**

src/libexpr/eval-cache.cc

@@ -777,7 +777,7 @@ StorePath AttrCursor::forceDerivation()
            been garbage-collected. So force it to be regenerated. */
         aDrvPath->forceValue();
         if (!root->state.store->isValidPath(drvPath))
-            throw Error("don't know how to recreate store derivation '%s'!",
+            throw Error("don't know how to recreate derivation '%s'!",
                 root->state.store->printStorePath(drvPath));
     }
     return drvPath;

src/libexpr/primops.cc

@@ -1505,7 +1505,7 @@ static void derivationStrictInternal(
     }
 
     else {
-        /* Compute a hash over the "masked" store derivation, which is
+        /* Compute a hash over the "masked" derivation, which is
            the final one except that in the list of outputs, the
            output paths are empty strings, and the corresponding
            environment variables have an empty value.  This ensures
@@ -1551,7 +1551,7 @@ static void derivationStrictInternal(
     printMsg(lvlChatty, "instantiated '%1%' -> '%2%'", drvName, drvPathS);
 
     /* Optimisation, but required in read-only mode! because in that
-       case we don't actually write store derivations, so we can't
+       case we don't actually write derivations, so we can't
        read them later. */
     {
         auto h = hashDerivationModulo(*state.store, drv, false);

src/libexpr/primops/context.cc

@@ -236,7 +236,7 @@ static RegisterPrimOp primop_getContext({
       Return the string context of *s*.
 
       The string context tracks references to derivations within a string.
-      It is represented as an attribute set of [store derivation](@docroot@/glossary.md#gloss-store-derivation) paths mapping to output names.
+      It is represented as an attribute set of [derivation](@docroot@/glossary.md#gloss-derivation) paths mapping to output names.
 
       Using [string interpolation](@docroot@/language/string-interpolation.md) on a derivation will add that derivation to the string context.
       For example,

src/nix/derivation-add.cc

@@ -14,7 +14,7 @@ struct CmdAddDerivation : MixDryRun, StoreCommand
 {
     std::string description() override
     {
-        return "Add a store derivation";
+        return "Add a derivation";
     }
 
     std::string doc() override

src/nix/derivation-add.md

@@ -3,17 +3,16 @@ R""(
 # Description
 
 This command reads from standard input a JSON representation of a
-[store derivation].
+[derivation].
 
 Store derivations are used internally by Nix. They are store paths with
 extension `.drv` that represent the build-time dependency graph to which
 a Nix expression evaluates.
 
-
+[derivation]: @docroot@/glossary.md#gloss-derivation
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
 
 `nix derivation add` takes a single derivation in the following format:
 
-{{#include ../../protocols/json/derivation.md}}
+{{#include @docroot@/protocols/json/derivation.md}}
 
 )""

src/nix/derivation-show.cc

@@ -1,5 +1,4 @@
-// FIXME: integrate this with nix path-info?
+// FIXME: integrate this with `nix path-info`?
-// FIXME: rename to 'nix store derivation show' or 'nix debug derivation show'?
 
 #include "command.hh"
 #include "common-args.hh"
@@ -27,7 +26,7 @@ struct CmdShowDerivation : InstallablesCommand
 
     std::string description() override
     {
-        return "show the contents of a store derivation";
+        return "show the contents of a derivation";
     }
 
     std::string doc() override

src/nix/derivation-show.md

@@ -2,7 +2,7 @@ R""(
 
 # Examples
 
-* Show the [store derivation] that results from evaluating the Hello
+* Show the [derivation] that results from evaluating the Hello
   package:
 
   ```console
@@ -37,7 +37,7 @@ R""(
 # Description
 
 This command prints on standard output a JSON representation of the
-[store derivation]s to which [*installables*](./nix.md#installables) evaluate.
+[derivation]s to which [*installables*](./nix.md#installables) evaluate.
 
 Store derivations are used internally by Nix. They are store paths with
 extension `.drv` that represent the build-time dependency graph to which
@@ -46,7 +46,7 @@ a Nix expression evaluates.
 By default, this command only shows top-level derivations, but with
 `--recursive`, it also shows their dependencies.
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[derivation]: ../../glossary.md#gloss-derivation
 
 `nix derivation show` outputs a JSON map of [store path]s to derivations in the following format:
 

src/nix/nix.md

@@ -144,11 +144,11 @@ Example: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
 
 These are paths inside the Nix store, or symlinks that resolve to a path in the Nix store.
 
-A [store derivation] is also addressed by store path.
+A [derivation] is also addressed by store path.
 
 Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
 
-If you want to refer to an output path of that store derivation, add the output name preceded by a caret (`^`).
+If you want to refer to an output path of that derivation, add the output name preceded by a caret (`^`).
 
 Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^out`
 
@@ -244,10 +244,10 @@ operate are determined as follows:
   a command like `nix shell nixpkgs#libxml2` will provide only those
   two outputs by default.
 
-  Note that a [store derivation] (given by its `.drv` file store path) doesn't have
+  Note that a [derivation] (given by its `.drv` file store path) doesn't have
   any attributes like `meta`, and thus this case doesn't apply to it.
 
-  [store derivation]: @docroot@/glossary.md#gloss-store-derivation
+  [derivation]: @docroot@/glossary.md#gloss-derivation
 
 * Otherwise, Nix will use all outputs of the derivation.
 

src/nix/path-info.md

@@ -68,9 +68,9 @@ R""(
   ]
   ```
 
-* Print the path of the [store derivation] produced by `nixpkgs#hello`:
+* Print the path of the [derivation] produced by `nixpkgs#hello`:
 
-  [store derivation]: @docroot@/glossary.md#gloss-store-derivation
+  [derivation]: @docroot@/glossary.md#gloss-derivation
 
   ```console
   # nix path-info --derivation nixpkgs#hello

src/nix/search.md

@@ -62,8 +62,8 @@ R""(
 
 # Description
 
-`nix search` searches [*installable*](./nix.md#installables) (which can be evaluated, that is, a
+`nix search` searches [*installable*](./nix.md#installables) that 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
+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

src/nix/store-copy-log.md

@@ -18,9 +18,9 @@ R""(
   (The flag `--substituters ''` avoids querying
   `https://cache.nixos.org` for the log.)
 
-* To copy the log for a specific [store derivation] via SSH:
+* To copy the log for a specific [derivation] via SSH:
 
-  [store derivation]: @docroot@/glossary.md#gloss-store-derivation
+  [derivation]: @docroot@/glossary.md#gloss--derivation
 
   ```console
   # nix store copy-log --to ssh-ng://machine /nix/store/ilgm50plpmcgjhcp33z6n4qbnpqfhxym-glibc-2.33-59.drv