mirror of
https://github.com/NixOS/nix.git
synced 2024-11-21 22:32:26 +00:00
WIP document derivations and deriving paths
And get rid of "store derivation" nonsense.
This commit is contained in:
John Ericson
parent
7ebeceaf3d
commit
a654cc2a72
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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`
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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`
|
||||
|
||||
|
||||
@ -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
|
||||
takes place.
|
||||
values on standard output.
|
||||
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)
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -11,10 +11,10 @@
|
||||
|
||||
Each of *paths* is processed as follows:
|
||||
|
||||
- If the path leads to a [store derivation]:
|
||||
1. If it is not [valid], substitute the store derivation file itself.
|
||||
- If the path leads to a [derivation]:
|
||||
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
|
||||
|
||||
@ -21,31 +21,26 @@
|
||||
|
||||
- [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`).
|
||||
A single build task.
|
||||
See [Derivation](@docroot@/doc/manual/src/store/drv.md#Derivation) for details.
|
||||
|
||||
[derivation]: #gloss-derivation
|
||||
|
||||
- [store derivation]{#gloss-store-derivation}
|
||||
- [derivation expression]{#gloss-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.
|
||||
A description of a [derivation] in the Nix language.
|
||||
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 *derivations* (implicitly by
|
||||
`nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
|
||||
|
||||
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.
|
||||
|
||||
[store derivation]: #gloss-store-derivation
|
||||
[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 [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).
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -71,9 +71,10 @@ Boxes are data structures, arrow labels are transformations.
|
||||
| evaluate | | |
|
||||
| | | | |
|
||||
| V | | |
|
||||
| .------------. | | .------------------. |
|
||||
| | derivation |----|-instantiate-|->| store derivation | |
|
||||
| '------------' | | '------------------' |
|
||||
| .------------. | | |
|
||||
| | derivation | | | .------------. |
|
||||
| | expression |----|-instantiate-|---->| derivation | |
|
||||
| '------------' | | '------------' |
|
||||
| | | | |
|
||||
| | | realise |
|
||||
| | | | |
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -97,7 +97,7 @@ Nix 0.8 has the following improvements:
|
||||
|
||||
$ 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
|
||||
|
||||
@ -198,7 +198,7 @@ This release has the following new features:
|
||||
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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
172
doc/manual/source/store/drv.md
Normal file
172
doc/manual/source/store/drv.md
Normal file
@ -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.
|
||||
@ -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},
|
||||
});
|
||||
|
||||
@ -24,7 +24,7 @@ enum class Realise {
|
||||
/**
|
||||
* Don't build the derivation.
|
||||
*
|
||||
* Postcondition: the store derivation exists.
|
||||
* Postcondition: the derivation exists.
|
||||
*/
|
||||
Derivation,
|
||||
/**
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
|
||||
[derivation]: @docroot@/glossary.md#gloss-derivation
|
||||
|
||||
`nix derivation add` takes a single derivation in the following format:
|
||||
|
||||
{{#include ../../protocols/json/derivation.md}}
|
||||
{{#include @docroot@/protocols/json/derivation.md}}
|
||||
|
||||
)""
|
||||
|
||||
@ -1,5 +1,4 @@
|
||||
// FIXME: integrate this with nix path-info?
|
||||
// FIXME: rename to 'nix store derivation show' or 'nix debug derivation show'?
|
||||
// FIXME: integrate this with `nix path-info`?
|
||||
|
||||
#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
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -62,8 +62,8 @@ R""(
|
||||
|
||||
# Description
|
||||
|
||||
`nix search` searches [*installable*](./nix.md#installables) (which 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
|
||||
`nix search` searches [*installable*](./nix.md#installables) that can be evaluated, that is, a
|
||||
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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user