From 8db8371a486ec3a074e79f6729d47c09842f01ef Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 10 Apr 2025 13:51:14 +0200 Subject: [PATCH] glossary: re-introduce "derivation" The "derivation" is one of the key concepts and captures the most distinctive aspect of Nix: that we work with a certain type data (linked files) in a certain manner (using pure functions). Here we finally arrange all the important pieces to show how they belong together, while referring to the respective reference documentation for details. This change also unbreaks downstream links to `//glossary#gloss-derivation`, which had been broken by removing the glossary entry --- doc/manual/source/glossary.md | 21 ++++++++++++++++----- doc/manual/source/language/index.md | 2 +- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md index 6a7501200..787978502 100644 --- a/doc/manual/source/glossary.md +++ b/doc/manual/source/glossary.md @@ -31,9 +31,23 @@ The industry term for storage and retrieval systems using [content addressing](#gloss-content-address). A Nix store also has [input addressing](#gloss-input-addressed-store-object), and metadata. +- [derivation]{#gloss-derivation} + + A derivation can be thought of as a [pure function](https://en.wikipedia.org/wiki/Pure_function) that produces new [store objects][store object] from existing store objects. + + Derivations are implemented as [operating system processes that run in a sandbox](@docroot@/store/building.md#builder-execution). + This sandbox by default only allows reading from store objects specified as inputs, and only allows writing to designated [outputs][output] to be [captured as store objects](@docroot@/store/building.md#processing-outputs). + How exactly to invoke such an isolated process is encoded in a [store derivation]. + + A derivation is typically specified as a [derivation expression] in the [Nix language], and [instantiated][instantiate] to a store derivation. + There are multiple ways of obtaining store objects from store derivatons, collectively called [realisation][realise]. + + [derivation]: #gloss-derivation + - [store derivation]{#gloss-store-derivation} - A single build task. + A [derivation] represented as a [store object]. + See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details. [store derivation]: #gloss-store-derivation @@ -50,10 +64,7 @@ - [derivation expression]{#gloss-derivation-expression} - A description of a [store 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`). + A description of a [store derivation] using the [`derivation` primitive](./language/derivations.md) in the [Nix language]. [derivation expression]: #gloss-derivation-expression diff --git a/doc/manual/source/language/index.md b/doc/manual/source/language/index.md index 2bfdbb8a0..b7630235a 100644 --- a/doc/manual/source/language/index.md +++ b/doc/manual/source/language/index.md @@ -1,6 +1,6 @@ # Nix Language -The Nix language is designed for conveniently creating and composing *derivations* – precise descriptions of how contents of existing files are used to derive new files. +The Nix language is designed for conveniently creating and composing [derivations](@docroot@/glossary.md#gloss-derivation) – precise descriptions of how contents of existing files are used to derive new files. > **Tip** >