Merge pull request #7592 from fricklerhandwerk/nix-store-realise

reword description of how realisation works
This commit is contained in:
Valentin Gagarin 2023-09-05 11:55:01 +02:00 committed by GitHub
commit f34484d18a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 26 additions and 28 deletions

View file

@ -1,6 +1,6 @@
# Name # Name
`nix-store --realise` - realise specified store paths `nix-store --realise` - build or fetch store objects
# Synopsis # Synopsis
@ -8,33 +8,35 @@
# Description # 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 Each of *paths* is processed as follows:
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.
- If the store path is not a derivation, realisation ensures that the - If the path leads to a [store derivation]:
specified path is valid (i.e., it and its closure exist in the file 1. If it is not [valid], substitute the store derivation file itself.
system). If the path is already valid, we are done immediately. 2. Realise its [output paths]:
Otherwise, the path and any missing paths in its closure may be - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure].
produced through substitutes. If there are no (successful) - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database].
substitutes, realisation fails. - 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 [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 The resulting paths are printed on standard output.
non-derivations argument, the argument itself is printed.) For non-derivation arguments, the argument itself is printed.
The following flags are available: {{#include ../status-build-failure.md}}
# Options
- `--dry-run`\ - `--dry-run`\
Print on standard error a description of what packages would be 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 previous build, the new output path is left in
`/nix/store/name.check.` `/nix/store/name.check.`
{{#include ../status-build-failure.md}}
{{#include ./opt-common.md}} {{#include ./opt-common.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 This operation is typically used to build [store derivation]s produced by
[`nix-instantiate`](@docroot@/command-ref/nix-instantiate.md): [`nix-instantiate`](@docroot@/command-ref/nix-instantiate.md):
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
```console ```console
$ nix-store --realise $(nix-instantiate ./test.nix) $ nix-store --realise $(nix-instantiate ./test.nix)
/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1 /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1

View file

@ -33,7 +33,7 @@
Ensure a [store path] is [valid][validity]. 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). See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md).

View file

@ -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 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. `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 program that is executed to perform the build. It can be either a
derivation or a source (a local file reference, e.g., derivation or a source (a local file reference, e.g.,
`./builder.sh`). `./builder.sh`).