mirror of
https://github.com/privatevoid-net/nix-super.git
synced 2024-11-10 08:16:15 +02:00
Merge pull request #7592 from fricklerhandwerk/nix-store-realise
reword description of how realisation works
This commit is contained in:
commit
f34484d18a
3 changed files with 26 additions and 28 deletions
|
@ -1,6 +1,6 @@
|
|||
# Name
|
||||
|
||||
`nix-store --realise` - realise specified store paths
|
||||
`nix-store --realise` - build or fetch store objects
|
||||
|
||||
# Synopsis
|
||||
|
||||
|
@ -8,33 +8,35 @@
|
|||
|
||||
# Description
|
||||
|
||||
The operation `--realise` essentially “builds” the specified store
|
||||
paths. Realisation is a somewhat overloaded term:
|
||||
|
||||
- If the store path is a *derivation*, realisation ensures that the
|
||||
output paths of the derivation are [valid] (i.e.,
|
||||
the output path and its closure exist in the file system). This
|
||||
can be done in several ways. First, it is possible that the
|
||||
outputs are already valid, in which case we are done
|
||||
immediately. Otherwise, there may be [substitutes]
|
||||
that produce the outputs (e.g., by downloading them). Finally, the
|
||||
outputs can be produced by running the build task described
|
||||
by the derivation.
|
||||
Each of *paths* is processed as follows:
|
||||
|
||||
- If the store path is not a derivation, realisation ensures that the
|
||||
specified path is valid (i.e., it and its closure exist in the file
|
||||
system). If the path is already valid, we are done immediately.
|
||||
Otherwise, the path and any missing paths in its closure may be
|
||||
produced through substitutes. If there are no (successful)
|
||||
substitutes, realisation fails.
|
||||
- If the path leads to a [store derivation]:
|
||||
1. If it is not [valid], substitute the store 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].
|
||||
- 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. This involves first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. <!-- 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.
|
||||
|
||||
[store paths]: @docroot@/glossary.md#gloss-store-path
|
||||
[valid]: @docroot@/glossary.md#gloss-validity
|
||||
[substitutes]: @docroot@/glossary.md#gloss-substitute
|
||||
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
|
||||
[output paths]: @docroot@/glossary.md#gloss-output-path
|
||||
[store objects]: @docroot@/glossary.md#gloss-store-object
|
||||
[closure]: @docroot@/glossary.md#gloss-closure
|
||||
[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
|
||||
[content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
|
||||
[Nix database]: @docroot@/glossary.md#gloss-nix-database
|
||||
|
||||
The output path of each derivation is printed on standard output. (For
|
||||
non-derivations argument, the argument itself is printed.)
|
||||
The resulting paths are printed on standard output.
|
||||
For non-derivation arguments, the argument itself is printed.
|
||||
|
||||
The following flags are available:
|
||||
{{#include ../status-build-failure.md}}
|
||||
|
||||
# Options
|
||||
|
||||
- `--dry-run`\
|
||||
Print on standard error a description of what packages would be
|
||||
|
@ -54,8 +56,6 @@ The following flags are available:
|
|||
previous build, the new output path is left in
|
||||
`/nix/store/name.check.`
|
||||
|
||||
{{#include ../status-build-failure.md}}
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
@ -67,8 +67,6 @@ The following flags are available:
|
|||
This operation is typically used to build [store derivation]s produced by
|
||||
[`nix-instantiate`](@docroot@/command-ref/nix-instantiate.md):
|
||||
|
||||
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
|
||||
|
||||
```console
|
||||
$ nix-store --realise $(nix-instantiate ./test.nix)
|
||||
/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1
|
||||
|
|
|
@ -33,7 +33,7 @@
|
|||
|
||||
Ensure a [store path] is [valid][validity].
|
||||
|
||||
This means either running the `builder` executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter].
|
||||
This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation], or fetching a pre-built [store object] from a [substituter], or delegating to a [remote builder](@docroot@/advanced-topics/distributed-builds.html) and retrieving the outputs. <!-- TODO: link [running] to build process page, #8888 -->
|
||||
|
||||
See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md).
|
||||
|
||||
|
|
|
@ -17,7 +17,7 @@ the attributes of which specify the inputs of the build.
|
|||
string. This is used as a symbolic name for the package by
|
||||
`nix-env`, and it is appended to the output paths of the derivation.
|
||||
|
||||
- There must be an attribute named `builder` that identifies the
|
||||
- There must be an attribute named [`builder`]{#attr-builder} that identifies the
|
||||
program that is executed to perform the build. It can be either a
|
||||
derivation or a source (a local file reference, e.g.,
|
||||
`./builder.sh`).
|
||||
|
|
Loading…
Reference in a new issue