mirror of
https://github.com/NixOS/nix
synced 2025-06-27 16:51:15 +02:00
8d4b6766e2
e.g. nix-env -e subversion => nix-env --uninstall subversion The aim is to make the documentation less cryptic for newcomers and the long options are more self-documenting. The change was made with the following script: <https://github.com/aschmolck/convert-short-nix-opts-to-long-ones> and sanity checked visually.
118 lines
3.8 KiB
Markdown
118 lines
3.8 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 --realise $(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>' --attr 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)
|
||
```
|