From 4c94db9899626b42d8d3e7667d36002c076b23d2 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 18 Nov 2022 11:42:31 +0100
Subject: [PATCH] define "build"

describing what we mean by building simplifies the definition of
a derivation (in the Nix language) to what it actually is: an attribute
set as produced by `derivation`.
---
 doc/manual/src/glossary.md | 41 +++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 7ab54e61d92..e8a8ac27e53 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -1,14 +1,45 @@
 # Glossary
 
   - [derivation]{#gloss-derivation}\
-    A description of a build task. 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 *store derivations* (implicitly by
-    `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
+    A [build] task declared in the [Nix language](./language/index.md) using the built-in function [`derivation`](language/derivations.md).
 
     [derivation]: #gloss-derivation
 
+  - [build]{#gloss-build}\
+    Produce a [store object].
+
+    See [`nix-build`](./command-ref/nix-build.md).
+
+    See [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental).
+
+    Nix uses a two-stage build process:
+    A Nix expression that evaluates to a [derivation] is [instantiate]d to a [store derivation], which is then [realise]d to a [store object].
+
+    ```
+    +--------------------+
+    | Nix language       |
+    | .----------------. |
+    | | Nix expression | |
+    | '----------------' |
+    |         |          |
+    |      evaluate      |
+    |         |          |             +------------------------+
+    |         V          |             | Nix store              |
+    |   .------------.   |             |  .------------------.  |
+    |   | derivation |---|-instantiate-|->| store derivation |  |
+    |   '------------'   |             |  '------------------'  |
+    +--------------------+             |           |            |
+                                       |        realise         |
+                                       |           |            |
+                                       |           V            |
+                                       |    .--------------.    |
+                                       |    | store object |    |
+                                       |    '--------------'    |
+                                       +------------------------+
+    ```
+
+    [build]: #gloss-build
+
   - [store derivation]{#gloss-store-derivation}\
     A [derivation] represented as a `.drv` file in the [store].
     It has a [store path], like any [store object].