mirror of
https://github.com/NixOS/nix
synced 2024-10-18 13:50:37 -04:00
119 lines
3.7 KiB
Markdown
119 lines
3.7 KiB
Markdown
|
# Name
|
|||
|
|
|
|||
|
|
`nix-store --realise` - realise specified store paths
|
|||
|
|
|
|||
|
|
# Synopsis
|
|||
|
|
|
|||
|
|
`nix-store` {`--realise` | `-r`} *paths…* [`--dry-run`]
|
|||
|
|
|
|||
|
|
# 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.
|
|||
|
|
|
|||
|
|
- 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.
|
|||
|
|
|
|||
|
|
[valid]: @docroot@/glossary.md#gloss-validity
|
|||
|
|
[substitutes]: @docroot@/glossary.md#gloss-substitute
|
|||
|
|
|
|||
|
|
The output path of each derivation is printed on standard output. (For
|
|||
|
|
non-derivations argument, the argument itself is printed.)
|
|||
|
|
|
|||
|
|
The following flags are available:
|
|||
|
|
|
|||
|
|
- `--dry-run`\
|
|||
|
|
Print on standard error a description of what packages would be
|
|||
|
|
built or downloaded, without actually performing the operation.
|
|||
|
|
|
|||
|
|
- `--ignore-unknown`\
|
|||
|
|
If a non-derivation path does not have a substitute, then silently
|
|||
|
|
ignore it.
|
|||
|
|
|
|||
|
|
- `--check`\
|
|||
|
|
This option allows you to check whether a derivation is
|
|||
|
|
deterministic. It rebuilds the specified derivation and checks
|
|||
|
|
whether the result is bitwise-identical with the existing outputs,
|
|||
|
|
printing an error if that’s not the case. The outputs of the
|
|||
|
|
specified derivation must already exist. When used with `-K`, if an
|
|||
|
|
output path is not identical to the corresponding output from the
|
|||
|
|
previous build, the new output path is left in
|
|||
|
|
`/nix/store/name.check.`
|
|||
|
|
|
|||
|
|
Special exit codes:
|
|||
|
|
|
|||
|
|
- `100`\
|
|||
|
|
Generic build failure, the builder process returned with a non-zero
|
|||
|
|
exit code.
|
|||
|
|
|
|||
|
|
- `101`\
|
|||
|
|
Build timeout, the build was aborted because it did not complete
|
|||
|
|
within the specified `timeout`.
|
|||
|
|
|
|||
|
|
- `102`\
|
|||
|
|
Hash mismatch, the build output was rejected because it does not
|
|||
|
|
match the [`outputHash` attribute of the
|
|||
|
|
derivation](@docroot@/language/advanced-attributes.md).
|
|||
|
|
|
|||
|
|
- `104`\
|
|||
|
|
Not deterministic, the build succeeded in check mode but the
|
|||
|
|
resulting output is not binary reproducible.
|
|||
|
|
|
|||
|
|
With the `--keep-going` flag it's possible for multiple failures to
|
|||
|
|
occur, in this case the 1xx status codes are or combined using binary
|
|||
|
|
or.
|
|||
|
|
|
|||
|
|
1100100
|
|||
|
|
^^^^
|
|||
|
|
|||`- timeout
|
|||
|
|
||`-- output hash mismatch
|
|||
|
|
|`--- build failure
|
|||
|
|
`---- not deterministic
|
|||
|
|
|
|||
|
|
|
|||
|
|
{{#include ./opt-common.md}}
|
|||
|
|
|
|||
|
|
{{#include ../opt-common.md}}
|
|||
|
|
|
|||
|
|
{{#include ../env-common.md}}
|
|||
|
|
|
|||
|
|
# Examples
|
|||
|
|
|
|||
|
|
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 -r $(nix-instantiate ./test.nix)
|
|||
|
|
/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
This is essentially what [`nix-build`](@docroot@/command-ref/nix-build.md) does.
|
|||
|
|
|
|||
|
|
To test whether a previously-built derivation is deterministic:
|
|||
|
|
|
|||
|
|
```console
|
|||
|
|
$ nix-build '<nixpkgs>' -A hello --check -K
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Use [`nix-store --read-log`](./read-log.md) to show the stderr and stdout of a build:
|
|||
|
|
|
|||
|
|
```console
|
|||
|
|
$ nix-store --read-log $(nix-instantiate ./test.nix)
|
|||
|
|
```
|