Skip to content

glossary: re-introduce "derivation" #12994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 26, 2025
Merged

glossary: re-introduce "derivation" #12994

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8db8371
glossary: re-introduce "derivation"
fricklerhandwerk Apr 10, 2025
82d5982
don't emphasize 'store derivation'
fricklerhandwerk Apr 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions doc/manual/source/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,22 @@

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.
Copy link
Member

@Ericson2314 Ericson2314 May 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not true because a function maps many possible arguments to results (many possible inputs) but a derivation has a specific set of inputs.

A derivation that depends on the outputs of another derivation is closer to being a function, because we don't know what those outputs are at the time of creating the derivation, but even this needs more explaining.

I think it would be better to say a derivation is a function application than a function. since it is applying a function-in-our-heads to some inputs.


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).
Comment on lines +38 to +39
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see why need this text here. These details can go in the chapter on derivations. The glossary entry is supposed to be an extremely short description that links to the chapter.


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.
Comment on lines 46 to 50
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not how "store derivation" is defined in that chapter. Rather the thing the glossary now calls "derivation" (the abstract concept) is called "store derivation".

We need to make things consistent. I would rather just always say "derivation" and drop the "store " part everywhere, but I am open to other options.


[store derivation]: #gloss-store-derivation
Expand All @@ -50,10 +63,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

Expand Down
2 changes: 1 addition & 1 deletion doc/manual/source/language/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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**
>
Expand Down
Loading