1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-06-25 02:21:16 +02:00

Document Store Derivations and Deriving Paths (#12290)

This is a big step documenting the store layer on its own, separately from the evaluator (and `builtins.derivation`).

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
This commit is contained in:
John Ericson 2025-02-09 20:30:07 -05:00 committed by GitHub
parent aa383a0b85
commit e80d333777
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
21 changed files with 614 additions and 244 deletions

View file

@ -19,31 +19,35 @@
Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object).
- [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`).
[derivation]: #gloss-derivation
- [store derivation]{#gloss-store-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.
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.
A single build task.
See [Store Derivation](@docroot@/store/drv.md#store-derivation) for details.
[store derivation]: #gloss-store-derivation
- [derivation path]{#gloss-derivation-path}
A [store path] which uniquely identifies a [store derivation].
See [Referencing Store Derivations](@docroot@/store/drv.md#derivation-path) for details.
Not to be confused with [deriving path].
[derivation path]: #gloss-derivation-path
- [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`).
[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 [store derivation].
See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
@ -55,7 +59,7 @@
This can be achieved by:
- Fetching a pre-built [store object] from a [substituter]
- Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation]
- Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [store derivation]
- Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
<!-- TODO: link [running] to build process page, #8888 -->
@ -73,7 +77,7 @@
- [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
A [derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
A [store derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
- [store]{#gloss-store}
@ -188,7 +192,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 [store derivations][store derivation].
These derivations can then be [realised][realise] to produce [outputs][output].
> **Example**
@ -230,14 +234,14 @@
- [output]{#gloss-output}
A [store object] produced by a [derivation].
A [store object] produced by a [store derivation].
See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
[output]: #gloss-output
- [output path]{#gloss-output-path}
The [store path] to the [output] of a [derivation].
The [store path] to the [output] of a [store derivation].
[output path]: #gloss-output-path
@ -246,14 +250,11 @@
- [deriving path]{#gloss-deriving-path}
Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
There are two forms:
Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
- *constant*: just a [store path]
It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
See [Deriving Path](./store/drv.md#deriving-path) for details.
- *output*: a pair of a [store path] to a [derivation] and an [output] name.
Not to be confused with [derivation path].
- [deriver]{#gloss-deriver}