Merge pull request #7518 from fricklerhandwerk/doc-commands
separate man pages for `nix-store` and `nix-env` subcommands
This commit is contained in:
Valentin Gagarin
GitHub
commit
368c5b8b9a
|
|
@ -13,6 +13,13 @@ man-pages := $(foreach n, \
|
|||
nix.conf.5 nix-daemon.8 \
|
||||
, $(d)/$(n))
|
||||
|
||||
# man pages for subcommands
|
||||
# convert from `$(d)/src/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1`
|
||||
# FIXME: unify with how nix3-cli man pages are generated
|
||||
man-pages += $(foreach subcommand, \
|
||||
$(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/src/command-ref/nix-*/*.md)), \
|
||||
$(d)/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand)))))
|
||||
|
||||
clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8
|
||||
|
||||
# Provide a dummy environment for nix, so that it will not access files outside the macOS sandbox.
|
||||
|
|
@ -29,13 +36,35 @@ nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -
|
|||
# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution
|
||||
define process-includes
|
||||
while read -r line; do \
|
||||
filename=$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line); \
|
||||
matchline=$$(sed 's|/|\\/|g' <<< $$line); \
|
||||
sed -i "/$$matchline/r $$(dirname $(2))/$$filename" $(2); \
|
||||
set -euo pipefail; \
|
||||
filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \
|
||||
test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \
|
||||
matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \
|
||||
sed -i "/$$matchline/r $$filename" $(2); \
|
||||
sed -i "s/$$matchline//" $(2); \
|
||||
done < <(grep '{{#include' $(1))
|
||||
endef
|
||||
|
||||
$(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md
|
||||
@printf "Title: %s\n\n" "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" > $^.tmp
|
||||
$(render-subcommand)
|
||||
|
||||
$(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md
|
||||
@printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp
|
||||
$(render-subcommand)
|
||||
|
||||
# FIXME: there surely is some more deduplication to be achieved here with even darker Make magic
|
||||
define render-subcommand
|
||||
@cat $^ >> $^.tmp
|
||||
@$(call process-includes,$^,$^.tmp)
|
||||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
|
||||
@# fix up `lowdown`'s automatic escaping of `--`
|
||||
@# https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
|
||||
@sed -i 's/\e\[u2013\]/--/' $@
|
||||
@rm $^.tmp
|
||||
endef
|
||||
|
||||
|
||||
$(d)/%.1: $(d)/src/command-ref/%.md
|
||||
@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
|
||||
@cat $^ >> $^.tmp
|
||||
|
|
@ -122,6 +151,8 @@ $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/
|
|||
cp -r doc/manual "$$tmp"; \
|
||||
find "$$tmp" -name '*.md' | while read -r file; do \
|
||||
$(call process-includes,$$file,$$file); \
|
||||
done; \
|
||||
find "$$tmp" -name '*.md' | while read -r file; do \
|
||||
docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \
|
||||
sed -i "s,@docroot@,$$docroot,g" "$$file"; \
|
||||
done; \
|
||||
|
|
|
|||
|
|
@ -47,7 +47,38 @@
|
|||
- [nix-build](command-ref/nix-build.md)
|
||||
- [nix-shell](command-ref/nix-shell.md)
|
||||
- [nix-store](command-ref/nix-store.md)
|
||||
- [nix-store --add-fixed](command-ref/nix-store/add-fixed.md)
|
||||
- [nix-store --add](command-ref/nix-store/add.md)
|
||||
- [nix-store --delete](command-ref/nix-store/delete.md)
|
||||
- [nix-store --dump-db](command-ref/nix-store/dump-db.md)
|
||||
- [nix-store --dump](command-ref/nix-store/dump.md)
|
||||
- [nix-store --export](command-ref/nix-store/export.md)
|
||||
- [nix-store --gc](command-ref/nix-store/gc.md)
|
||||
- [nix-store --generate-binary-cache-key](command-ref/nix-store/generate-binary-cache-key.md)
|
||||
- [nix-store --import](command-ref/nix-store/import.md)
|
||||
- [nix-store --load-db](command-ref/nix-store/load-db.md)
|
||||
- [nix-store --optimise](command-ref/nix-store/optimise.md)
|
||||
- [nix-store --print-env](command-ref/nix-store/print-env.md)
|
||||
- [nix-store --query](command-ref/nix-store/query.md)
|
||||
- [nix-store --read-log](command-ref/nix-store/read-log.md)
|
||||
- [nix-store --realise](command-ref/nix-store/realise.md)
|
||||
- [nix-store --repair-path](command-ref/nix-store/repair-path.md)
|
||||
- [nix-store --restore](command-ref/nix-store/restore.md)
|
||||
- [nix-store --serve](command-ref/nix-store/serve.md)
|
||||
- [nix-store --verify-path](command-ref/nix-store/verify-path.md)
|
||||
- [nix-store --verify](command-ref/nix-store/verify.md)
|
||||
- [nix-env](command-ref/nix-env.md)
|
||||
- [nix-env --delete-generations](command-ref/nix-env/delete-generations.md)
|
||||
- [nix-env --install](command-ref/nix-env/install.md)
|
||||
- [nix-env --list-generations](command-ref/nix-env/list-generations.md)
|
||||
- [nix-env --query](command-ref/nix-env/query.md)
|
||||
- [nix-env --rollback](command-ref/nix-env/rollback.md)
|
||||
- [nix-env --set-flag](command-ref/nix-env/set-flag.md)
|
||||
- [nix-env --set](command-ref/nix-env/set.md)
|
||||
- [nix-env --switch-generation](command-ref/nix-env/switch-generation.md)
|
||||
- [nix-env --switch-profile](command-ref/nix-env/switch-profile.md)
|
||||
- [nix-env --uninstall](command-ref/nix-env/uninstall.md)
|
||||
- [nix-env --upgrade](command-ref/nix-env/upgrade.md)
|
||||
- [Utilities](command-ref/utilities.md)
|
||||
- [nix-channel](command-ref/nix-channel.md)
|
||||
- [nix-collect-garbage](command-ref/nix-collect-garbage.md)
|
||||
|
|
|
|||
|
|
@ -2,18 +2,18 @@
|
|||
|
||||
Most Nix commands interpret the following environment variables:
|
||||
|
||||
- [`IN_NIX_SHELL`]{#env-IN_NIX_SHELL}\
|
||||
- <span id="env-IN_NIX_SHELL">[`IN_NIX_SHELL`](#env-IN_NIX_SHELL)</span>\
|
||||
Indicator that tells if the current environment was set up by
|
||||
`nix-shell`. It can have the values `pure` or `impure`.
|
||||
|
||||
- [`NIX_PATH`]{#env-NIX_PATH}\
|
||||
- <span id="env-NIX_PATH">[`NIX_PATH`](#env-NIX_PATH)</span>\
|
||||
A colon-separated list of directories used to look up the location of Nix
|
||||
expressions using [paths](../language/values.md#type-path)
|
||||
expressions using [paths](@docroot@/language/values.md#type-path)
|
||||
enclosed in angle brackets (i.e., `<path>`),
|
||||
e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
|
||||
[`-I` option](./opt-common.md#opt-I).
|
||||
[`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
|
||||
|
||||
If `NIX_PATH` is not set at all, Nix will fall back to the following list in [impure](./conf-file.md#conf-pure-eval) and [unrestricted](./conf-file.md#conf-restrict-eval) evaluation mode:
|
||||
If `NIX_PATH` is not set at all, Nix will fall back to the following list in [impure](@docroot@/command-ref/conf-file.md#conf-pure-eval) and [unrestricted](@docroot@/command-ref/conf-file.md#conf-restrict-eval) evaluation mode:
|
||||
|
||||
1. `$HOME/.nix-defexpr/channels`
|
||||
2. `nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixpkgs`
|
||||
|
|
@ -24,7 +24,7 @@ Most Nix commands interpret the following environment variables:
|
|||
|
||||
error: file 'nixpkgs' was not found in the Nix search path
|
||||
|
||||
- [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
|
||||
- <span id="env-NIX_IGNORE_SYMLINK_STORE">[`NIX_IGNORE_SYMLINK_STORE`](#env-NIX_IGNORE_SYMLINK_STORE)</span>\
|
||||
Normally, the Nix store directory (typically `/nix/store`) is not
|
||||
allowed to contain any symlink components. This is to prevent
|
||||
“impure” builds. Builders sometimes “canonicalise” paths by
|
||||
|
|
@ -46,58 +46,58 @@ Most Nix commands interpret the following environment variables:
|
|||
|
||||
Consult the mount 8 manual page for details.
|
||||
|
||||
- [`NIX_STORE_DIR`]{#env-NIX_STORE_DIR}\
|
||||
- <span id="env-NIX_STORE_DIR">[`NIX_STORE_DIR`](#env-NIX_STORE_DIR)</span>\
|
||||
Overrides the location of the Nix store (default `prefix/store`).
|
||||
|
||||
- [`NIX_DATA_DIR`]{#env-NIX_DATA_DIR}\
|
||||
- <span id="env-NIX_DATA_DIR">[`NIX_DATA_DIR`](#env-NIX_DATA_DIR)</span>\
|
||||
Overrides the location of the Nix static data directory (default
|
||||
`prefix/share`).
|
||||
|
||||
- [`NIX_LOG_DIR`]{#env-NIX_LOG_DIR}\
|
||||
- <span id="env-NIX_LOG_DIR">[`NIX_LOG_DIR`](#env-NIX_LOG_DIR)</span>\
|
||||
Overrides the location of the Nix log directory (default
|
||||
`prefix/var/log/nix`).
|
||||
|
||||
- [`NIX_STATE_DIR`]{#env-NIX_STATE_DIR}\
|
||||
- <span id="env-NIX_STATE_DIR">[`NIX_STATE_DIR`](#env-NIX_STATE_DIR)</span>\
|
||||
Overrides the location of the Nix state directory (default
|
||||
`prefix/var/nix`).
|
||||
|
||||
- [`NIX_CONF_DIR`]{#env-NIX_CONF_DIR}\
|
||||
- <span id="env-NIX_CONF_DIR">[`NIX_CONF_DIR`](#env-NIX_CONF_DIR)</span>\
|
||||
Overrides the location of the system Nix configuration directory
|
||||
(default `prefix/etc/nix`).
|
||||
|
||||
- [`NIX_CONFIG`]{#env-NIX_CONFIG}\
|
||||
- <span id="env-NIX_CONFIG">[`NIX_CONFIG`](#env-NIX_CONFIG)</span>\
|
||||
Applies settings from Nix configuration from the environment.
|
||||
The content is treated as if it was read from a Nix configuration file.
|
||||
Settings are separated by the newline character.
|
||||
|
||||
- [`NIX_USER_CONF_FILES`]{#env-NIX_USER_CONF_FILES}\
|
||||
- <span id="env-NIX_USER_CONF_FILES">[`NIX_USER_CONF_FILES`](#env-NIX_USER_CONF_FILES)</span>\
|
||||
Overrides the location of the user Nix configuration files to load
|
||||
from (defaults to the XDG spec locations). The variable is treated
|
||||
as a list separated by the `:` token.
|
||||
|
||||
- [`TMPDIR`]{#env-TMPDIR}\
|
||||
- <span id="env-TMPDIR">[`TMPDIR`](#env-TMPDIR)</span>\
|
||||
Use the specified directory to store temporary files. In particular,
|
||||
this includes temporary build directories; these can take up
|
||||
substantial amounts of disk space. The default is `/tmp`.
|
||||
|
||||
- [`NIX_REMOTE`]{#env-NIX_REMOTE}\
|
||||
- <span id="env-NIX_REMOTE">[`NIX_REMOTE`](#env-NIX_REMOTE)</span>\
|
||||
This variable should be set to `daemon` if you want to use the Nix
|
||||
daemon to execute Nix operations. This is necessary in [multi-user
|
||||
Nix installations](../installation/multi-user.md). If the Nix
|
||||
Nix installations](@docroot@/installation/multi-user.md). If the Nix
|
||||
daemon's Unix socket is at some non-standard path, this variable
|
||||
should be set to `unix://path/to/socket`. Otherwise, it should be
|
||||
left unset.
|
||||
|
||||
- [`NIX_SHOW_STATS`]{#env-NIX_SHOW_STATS}\
|
||||
- <span id="env-NIX_SHOW_STATS">[`NIX_SHOW_STATS`](#env-NIX_SHOW_STATS)</span>\
|
||||
If set to `1`, Nix will print some evaluation statistics, such as
|
||||
the number of values allocated.
|
||||
|
||||
- [`NIX_COUNT_CALLS`]{#env-NIX_COUNT_CALLS}\
|
||||
- <span id="env-NIX_COUNT_CALLS">[`NIX_COUNT_CALLS`](#env-NIX_COUNT_CALLS)</span>\
|
||||
If set to `1`, Nix will print how often functions were called during
|
||||
Nix expression evaluation. This is useful for profiling your Nix
|
||||
expressions.
|
||||
|
||||
- [`GC_INITIAL_HEAP_SIZE`]{#env-GC_INITIAL_HEAP_SIZE}\
|
||||
- <span id="env-GC_INITIAL_HEAP_SIZE">[`GC_INITIAL_HEAP_SIZE`](#env-GC_INITIAL_HEAP_SIZE)</span>\
|
||||
If Nix has been configured to use the Boehm garbage collector, this
|
||||
variable sets the initial size of the heap in bytes. It defaults to
|
||||
384 MiB. Setting it to a low value reduces memory consumption, but
|
||||
|
|
@ -114,4 +114,4 @@ New Nix commands conform to the [XDG Base Directory Specification], and use the
|
|||
Classic Nix commands can also be made to follow this standard using the [`use-xdg-base-directories`] configuration option.
|
||||
|
||||
[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
||||
[`use-xdg-base-directories`]: ../command-ref/conf-file.md#conf-use-xdg-base-directories
|
||||
[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
|
||||
|
|
@ -38,7 +38,7 @@ 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
|
||||
--realise`](nix-store.md#operation---realise) (to build the store
|
||||
--realise`](@docroot@/command-ref/nix-store/realise.md) (to build the store
|
||||
derivation).
|
||||
|
||||
[store derivation]: ../glossary.md#gloss-store-derivation
|
||||
|
|
@ -51,9 +51,8 @@ derivation).
|
|||
|
||||
# Options
|
||||
|
||||
All options not listed here are passed to `nix-store
|
||||
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
|
||||
`nix-instantiate`.
|
||||
All options not listed here are passed to `nix-store --realise`,
|
||||
except for `--arg` and `--attr` / `-A` which are passed to `nix-instantiate`.
|
||||
|
||||
- <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
|
||||
|
||||
|
|
@ -70,7 +69,9 @@ All options not listed here are passed to `nix-store
|
|||
Change the name of the symlink to the output path created from
|
||||
`result` to *outlink*.
|
||||
|
||||
The following common options are supported:
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -45,6 +45,10 @@ Note that `--add` does not automatically perform an update.
|
|||
|
||||
The list of subscribed channels is stored in `~/.nix-channels`.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To subscribe to the Nixpkgs channel and install the GNU Hello package:
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
# Description
|
||||
|
||||
The command `nix-collect-garbage` is mostly an alias of [`nix-store
|
||||
--gc`](nix-store.md#operation---gc), that is, it deletes all
|
||||
--gc`](@docroot@/command-ref/nix-store/gc.md), that is, it deletes all
|
||||
unreachable paths in the Nix store to clean up your system. However,
|
||||
it provides two additional options: `-d` (`--delete-old`), which
|
||||
deletes all old generations of all profiles in `/nix/var/nix/profiles`
|
||||
|
|
@ -20,6 +20,10 @@ and `--delete-older-than` *period*, where period is a value such as
|
|||
of days in all profiles in `/nix/var/nix/profiles` (except for the
|
||||
generations that were active at that point in time).
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
# Example
|
||||
|
||||
To delete from the Nix store everything that is not used by the current
|
||||
|
|
|
|||
|
|
@ -63,12 +63,16 @@ authentication, you can avoid typing the passphrase with `ssh-agent`.
|
|||
- `-v`\
|
||||
Show verbose output.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
# Environment variables
|
||||
|
||||
- `NIX_SSHOPTS`\
|
||||
Additional options to be passed to `ssh` on the command
|
||||
line.
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
Copy Firefox with all its dependencies to a remote machine:
|
||||
|
|
|
|||
|
|
@ -4,15 +4,14 @@
|
|||
|
||||
# Synopsis
|
||||
|
||||
`nix-env`
|
||||
`nix-env` *operation* [*options*] [*arguments…*]
|
||||
[`--option` *name* *value*]
|
||||
[`--arg` *name* *value*]
|
||||
[`--argstr` *name* *value*]
|
||||
[{`--file` | `-f`} *path*]
|
||||
[{`--profile` | `-p`} *path(]
|
||||
[{`--profile` | `-p`} *path*]
|
||||
[`--system-filter` *system*]
|
||||
[`--dry-run`]
|
||||
*operation* [*options…*] [*arguments…*]
|
||||
|
||||
# Description
|
||||
|
||||
|
|
@ -24,7 +23,29 @@ environments: different users can have different environments, and
|
|||
individual users can switch between different environments.
|
||||
|
||||
`nix-env` takes exactly one *operation* flag which indicates the
|
||||
subcommand to be performed. These are documented below.
|
||||
subcommand to be performed. The following operations are available:
|
||||
|
||||
- [`--install`](./nix-env/install.md)
|
||||
- [`--upgrade`](./nix-env/upgrade.md)
|
||||
- [`--uninstall`](./nix-env/uninstall.md)
|
||||
- [`--set`](./nix-env/set.md)
|
||||
- [`--set-flag`](./nix-env/set-flag.md)
|
||||
- [`--query`](./nix-env/query.md)
|
||||
- [`--switch-profile`](./nix-env/switch-profile.md)
|
||||
- [`--list-generations`](./nix-env/list-generations.md)
|
||||
- [`--delete-generations`](./nix-env/delete-generations.md)
|
||||
- [`--switch-generation`](./nix-env/switch-generation.md)
|
||||
- [`--rollback`](./nix-env/rollback.md)
|
||||
|
||||
These pages can be viewed offline:
|
||||
|
||||
- `man nix-env-<operation>`.
|
||||
|
||||
Example: `man nix-env-install`
|
||||
|
||||
- `nix-env --help --<operation>`
|
||||
|
||||
Example: `nix-env --help --install`
|
||||
|
||||
# Selectors
|
||||
|
||||
|
|
@ -60,46 +81,6 @@ match. Here are some examples:
|
|||
Matches any package name containing the strings `firefox` or
|
||||
`chromium`.
|
||||
|
||||
# Common options
|
||||
|
||||
This section lists the options that are common to all operations. These
|
||||
options are allowed for every subcommand, though they may not always
|
||||
have an effect.
|
||||
|
||||
- `--file` / `-f` *path*\
|
||||
Specifies the Nix expression (designated below as the *active Nix
|
||||
expression*) used by the `--install`, `--upgrade`, and `--query
|
||||
--available` operations to obtain derivations. The default is
|
||||
`~/.nix-defexpr`.
|
||||
|
||||
If the argument starts with `http://` or `https://`, it is
|
||||
interpreted as the URL of a tarball that will be downloaded and
|
||||
unpacked to a temporary location. The tarball must include a single
|
||||
top-level directory containing at least a file named `default.nix`.
|
||||
|
||||
- `--profile` / `-p` *path*\
|
||||
Specifies the profile to be used by those operations that operate on
|
||||
a profile (designated below as the *active profile*). A profile is a
|
||||
sequence of user environments called *generations*, one of which is
|
||||
the *current generation*.
|
||||
|
||||
- `--dry-run`\
|
||||
For the `--install`, `--upgrade`, `--uninstall`,
|
||||
`--switch-generation`, `--delete-generations` and `--rollback`
|
||||
operations, this flag will cause `nix-env` to print what *would* be
|
||||
done if this flag had not been specified, without actually doing it.
|
||||
|
||||
`--dry-run` also prints out which paths will be
|
||||
[substituted](../glossary.md) (i.e., downloaded) and which paths
|
||||
will be built from source (because no substitute is available).
|
||||
|
||||
- `--system-filter` *system*\
|
||||
By default, operations such as `--query
|
||||
--available` show derivations matching any platform. This option
|
||||
allows you to use derivations for the specified platform *system*.
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
# Files
|
||||
|
||||
- `~/.nix-defexpr`\
|
||||
|
|
@ -145,750 +126,3 @@ have an effect.
|
|||
symlink points to `prefix/var/nix/profiles/default`. The `PATH`
|
||||
environment variable should include `~/.nix-profile/bin` for the
|
||||
user environment to be visible to the user.
|
||||
|
||||
# Operation `--install`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` {`--install` | `-i`} *args…*
|
||||
[{`--prebuilt-only` | `-b`}]
|
||||
[{`--attr` | `-A`}]
|
||||
[`--from-expression`] [`-E`]
|
||||
[`--from-profile` *path*]
|
||||
[`--preserve-installed` | `-P`]
|
||||
[`--remove-all` | `-r`]
|
||||
|
||||
## Description
|
||||
|
||||
The install operation creates a new user environment, based on the
|
||||
current generation of the active profile, to which a set of store paths
|
||||
described by *args* is added. The arguments *args* map to store paths in
|
||||
a number of possible ways:
|
||||
|
||||
- By default, *args* is a set of derivation names denoting derivations
|
||||
in the active Nix expression. 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.
|
||||
|
||||
If there are multiple derivations matching a name in *args* that
|
||||
have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
|
||||
derivation with the highest *priority* is used. A derivation can
|
||||
define a priority by declaring the `meta.priority` attribute. This
|
||||
attribute should be a number, with a higher value denoting a lower
|
||||
priority. The default priority is `0`.
|
||||
|
||||
If there are multiple matching derivations with the same priority,
|
||||
then the derivation with the highest version will be installed.
|
||||
|
||||
You can force the installation of multiple derivations with the same
|
||||
name by being specific about the versions. For instance, `nix-env -i
|
||||
gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
|
||||
probably cause a user environment conflict\!).
|
||||
|
||||
- If `--attr` (`-A`) is specified, the arguments are *attribute
|
||||
paths* that select attributes from the top-level Nix
|
||||
expression. This is faster than using derivation names and
|
||||
unambiguous. To find out the attribute paths of available
|
||||
packages, use `nix-env -qaP`.
|
||||
|
||||
- If `--from-profile` *path* is given, *args* is a set of names
|
||||
denoting installed store paths in the profile *path*. This is an
|
||||
easy way to copy user environment elements from one profile to
|
||||
another.
|
||||
|
||||
- If `--from-expression` is given, *args* are Nix
|
||||
[functions](../language/constructs.md#functions)
|
||||
that are called with the active Nix expression as their single
|
||||
argument. 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 derivation]s, then these are
|
||||
[realised](nix-store.md#operation---realise), and the resulting output paths
|
||||
are installed.
|
||||
|
||||
[store derivation]: ../glossary.md#gloss-store-derivation
|
||||
|
||||
- If *args* are store paths that are not store derivations, then these
|
||||
are [realised](nix-store.md#operation---realise) and installed.
|
||||
|
||||
- By default all outputs are installed for each derivation. That can
|
||||
be reduced by setting `meta.outputsToInstall`.
|
||||
|
||||
## Flags
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
|
||||
- `--preserve-installed`; `-P`\
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
|
||||
- `--remove-all`; `-r`\
|
||||
Remove all previously installed packages first. This is equivalent
|
||||
to running `nix-env -e '.*'` first, except that everything happens
|
||||
in a single transaction.
|
||||
|
||||
## Examples
|
||||
|
||||
To install a package using a specific attribute path from the active Nix expression:
|
||||
|
||||
```console
|
||||
$ nix-env -iA gcc40mips
|
||||
installing `gcc-4.0.2'
|
||||
$ nix-env -iA xorg.xorgserver
|
||||
installing `xorg-server-1.2.0'
|
||||
```
|
||||
|
||||
To install a specific version of `gcc` using the derivation name:
|
||||
|
||||
```console
|
||||
$ nix-env --install gcc-3.3.2
|
||||
installing `gcc-3.3.2'
|
||||
uninstalling `gcc-3.1'
|
||||
```
|
||||
|
||||
Using attribute path for selecting a package is preferred,
|
||||
as it is much faster and there will not be multiple matches.
|
||||
|
||||
Note the previously installed version is removed, since
|
||||
`--preserve-installed` was not specified.
|
||||
|
||||
To install an arbitrary version:
|
||||
|
||||
```console
|
||||
$ nix-env --install gcc
|
||||
installing `gcc-3.3.2'
|
||||
```
|
||||
|
||||
To install all derivations in the Nix expression `foo.nix`:
|
||||
|
||||
```console
|
||||
$ nix-env -f ~/foo.nix -i '.*'
|
||||
```
|
||||
|
||||
To copy the store path with symbolic name `gcc` from another profile:
|
||||
|
||||
```console
|
||||
$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
|
||||
```
|
||||
|
||||
To install a specific [store derivation] (typically created by
|
||||
`nix-instantiate`):
|
||||
|
||||
```console
|
||||
$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
|
||||
```
|
||||
|
||||
To install a specific output path:
|
||||
|
||||
```console
|
||||
$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
|
||||
```
|
||||
|
||||
To install from a Nix expression specified on the command-line:
|
||||
|
||||
```console
|
||||
$ nix-env -f ./foo.nix -i -E \
|
||||
'f: (f {system = "i686-linux";}).subversionWithJava'
|
||||
```
|
||||
|
||||
I.e., this evaluates to `(f: (f {system =
|
||||
"i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting
|
||||
the `subversionWithJava` attribute from the set returned by calling the
|
||||
function defined in `./foo.nix`.
|
||||
|
||||
A dry-run tells you which paths will be downloaded or built from source:
|
||||
|
||||
```console
|
||||
$ nix-env -f '<nixpkgs>' -iA hello --dry-run
|
||||
(dry run; not doing anything)
|
||||
installing ‘hello-2.10’
|
||||
this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
|
||||
/nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
|
||||
...
|
||||
```
|
||||
|
||||
To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
|
||||
channel:
|
||||
|
||||
```console
|
||||
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
|
||||
```
|
||||
|
||||
# Operation `--upgrade`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` {`--upgrade` | `-u`} *args*
|
||||
[`--lt` | `--leq` | `--eq` | `--always`]
|
||||
[{`--prebuilt-only` | `-b`}]
|
||||
[{`--attr` | `-A`}]
|
||||
[`--from-expression`] [`-E`]
|
||||
[`--from-profile` *path*]
|
||||
[`--preserve-installed` | `-P`]
|
||||
|
||||
## Description
|
||||
|
||||
The upgrade operation creates a new user environment, based on the
|
||||
current generation of the active profile, in which all store paths are
|
||||
replaced for which there are newer versions in the set of paths
|
||||
described by *args*. Paths for which there are no newer versions are
|
||||
left untouched; this is not an error. It is also not an error if an
|
||||
element of *args* matches no installed derivations.
|
||||
|
||||
For a description of how *args* is mapped to a set of store paths, see
|
||||
[`--install`](#operation---install). If *args* describes multiple
|
||||
store paths with the same symbolic name, only the one with the highest
|
||||
version is installed.
|
||||
|
||||
## Flags
|
||||
|
||||
- `--lt`\
|
||||
Only upgrade a derivation to newer versions. This is the default.
|
||||
|
||||
- `--leq`\
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same version. Version are not a unique
|
||||
identification of a derivation, so there may be many derivations
|
||||
that have the same version. This flag may be useful to force
|
||||
“synchronisation” between the installed and available derivations.
|
||||
|
||||
- `--eq`\
|
||||
*Only* “upgrade” to derivations that have the same version. This may
|
||||
not seem very useful, but it actually is, e.g., when there is a new
|
||||
release of Nixpkgs and you want to replace installed applications
|
||||
with the same versions built against newer dependencies (to reduce
|
||||
the number of dependencies floating around on your system).
|
||||
|
||||
- `--always`\
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same or a lower version. I.e., derivations
|
||||
may actually be downgraded depending on what is available in the
|
||||
active Nix expression.
|
||||
|
||||
For the other flags, see `--install`.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env --upgrade -A nixpkgs.gcc
|
||||
upgrading `gcc-3.3.1' to `gcc-3.4'
|
||||
```
|
||||
|
||||
When there are no updates available, nothing will happen:
|
||||
|
||||
```console
|
||||
$ nix-env --upgrade -A nixpkgs.pan
|
||||
```
|
||||
|
||||
Using `-A` is preferred when possible, as it is faster and unambiguous but
|
||||
it is also possible to upgrade to a specific version by matching the derivation name:
|
||||
|
||||
```console
|
||||
$ nix-env -u gcc-3.3.2 --always
|
||||
upgrading `gcc-3.4' to `gcc-3.3.2'
|
||||
```
|
||||
|
||||
To try to upgrade everything
|
||||
(matching packages based on the part of the derivation name without version):
|
||||
|
||||
```console
|
||||
$ nix-env -u
|
||||
upgrading `hello-2.1.2' to `hello-2.1.3'
|
||||
upgrading `mozilla-1.2' to `mozilla-1.4'
|
||||
```
|
||||
|
||||
## Versions
|
||||
|
||||
The upgrade operation determines whether a derivation `y` is an upgrade
|
||||
of a derivation `x` by looking at their respective `name` attributes.
|
||||
The names (e.g., `gcc-3.3.1` are split into two parts: the package name
|
||||
(`gcc`), and the version (`3.3.1`). The version part starts after the
|
||||
first dash not followed by a letter. `y` is considered an upgrade of `x`
|
||||
if their package names match, and the version of `y` is higher than that
|
||||
of `x`.
|
||||
|
||||
The versions are compared by splitting them into contiguous components
|
||||
of numbers and letters. E.g., `3.3.1pre5` is split into `[3, 3, 1,
|
||||
"pre", 5]`. These lists are then compared lexicographically (from left
|
||||
to right). Corresponding components `a` and `b` are compared as follows.
|
||||
If they are both numbers, integer comparison is used. If `a` is an empty
|
||||
string and `b` is a number, `a` is considered less than `b`. The special
|
||||
string component `pre` (for *pre-release*) is considered to be less than
|
||||
other components. String components are considered less than number
|
||||
components. Otherwise, they are compared lexicographically (i.e., using
|
||||
case-sensitive string comparison).
|
||||
|
||||
This is illustrated by the following examples:
|
||||
|
||||
1.0 < 2.3
|
||||
2.1 < 2.3
|
||||
2.3 = 2.3
|
||||
2.5 > 2.3
|
||||
3.1 > 2.3
|
||||
2.3.1 > 2.3
|
||||
2.3.1 > 2.3a
|
||||
2.3pre1 < 2.3
|
||||
2.3pre3 < 2.3pre12
|
||||
2.3a < 2.3c
|
||||
2.3pre1 < 2.3c
|
||||
2.3pre1 < 2.3q
|
||||
|
||||
# Operation `--uninstall`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` {`--uninstall` | `-e`} *drvnames…*
|
||||
|
||||
## Description
|
||||
|
||||
The uninstall operation creates a new user environment, based on the
|
||||
current generation of the active profile, from which the store paths
|
||||
designated by the symbolic names *drvnames* are removed.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env --uninstall gcc
|
||||
$ nix-env -e '.*' (remove everything)
|
||||
```
|
||||
|
||||
# Operation `--set`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` `--set` *drvname*
|
||||
|
||||
## Description
|
||||
|
||||
The `--set` operation modifies the current generation of a profile so
|
||||
that it contains exactly the specified derivation, and nothing else.
|
||||
|
||||
## Examples
|
||||
|
||||
The following updates a profile such that its current generation will
|
||||
contain just Firefox:
|
||||
|
||||
```console
|
||||
$ nix-env -p /nix/var/nix/profiles/browser --set firefox
|
||||
```
|
||||
|
||||
# Operation `--set-flag`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` `--set-flag` *name* *value* *drvnames*
|
||||
|
||||
## Description
|
||||
|
||||
The `--set-flag` operation allows meta attributes of installed packages
|
||||
to be modified. There are several attributes that can be usefully
|
||||
modified, because they affect the behaviour of `nix-env` or the user
|
||||
environment build script:
|
||||
|
||||
- `priority` can be changed to resolve filename clashes. The user
|
||||
environment build script uses the `meta.priority` attribute of
|
||||
derivations to resolve filename collisions between packages. Lower
|
||||
priority values denote a higher priority. For instance, the GCC
|
||||
wrapper package and the Binutils package in Nixpkgs both have a file
|
||||
`bin/ld`, so previously if you tried to install both you would get a
|
||||
collision. Now, on the other hand, the GCC wrapper declares a higher
|
||||
priority than Binutils, so the former’s `bin/ld` is symlinked in the
|
||||
user environment.
|
||||
|
||||
- `keep` can be set to `true` to prevent the package from being
|
||||
upgraded or replaced. This is useful if you want to hang on to an
|
||||
older version of a package.
|
||||
|
||||
- `active` can be set to `false` to “disable” the package. That is, no
|
||||
symlinks will be generated to the files of the package, but it
|
||||
remains part of the profile (so it won’t be garbage-collected). It
|
||||
can be set back to `true` to re-enable the package.
|
||||
|
||||
## Examples
|
||||
|
||||
To prevent the currently installed Firefox from being upgraded:
|
||||
|
||||
```console
|
||||
$ nix-env --set-flag keep true firefox
|
||||
```
|
||||
|
||||
After this, `nix-env -u` will ignore Firefox.
|
||||
|
||||
To disable the currently installed Firefox, then install a new Firefox
|
||||
while the old remains part of the profile:
|
||||
|
||||
```console
|
||||
$ nix-env -q
|
||||
firefox-2.0.0.9 (the current one)
|
||||
|
||||
$ nix-env --preserve-installed -i firefox-2.0.0.11
|
||||
installing `firefox-2.0.0.11'
|
||||
building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
|
||||
collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
|
||||
and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
|
||||
(i.e., can’t have two active at the same time)
|
||||
|
||||
$ nix-env --set-flag active false firefox
|
||||
setting flag on `firefox-2.0.0.9'
|
||||
|
||||
$ nix-env --preserve-installed -i firefox-2.0.0.11
|
||||
installing `firefox-2.0.0.11'
|
||||
|
||||
$ nix-env -q
|
||||
firefox-2.0.0.11 (the enabled one)
|
||||
firefox-2.0.0.9 (the disabled one)
|
||||
```
|
||||
|
||||
To make files from `binutils` take precedence over files from `gcc`:
|
||||
|
||||
```console
|
||||
$ nix-env --set-flag priority 5 binutils
|
||||
$ nix-env --set-flag priority 10 gcc
|
||||
```
|
||||
|
||||
# Operation `--query`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` {`--query` | `-q`} *names…*
|
||||
[`--installed` | `--available` | `-a`]
|
||||
[{`--status` | `-s`}]
|
||||
[{`--attr-path` | `-P`}]
|
||||
[`--no-name`]
|
||||
[{`--compare-versions` | `-c`}]
|
||||
[`--system`]
|
||||
[`--drv-path`]
|
||||
[`--out-path`]
|
||||
[`--description`]
|
||||
[`--meta`]
|
||||
[`--xml`]
|
||||
[`--json`]
|
||||
[{`--prebuilt-only` | `-b`}]
|
||||
[{`--attr` | `-A`} *attribute-path*]
|
||||
|
||||
## Description
|
||||
|
||||
The query operation displays information about either the store paths
|
||||
that are installed in the current generation of the active profile
|
||||
(`--installed`), or the derivations that are available for installation
|
||||
in the active Nix expression (`--available`). It only prints information
|
||||
about derivations whose symbolic name matches one of *names*.
|
||||
|
||||
The derivations are sorted by their `name` attributes.
|
||||
|
||||
## Source selection
|
||||
|
||||
The following flags specify the set of things on which the query
|
||||
operates.
|
||||
|
||||
- `--installed`\
|
||||
The query operates on the store paths that are installed in the
|
||||
current generation of the active profile. This is the default.
|
||||
|
||||
- `--available`; `-a`\
|
||||
The query operates on the derivations that are available in the
|
||||
active Nix expression.
|
||||
|
||||
## Queries
|
||||
|
||||
The following flags specify what information to display about the
|
||||
selected derivations. Multiple flags may be specified, in which case the
|
||||
information is shown in the order given here. Note that the name of the
|
||||
derivation is shown unless `--no-name` is specified.
|
||||
|
||||
- `--xml`\
|
||||
Print the result in an XML representation suitable for automatic
|
||||
processing by other tools. The root element is called `items`, which
|
||||
contains a `item` element for each available or installed
|
||||
derivation. The fields discussed below are all stored in attributes
|
||||
of the `item` elements.
|
||||
|
||||
- `--json`\
|
||||
Print the result in a JSON representation suitable for automatic
|
||||
processing by other tools.
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
Show only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, this shows all packages that
|
||||
probably can be installed quickly.
|
||||
|
||||
- `--status`; `-s`\
|
||||
Print the *status* of the derivation. The status consists of three
|
||||
characters. The first is `I` or `-`, indicating whether the
|
||||
derivation is currently installed in the current generation of the
|
||||
active profile. This is by definition the case for `--installed`,
|
||||
but not for `--available`. The second is `P` or `-`, indicating
|
||||
whether the derivation is present on the system. This indicates
|
||||
whether installation of an available derivation will require the
|
||||
derivation to be built. The third is `S` or `-`, indicating whether
|
||||
a substitute is available for the derivation.
|
||||
|
||||
- `--attr-path`; `-P`\
|
||||
Print the *attribute path* of the derivation, which can be used to
|
||||
unambiguously select it using the `--attr` option available in
|
||||
commands that install derivations like `nix-env --install`. This
|
||||
option only works together with `--available`
|
||||
|
||||
- `--no-name`\
|
||||
Suppress printing of the `name` attribute of each derivation.
|
||||
|
||||
- `--compare-versions` / `-c`\
|
||||
Compare installed versions to available versions, or vice versa (if
|
||||
`--available` is given). This is useful for quickly seeing whether
|
||||
upgrades for installed packages are available in a Nix expression. A
|
||||
column is added with the following meaning:
|
||||
|
||||
- `<` *version*\
|
||||
A newer version of the package is available or installed.
|
||||
|
||||
- `=` *version*\
|
||||
At most the same version of the package is available or
|
||||
installed.
|
||||
|
||||
- `>` *version*\
|
||||
Only older versions of the package are available or installed.
|
||||
|
||||
- `- ?`\
|
||||
No version of the package is available or installed.
|
||||
|
||||
- `--system`\
|
||||
Print the `system` attribute of the derivation.
|
||||
|
||||
- `--drv-path`\
|
||||
Print the path of the [store derivation].
|
||||
|
||||
- `--out-path`\
|
||||
Print the output path of the derivation.
|
||||
|
||||
- `--description`\
|
||||
Print a short (one-line) description of the derivation, if
|
||||
available. The description is taken from the `meta.description`
|
||||
attribute of the derivation.
|
||||
|
||||
- `--meta`\
|
||||
Print all of the meta-attributes of the derivation. This option is
|
||||
only available with `--xml` or `--json`.
|
||||
|
||||
## Examples
|
||||
|
||||
To show installed packages:
|
||||
|
||||
```console
|
||||
$ nix-env -q
|
||||
bison-1.875c
|
||||
docbook-xml-4.2
|
||||
firefox-1.0.4
|
||||
MPlayer-1.0pre7
|
||||
ORBit2-2.8.3
|
||||
…
|
||||
```
|
||||
|
||||
To show available packages:
|
||||
|
||||
```console
|
||||
$ nix-env -qa
|
||||
firefox-1.0.7
|
||||
GConf-2.4.0.1
|
||||
MPlayer-1.0pre7
|
||||
ORBit2-2.8.3
|
||||
…
|
||||
```
|
||||
|
||||
To show the status of available packages:
|
||||
|
||||
```console
|
||||
$ nix-env -qas
|
||||
-P- firefox-1.0.7 (not installed but present)
|
||||
--S GConf-2.4.0.1 (not present, but there is a substitute for fast installation)
|
||||
--S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
|
||||
IP- ORBit2-2.8.3 (installed and by definition present)
|
||||
…
|
||||
```
|
||||
|
||||
To show available packages in the Nix expression `foo.nix`:
|
||||
|
||||
```console
|
||||
$ nix-env -f ./foo.nix -qa
|
||||
foo-1.2.3
|
||||
```
|
||||
|
||||
To compare installed versions to what’s available:
|
||||
|
||||
```console
|
||||
$ nix-env -qc
|
||||
...
|
||||
acrobat-reader-7.0 - ? (package is not available at all)
|
||||
autoconf-2.59 = 2.59 (same version)
|
||||
firefox-1.0.4 < 1.0.7 (a more recent version is available)
|
||||
...
|
||||
```
|
||||
|
||||
To show all packages with “`zip`” in the name:
|
||||
|
||||
```console
|
||||
$ nix-env -qa '.*zip.*'
|
||||
bzip2-1.0.6
|
||||
gzip-1.6
|
||||
zip-3.0
|
||||
…
|
||||
```
|
||||
|
||||
To show all packages with “`firefox`” or “`chromium`” in the name:
|
||||
|
||||
```console
|
||||
$ nix-env -qa '.*(firefox|chromium).*'
|
||||
chromium-37.0.2062.94
|
||||
chromium-beta-38.0.2125.24
|
||||
firefox-32.0.3
|
||||
firefox-with-plugins-13.0.1
|
||||
…
|
||||
```
|
||||
|
||||
To show all packages in the latest revision of the Nixpkgs repository:
|
||||
|
||||
```console
|
||||
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
|
||||
```
|
||||
|
||||
# Operation `--switch-profile`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` {`--switch-profile` | `-S`} *path*
|
||||
|
||||
## Description
|
||||
|
||||
This operation makes *path* the current profile for the user. That is,
|
||||
the symlink `~/.nix-profile` is made to point to *path*.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env -S ~/my-profile
|
||||
```
|
||||
|
||||
# Operation `--list-generations`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` `--list-generations`
|
||||
|
||||
## Description
|
||||
|
||||
This operation print a list of all the currently existing generations
|
||||
for the active profile. These may be switched to using the
|
||||
`--switch-generation` operation. It also prints the creation date of the
|
||||
generation, and indicates the current generation.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env --list-generations
|
||||
95 2004-02-06 11:48:24
|
||||
96 2004-02-06 11:49:01
|
||||
97 2004-02-06 16:22:45
|
||||
98 2004-02-06 16:24:33 (current)
|
||||
```
|
||||
|
||||
# Operation `--delete-generations`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` `--delete-generations` *generations*
|
||||
|
||||
## Description
|
||||
|
||||
This operation deletes the specified generations of the current profile.
|
||||
The generations can be a list of generation numbers, the special value
|
||||
`old` to delete all non-current generations, a value such as `30d` to
|
||||
delete all generations older than the specified number of days (except
|
||||
for the generation that was active at that point in time), or a value
|
||||
such as `+5` to keep the last `5` generations ignoring any newer than
|
||||
current, e.g., if `30` is the current generation `+5` will delete
|
||||
generation `25` and all older generations. Periodically deleting old
|
||||
generations is important to make garbage collection effective.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env --delete-generations 3 4 8
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --delete-generations +5
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --delete-generations 30d
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env -p other_profile --delete-generations old
|
||||
```
|
||||
|
||||
# Operation `--switch-generation`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` {`--switch-generation` | `-G`} *generation*
|
||||
|
||||
## Description
|
||||
|
||||
This operation makes generation number *generation* the current
|
||||
generation of the active profile. That is, if the `profile` is the path
|
||||
to the active profile, then the symlink `profile` is made to point to
|
||||
`profile-generation-link`, which is in turn a symlink to the actual user
|
||||
environment in the Nix store.
|
||||
|
||||
Switching will fail if the specified generation does not exist.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env -G 42
|
||||
switching from generation 50 to 42
|
||||
```
|
||||
|
||||
# Operation `--rollback`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` `--rollback`
|
||||
|
||||
## Description
|
||||
|
||||
This operation switches to the “previous” generation of the active
|
||||
profile, that is, the highest numbered generation lower than the current
|
||||
generation, if it exists. It is just a convenience wrapper around
|
||||
`--list-generations` and `--switch-generation`.
|
||||
|
||||
## Examples
|
||||
|
||||
```console
|
||||
$ nix-env --rollback
|
||||
switching from generation 92 to 91
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --rollback
|
||||
error: no generation older than the current (91) exists
|
||||
```
|
||||
|
||||
# Environment variables
|
||||
|
||||
- `NIX_PROFILE`\
|
||||
Location of the Nix profile. Defaults to the target of the symlink
|
||||
`~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
|
||||
otherwise.
|
||||
|
|
|
|||
46
doc/manual/src/command-ref/nix-env/delete-generations.md
Normal file
46
doc/manual/src/command-ref/nix-env/delete-generations.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# Name
|
||||
|
||||
`nix-env --delete-generations` - delete profile generations
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` `--delete-generations` *generations*
|
||||
|
||||
# Description
|
||||
|
||||
This operation deletes the specified generations of the current profile.
|
||||
The generations can be a list of generation numbers, the special value
|
||||
`old` to delete all non-current generations, a value such as `30d` to
|
||||
delete all generations older than the specified number of days (except
|
||||
for the generation that was active at that point in time), or a value
|
||||
such as `+5` to keep the last `5` generations ignoring any newer than
|
||||
current, e.g., if `30` is the current generation `+5` will delete
|
||||
generation `25` and all older generations. Periodically deleting old
|
||||
generations is important to make garbage collection effective.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env --delete-generations 3 4 8
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --delete-generations +5
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --delete-generations 30d
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env -p other_profile --delete-generations old
|
||||
```
|
||||
|
||||
6
doc/manual/src/command-ref/nix-env/env-common.md
Normal file
6
doc/manual/src/command-ref/nix-env/env-common.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Environment variables
|
||||
|
||||
- `NIX_PROFILE`\
|
||||
Location of the Nix profile. Defaults to the target of the symlink
|
||||
`~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
|
||||
otherwise.
|
||||
187
doc/manual/src/command-ref/nix-env/install.md
Normal file
187
doc/manual/src/command-ref/nix-env/install.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# Name
|
||||
|
||||
`nix-env --install` - add packages to user environment
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` {`--install` | `-i`} *args…*
|
||||
[{`--prebuilt-only` | `-b`}]
|
||||
[{`--attr` | `-A`}]
|
||||
[`--from-expression`] [`-E`]
|
||||
[`--from-profile` *path*]
|
||||
[`--preserve-installed` | `-P`]
|
||||
[`--remove-all` | `-r`]
|
||||
|
||||
# Description
|
||||
|
||||
The install operation creates a new user environment, based on the
|
||||
current generation of the active profile, to which a set of store paths
|
||||
described by *args* is added. The arguments *args* map to store paths in
|
||||
a number of possible ways:
|
||||
|
||||
- By default, *args* is a set of derivation names denoting derivations
|
||||
in the active Nix expression. 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.
|
||||
|
||||
If there are multiple derivations matching a name in *args* that
|
||||
have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
|
||||
derivation with the highest *priority* is used. A derivation can
|
||||
define a priority by declaring the `meta.priority` attribute. This
|
||||
attribute should be a number, with a higher value denoting a lower
|
||||
priority. The default priority is `0`.
|
||||
|
||||
If there are multiple matching derivations with the same priority,
|
||||
then the derivation with the highest version will be installed.
|
||||
|
||||
You can force the installation of multiple derivations with the same
|
||||
name by being specific about the versions. For instance, `nix-env -i
|
||||
gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
|
||||
probably cause a user environment conflict\!).
|
||||
|
||||
- If `--attr` (`-A`) is specified, the arguments are *attribute
|
||||
paths* that select attributes from the top-level Nix
|
||||
expression. This is faster than using derivation names and
|
||||
unambiguous. To find out the attribute paths of available
|
||||
packages, use `nix-env -qaP`.
|
||||
|
||||
- If `--from-profile` *path* is given, *args* is a set of names
|
||||
denoting installed store paths in the profile *path*. This is an
|
||||
easy way to copy user environment elements from one profile to
|
||||
another.
|
||||
|
||||
- If `--from-expression` is given, *args* are Nix
|
||||
[functions](@docroot@/language/constructs.md#functions)
|
||||
that are called with the active Nix expression as their single
|
||||
argument. 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](@docroot@/command-ref/nix-store/realise.md), and the resulting output paths
|
||||
are installed.
|
||||
|
||||
- If *args* are store paths that are not store derivations, then these
|
||||
are [realised](@docroot@/command-ref/nix-store/realise.md) and installed.
|
||||
|
||||
- By default all outputs are installed for each derivation. That can
|
||||
be reduced by setting `meta.outputsToInstall`.
|
||||
|
||||
# Flags
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
|
||||
- `--preserve-installed` / `-P`\
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
|
||||
- `--remove-all` / `-r`\
|
||||
Remove all previously installed packages first. This is equivalent
|
||||
to running `nix-env -e '.*'` first, except that everything happens
|
||||
in a single transaction.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To install a package using a specific attribute path from the active Nix expression:
|
||||
|
||||
```console
|
||||
$ nix-env -iA gcc40mips
|
||||
installing `gcc-4.0.2'
|
||||
$ nix-env -iA xorg.xorgserver
|
||||
installing `xorg-server-1.2.0'
|
||||
```
|
||||
|
||||
To install a specific version of `gcc` using the derivation name:
|
||||
|
||||
```console
|
||||
$ nix-env --install gcc-3.3.2
|
||||
installing `gcc-3.3.2'
|
||||
uninstalling `gcc-3.1'
|
||||
```
|
||||
|
||||
Using attribute path for selecting a package is preferred,
|
||||
as it is much faster and there will not be multiple matches.
|
||||
|
||||
Note the previously installed version is removed, since
|
||||
`--preserve-installed` was not specified.
|
||||
|
||||
To install an arbitrary version:
|
||||
|
||||
```console
|
||||
$ nix-env --install gcc
|
||||
installing `gcc-3.3.2'
|
||||
```
|
||||
|
||||
To install all derivations in the Nix expression `foo.nix`:
|
||||
|
||||
```console
|
||||
$ nix-env -f ~/foo.nix -i '.*'
|
||||
```
|
||||
|
||||
To copy the store path with symbolic name `gcc` from another profile:
|
||||
|
||||
```console
|
||||
$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
|
||||
```
|
||||
|
||||
To install a specific [store derivation] (typically created by
|
||||
`nix-instantiate`):
|
||||
|
||||
```console
|
||||
$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
|
||||
```
|
||||
|
||||
To install a specific output path:
|
||||
|
||||
```console
|
||||
$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
|
||||
```
|
||||
|
||||
To install from a Nix expression specified on the command-line:
|
||||
|
||||
```console
|
||||
$ nix-env -f ./foo.nix -i -E \
|
||||
'f: (f {system = "i686-linux";}).subversionWithJava'
|
||||
```
|
||||
|
||||
I.e., this evaluates to `(f: (f {system =
|
||||
"i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting
|
||||
the `subversionWithJava` attribute from the set returned by calling the
|
||||
function defined in `./foo.nix`.
|
||||
|
||||
A dry-run tells you which paths will be downloaded or built from source:
|
||||
|
||||
```console
|
||||
$ nix-env -f '<nixpkgs>' -iA hello --dry-run
|
||||
(dry run; not doing anything)
|
||||
installing ‘hello-2.10’
|
||||
this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
|
||||
/nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
|
||||
...
|
||||
```
|
||||
|
||||
To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
|
||||
channel:
|
||||
|
||||
```console
|
||||
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
|
||||
```
|
||||
|
||||
33
doc/manual/src/command-ref/nix-env/list-generations.md
Normal file
33
doc/manual/src/command-ref/nix-env/list-generations.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# Name
|
||||
|
||||
`nix-env --list-generations` - list profile generations
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` `--list-generations`
|
||||
|
||||
# Description
|
||||
|
||||
This operation print a list of all the currently existing generations
|
||||
for the active profile. These may be switched to using the
|
||||
`--switch-generation` operation. It also prints the creation date of the
|
||||
generation, and indicates the current generation.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env --list-generations
|
||||
95 2004-02-06 11:48:24
|
||||
96 2004-02-06 11:49:01
|
||||
97 2004-02-06 16:22:45
|
||||
98 2004-02-06 16:24:33 (current)
|
||||
```
|
||||
|
||||
35
doc/manual/src/command-ref/nix-env/opt-common.md
Normal file
35
doc/manual/src/command-ref/nix-env/opt-common.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Options
|
||||
|
||||
The following options are allowed for all `nix-env` operations, but may not always have an effect.
|
||||
|
||||
- `--file` / `-f` *path*\
|
||||
Specifies the Nix expression (designated below as the *active Nix
|
||||
expression*) used by the `--install`, `--upgrade`, and `--query
|
||||
--available` operations to obtain derivations. The default is
|
||||
`~/.nix-defexpr`.
|
||||
|
||||
If the argument starts with `http://` or `https://`, it is
|
||||
interpreted as the URL of a tarball that will be downloaded and
|
||||
unpacked to a temporary location. The tarball must include a single
|
||||
top-level directory containing at least a file named `default.nix`.
|
||||
|
||||
- `--profile` / `-p` *path*\
|
||||
Specifies the profile to be used by those operations that operate on
|
||||
a profile (designated below as the *active profile*). A profile is a
|
||||
sequence of user environments called *generations*, one of which is
|
||||
the *current generation*.
|
||||
|
||||
- `--dry-run`\
|
||||
For the `--install`, `--upgrade`, `--uninstall`,
|
||||
`--switch-generation`, `--delete-generations` and `--rollback`
|
||||
operations, this flag will cause `nix-env` to print what *would* be
|
||||
done if this flag had not been specified, without actually doing it.
|
||||
|
||||
`--dry-run` also prints out which paths will be
|
||||
[substituted](@docroot@/glossary.md) (i.e., downloaded) and which paths
|
||||
will be built from source (because no substitute is available).
|
||||
|
||||
- `--system-filter` *system*\
|
||||
By default, operations such as `--query
|
||||
--available` show derivations matching any platform. This option
|
||||
allows you to use derivations for the specified platform *system*.
|
||||
215
doc/manual/src/command-ref/nix-env/query.md
Normal file
215
doc/manual/src/command-ref/nix-env/query.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
# Name
|
||||
|
||||
`nix-env --query` - display information about packages
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` {`--query` | `-q`} *names…*
|
||||
[`--installed` | `--available` | `-a`]
|
||||
[{`--status` | `-s`}]
|
||||
[{`--attr-path` | `-P`}]
|
||||
[`--no-name`]
|
||||
[{`--compare-versions` | `-c`}]
|
||||
[`--system`]
|
||||
[`--drv-path`]
|
||||
[`--out-path`]
|
||||
[`--description`]
|
||||
[`--meta`]
|
||||
[`--xml`]
|
||||
[`--json`]
|
||||
[{`--prebuilt-only` | `-b`}]
|
||||
[{`--attr` | `-A`} *attribute-path*]
|
||||
|
||||
# Description
|
||||
|
||||
The query operation displays information about either the store paths
|
||||
that are installed in the current generation of the active profile
|
||||
(`--installed`), or the derivations that are available for installation
|
||||
in the active Nix expression (`--available`). It only prints information
|
||||
about derivations whose symbolic name matches one of *names*.
|
||||
|
||||
The derivations are sorted by their `name` attributes.
|
||||
|
||||
# Source selection
|
||||
|
||||
The following flags specify the set of things on which the query
|
||||
operates.
|
||||
|
||||
- `--installed`\
|
||||
The query operates on the store paths that are installed in the
|
||||
current generation of the active profile. This is the default.
|
||||
|
||||
- `--available`; `-a`\
|
||||
The query operates on the derivations that are available in the
|
||||
active Nix expression.
|
||||
|
||||
# Queries
|
||||
|
||||
The following flags specify what information to display about the
|
||||
selected derivations. Multiple flags may be specified, in which case the
|
||||
information is shown in the order given here. Note that the name of the
|
||||
derivation is shown unless `--no-name` is specified.
|
||||
|
||||
- `--xml`\
|
||||
Print the result in an XML representation suitable for automatic
|
||||
processing by other tools. The root element is called `items`, which
|
||||
contains a `item` element for each available or installed
|
||||
derivation. The fields discussed below are all stored in attributes
|
||||
of the `item` elements.
|
||||
|
||||
- `--json`\
|
||||
Print the result in a JSON representation suitable for automatic
|
||||
processing by other tools.
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
Show only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, this shows all packages that
|
||||
probably can be installed quickly.
|
||||
|
||||
- `--status`; `-s`\
|
||||
Print the *status* of the derivation. The status consists of three
|
||||
characters. The first is `I` or `-`, indicating whether the
|
||||
derivation is currently installed in the current generation of the
|
||||
active profile. This is by definition the case for `--installed`,
|
||||
but not for `--available`. The second is `P` or `-`, indicating
|
||||
whether the derivation is present on the system. This indicates
|
||||
whether installation of an available derivation will require the
|
||||
derivation to be built. The third is `S` or `-`, indicating whether
|
||||
a substitute is available for the derivation.
|
||||
|
||||
- `--attr-path`; `-P`\
|
||||
Print the *attribute path* of the derivation, which can be used to
|
||||
unambiguously select it using the `--attr` option available in
|
||||
commands that install derivations like `nix-env --install`. This
|
||||
option only works together with `--available`
|
||||
|
||||
- `--no-name`\
|
||||
Suppress printing of the `name` attribute of each derivation.
|
||||
|
||||
- `--compare-versions` / `-c`\
|
||||
Compare installed versions to available versions, or vice versa (if
|
||||
`--available` is given). This is useful for quickly seeing whether
|
||||
upgrades for installed packages are available in a Nix expression. A
|
||||
column is added with the following meaning:
|
||||
|
||||
- `<` *version*\
|
||||
A newer version of the package is available or installed.
|
||||
|
||||
- `=` *version*\
|
||||
At most the same version of the package is available or
|
||||
installed.
|
||||
|
||||
- `>` *version*\
|
||||
Only older versions of the package are available or installed.
|
||||
|
||||
- `- ?`\
|
||||
No version of the package is available or installed.
|
||||
|
||||
- `--system`\
|
||||
Print the `system` attribute of the derivation.
|
||||
|
||||
- `--drv-path`\
|
||||
Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
|
||||
|
||||
- `--out-path`\
|
||||
Print the output path of the derivation.
|
||||
|
||||
- `--description`\
|
||||
Print a short (one-line) description of the derivation, if
|
||||
available. The description is taken from the `meta.description`
|
||||
attribute of the derivation.
|
||||
|
||||
- `--meta`\
|
||||
Print all of the meta-attributes of the derivation. This option is
|
||||
only available with `--xml` or `--json`.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To show installed packages:
|
||||
|
||||
```console
|
||||
$ nix-env -q
|
||||
bison-1.875c
|
||||
docbook-xml-4.2
|
||||
firefox-1.0.4
|
||||
MPlayer-1.0pre7
|
||||
ORBit2-2.8.3
|
||||
…
|
||||
```
|
||||
|
||||
To show available packages:
|
||||
|
||||
```console
|
||||
$ nix-env -qa
|
||||
firefox-1.0.7
|
||||
GConf-2.4.0.1
|
||||
MPlayer-1.0pre7
|
||||
ORBit2-2.8.3
|
||||
…
|
||||
```
|
||||
|
||||
To show the status of available packages:
|
||||
|
||||
```console
|
||||
$ nix-env -qas
|
||||
-P- firefox-1.0.7 (not installed but present)
|
||||
--S GConf-2.4.0.1 (not present, but there is a substitute for fast installation)
|
||||
--S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
|
||||
IP- ORBit2-2.8.3 (installed and by definition present)
|
||||
…
|
||||
```
|
||||
|
||||
To show available packages in the Nix expression `foo.nix`:
|
||||
|
||||
```console
|
||||
$ nix-env -f ./foo.nix -qa
|
||||
foo-1.2.3
|
||||
```
|
||||
|
||||
To compare installed versions to what’s available:
|
||||
|
||||
```console
|
||||
$ nix-env -qc
|
||||
...
|
||||
acrobat-reader-7.0 - ? (package is not available at all)
|
||||
autoconf-2.59 = 2.59 (same version)
|
||||
firefox-1.0.4 < 1.0.7 (a more recent version is available)
|
||||
...
|
||||
```
|
||||
|
||||
To show all packages with “`zip`” in the name:
|
||||
|
||||
```console
|
||||
$ nix-env -qa '.*zip.*'
|
||||
bzip2-1.0.6
|
||||
gzip-1.6
|
||||
zip-3.0
|
||||
…
|
||||
```
|
||||
|
||||
To show all packages with “`firefox`” or “`chromium`” in the name:
|
||||
|
||||
```console
|
||||
$ nix-env -qa '.*(firefox|chromium).*'
|
||||
chromium-37.0.2062.94
|
||||
chromium-beta-38.0.2125.24
|
||||
firefox-32.0.3
|
||||
firefox-with-plugins-13.0.1
|
||||
…
|
||||
```
|
||||
|
||||
To show all packages in the latest revision of the Nixpkgs repository:
|
||||
|
||||
```console
|
||||
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
|
||||
```
|
||||
|
||||
34
doc/manual/src/command-ref/nix-env/rollback.md
Normal file
34
doc/manual/src/command-ref/nix-env/rollback.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
# Name
|
||||
|
||||
`nix-env --rollback` - set user environment to previous generation
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` `--rollback`
|
||||
|
||||
# Description
|
||||
|
||||
This operation switches to the “previous” generation of the active
|
||||
profile, that is, the highest numbered generation lower than the current
|
||||
generation, if it exists. It is just a convenience wrapper around
|
||||
`--list-generations` and `--switch-generation`.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env --rollback
|
||||
switching from generation 92 to 91
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --rollback
|
||||
error: no generation older than the current (91) exists
|
||||
```
|
||||
82
doc/manual/src/command-ref/nix-env/set-flag.md
Normal file
82
doc/manual/src/command-ref/nix-env/set-flag.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
# Name
|
||||
|
||||
`nix-env --set-flag` - modify meta attributes of installed packages
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` `--set-flag` *name* *value* *drvnames*
|
||||
|
||||
# Description
|
||||
|
||||
The `--set-flag` operation allows meta attributes of installed packages
|
||||
to be modified. There are several attributes that can be usefully
|
||||
modified, because they affect the behaviour of `nix-env` or the user
|
||||
environment build script:
|
||||
|
||||
- `priority` can be changed to resolve filename clashes. The user
|
||||
environment build script uses the `meta.priority` attribute of
|
||||
derivations to resolve filename collisions between packages. Lower
|
||||
priority values denote a higher priority. For instance, the GCC
|
||||
wrapper package and the Binutils package in Nixpkgs both have a file
|
||||
`bin/ld`, so previously if you tried to install both you would get a
|
||||
collision. Now, on the other hand, the GCC wrapper declares a higher
|
||||
priority than Binutils, so the former’s `bin/ld` is symlinked in the
|
||||
user environment.
|
||||
|
||||
- `keep` can be set to `true` to prevent the package from being
|
||||
upgraded or replaced. This is useful if you want to hang on to an
|
||||
older version of a package.
|
||||
|
||||
- `active` can be set to `false` to “disable” the package. That is, no
|
||||
symlinks will be generated to the files of the package, but it
|
||||
remains part of the profile (so it won’t be garbage-collected). It
|
||||
can be set back to `true` to re-enable the package.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To prevent the currently installed Firefox from being upgraded:
|
||||
|
||||
```console
|
||||
$ nix-env --set-flag keep true firefox
|
||||
```
|
||||
|
||||
After this, `nix-env -u` will ignore Firefox.
|
||||
|
||||
To disable the currently installed Firefox, then install a new Firefox
|
||||
while the old remains part of the profile:
|
||||
|
||||
```console
|
||||
$ nix-env -q
|
||||
firefox-2.0.0.9 (the current one)
|
||||
|
||||
$ nix-env --preserve-installed -i firefox-2.0.0.11
|
||||
installing `firefox-2.0.0.11'
|
||||
building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
|
||||
collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
|
||||
and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
|
||||
(i.e., can’t have two active at the same time)
|
||||
|
||||
$ nix-env --set-flag active false firefox
|
||||
setting flag on `firefox-2.0.0.9'
|
||||
|
||||
$ nix-env --preserve-installed -i firefox-2.0.0.11
|
||||
installing `firefox-2.0.0.11'
|
||||
|
||||
$ nix-env -q
|
||||
firefox-2.0.0.11 (the enabled one)
|
||||
firefox-2.0.0.9 (the disabled one)
|
||||
```
|
||||
|
||||
To make files from `binutils` take precedence over files from `gcc`:
|
||||
|
||||
```console
|
||||
$ nix-env --set-flag priority 5 binutils
|
||||
$ nix-env --set-flag priority 10 gcc
|
||||
```
|
||||
|
||||
30
doc/manual/src/command-ref/nix-env/set.md
Normal file
30
doc/manual/src/command-ref/nix-env/set.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Name
|
||||
|
||||
`nix-env --set` - set profile to contain a specified derivation
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-env` `--set` *drvname*
|
||||
|
||||
## Description
|
||||
|
||||
The `--set` operation modifies the current generation of a profile so
|
||||
that it contains exactly the specified derivation, and nothing else.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
## Examples
|
||||
|
||||
The following updates a profile such that its current generation will
|
||||
contain just Firefox:
|
||||
|
||||
```console
|
||||
$ nix-env -p /nix/var/nix/profiles/browser --set firefox
|
||||
```
|
||||
|
||||
33
doc/manual/src/command-ref/nix-env/switch-generation.md
Normal file
33
doc/manual/src/command-ref/nix-env/switch-generation.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# Name
|
||||
|
||||
`nix-env --switch-generation` - set user environment to given profile generation
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` {`--switch-generation` | `-G`} *generation*
|
||||
|
||||
# Description
|
||||
|
||||
This operation makes generation number *generation* the current
|
||||
generation of the active profile. That is, if the `profile` is the path
|
||||
to the active profile, then the symlink `profile` is made to point to
|
||||
`profile-generation-link`, which is in turn a symlink to the actual user
|
||||
environment in the Nix store.
|
||||
|
||||
Switching will fail if the specified generation does not exist.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env -G 42
|
||||
switching from generation 50 to 42
|
||||
```
|
||||
|
||||
26
doc/manual/src/command-ref/nix-env/switch-profile.md
Normal file
26
doc/manual/src/command-ref/nix-env/switch-profile.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# Name
|
||||
|
||||
`nix-env --switch-profile` - set user environment to given profile
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` {`--switch-profile` | `-S`} *path*
|
||||
|
||||
# Description
|
||||
|
||||
This operation makes *path* the current profile for the user. That is,
|
||||
the symlink `~/.nix-profile` is made to point to *path*.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env -S ~/my-profile
|
||||
```
|
||||
28
doc/manual/src/command-ref/nix-env/uninstall.md
Normal file
28
doc/manual/src/command-ref/nix-env/uninstall.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# Name
|
||||
|
||||
`nix-env --uninstall` - remove packages from user environment
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` {`--uninstall` | `-e`} *drvnames…*
|
||||
|
||||
# Description
|
||||
|
||||
The uninstall operation creates a new user environment, based on the
|
||||
current generation of the active profile, from which the store paths
|
||||
designated by the symbolic names *drvnames* are removed.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env --uninstall gcc
|
||||
$ nix-env -e '.*' (remove everything)
|
||||
```
|
||||
141
doc/manual/src/command-ref/nix-env/upgrade.md
Normal file
141
doc/manual/src/command-ref/nix-env/upgrade.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
# Name
|
||||
|
||||
`nix-env --upgrade` - upgrade packages in user environment
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-env` {`--upgrade` | `-u`} *args*
|
||||
[`--lt` | `--leq` | `--eq` | `--always`]
|
||||
[{`--prebuilt-only` | `-b`}]
|
||||
[{`--attr` | `-A`}]
|
||||
[`--from-expression`] [`-E`]
|
||||
[`--from-profile` *path*]
|
||||
[`--preserve-installed` | `-P`]
|
||||
|
||||
# Description
|
||||
|
||||
The upgrade operation creates a new user environment, based on the
|
||||
current generation of the active profile, in which all store paths are
|
||||
replaced for which there are newer versions in the set of paths
|
||||
described by *args*. Paths for which there are no newer versions are
|
||||
left untouched; this is not an error. It is also not an error if an
|
||||
element of *args* matches no installed derivations.
|
||||
|
||||
For a description of how *args* is mapped to a set of store paths, see
|
||||
[`--install`](#operation---install). If *args* describes multiple
|
||||
store paths with the same symbolic name, only the one with the highest
|
||||
version is installed.
|
||||
|
||||
# Flags
|
||||
|
||||
- `--lt`\
|
||||
Only upgrade a derivation to newer versions. This is the default.
|
||||
|
||||
- `--leq`\
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same version. Version are not a unique
|
||||
identification of a derivation, so there may be many derivations
|
||||
that have the same version. This flag may be useful to force
|
||||
“synchronisation” between the installed and available derivations.
|
||||
|
||||
- `--eq`\
|
||||
*Only* “upgrade” to derivations that have the same version. This may
|
||||
not seem very useful, but it actually is, e.g., when there is a new
|
||||
release of Nixpkgs and you want to replace installed applications
|
||||
with the same versions built against newer dependencies (to reduce
|
||||
the number of dependencies floating around on your system).
|
||||
|
||||
- `--always`\
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same or a lower version. I.e., derivations
|
||||
may actually be downgraded depending on what is available in the
|
||||
active Nix expression.
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
|
||||
- `--preserve-installed` / `-P`\
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
```console
|
||||
$ nix-env --upgrade -A nixpkgs.gcc
|
||||
upgrading `gcc-3.3.1' to `gcc-3.4'
|
||||
```
|
||||
|
||||
When there are no updates available, nothing will happen:
|
||||
|
||||
```console
|
||||
$ nix-env --upgrade -A nixpkgs.pan
|
||||
```
|
||||
|
||||
Using `-A` is preferred when possible, as it is faster and unambiguous but
|
||||
it is also possible to upgrade to a specific version by matching the derivation name:
|
||||
|
||||
```console
|
||||
$ nix-env -u gcc-3.3.2 --always
|
||||
upgrading `gcc-3.4' to `gcc-3.3.2'
|
||||
```
|
||||
|
||||
To try to upgrade everything
|
||||
(matching packages based on the part of the derivation name without version):
|
||||
|
||||
```console
|
||||
$ nix-env -u
|
||||
upgrading `hello-2.1.2' to `hello-2.1.3'
|
||||
upgrading `mozilla-1.2' to `mozilla-1.4'
|
||||
```
|
||||
|
||||
# Versions
|
||||
|
||||
The upgrade operation determines whether a derivation `y` is an upgrade
|
||||
of a derivation `x` by looking at their respective `name` attributes.
|
||||
The names (e.g., `gcc-3.3.1` are split into two parts: the package name
|
||||
(`gcc`), and the version (`3.3.1`). The version part starts after the
|
||||
first dash not followed by a letter. `y` is considered an upgrade of `x`
|
||||
if their package names match, and the version of `y` is higher than that
|
||||
of `x`.
|
||||
|
||||
The versions are compared by splitting them into contiguous components
|
||||
of numbers and letters. E.g., `3.3.1pre5` is split into `[3, 3, 1,
|
||||
"pre", 5]`. These lists are then compared lexicographically (from left
|
||||
to right). Corresponding components `a` and `b` are compared as follows.
|
||||
If they are both numbers, integer comparison is used. If `a` is an empty
|
||||
string and `b` is a number, `a` is considered less than `b`. The special
|
||||
string component `pre` (for *pre-release*) is considered to be less than
|
||||
other components. String components are considered less than number
|
||||
components. Otherwise, they are compared lexicographically (i.e., using
|
||||
case-sensitive string comparison).
|
||||
|
||||
This is illustrated by the following examples:
|
||||
|
||||
1.0 < 2.3
|
||||
2.1 < 2.3
|
||||
2.3 = 2.3
|
||||
2.5 > 2.3
|
||||
3.1 > 2.3
|
||||
2.3.1 > 2.3
|
||||
2.3.1 > 2.3a
|
||||
2.3pre1 < 2.3
|
||||
2.3pre3 < 2.3pre12
|
||||
2.3a < 2.3c
|
||||
2.3pre1 < 2.3c
|
||||
2.3pre1 < 2.3q
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ The hash is computed over a *serialisation* of each path: a dump of
|
|||
the file system tree rooted at the path. This allows directories and
|
||||
symlinks to be hashed as well as regular files. The dump is in the
|
||||
*NAR format* produced by [`nix-store
|
||||
--dump`](nix-store.md#operation---dump). Thus, `nix-hash path`
|
||||
--dump`](@docroot@/command-ref/nix-store/dump.md). Thus, `nix-hash path`
|
||||
yields the same cryptographic hash as `nix-store --dump path |
|
||||
md5sum`.
|
||||
|
||||
|
|
|
|||
|
|
@ -76,7 +76,9 @@ standard input.
|
|||
this option is not enabled, there may be uninstantiated store paths
|
||||
in the final output.
|
||||
|
||||
<!-- end list -->
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ All options not listed here are passed to `nix-store
|
|||
When a `--pure` shell is started, keep the listed environment
|
||||
variables.
|
||||
|
||||
The following common options are supported:
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
# Environment variables
|
||||
|
||||
|
|
@ -110,6 +110,8 @@ The following common options are supported:
|
|||
`bash` found in `<nixpkgs>`, falling back to the `bash` found in
|
||||
`PATH` if not found.
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To build the dependencies of the package Pan, and start an interactive
|
||||
|
|
|
|||
|
|
@ -13,838 +13,35 @@
|
|||
The command `nix-store` performs primitive operations on the Nix store.
|
||||
You generally do not need to run this command manually.
|
||||
|
||||
`nix-store` takes exactly one *operation* flag which indicates the
|
||||
subcommand to be performed. These are documented below.
|
||||
|
||||
# Common options
|
||||
|
||||
This section lists the options that are common to all operations. These
|
||||
options are allowed for every subcommand, though they may not always
|
||||
have an effect.
|
||||
|
||||
- <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
|
||||
|
||||
Causes the result of a realisation (`--realise` and
|
||||
`--force-realise`) to be registered as a root of the garbage
|
||||
collector. *path* will be created as a symlink to the resulting
|
||||
store path. In addition, a uniquely named symlink to *path* will
|
||||
be created in `/nix/var/nix/gcroots/auto/`. For instance,
|
||||
|
||||
```console
|
||||
$ nix-store --add-root /home/eelco/bla/result -r ...
|
||||
|
||||
$ ls -l /nix/var/nix/gcroots/auto
|
||||
lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result
|
||||
|
||||
$ ls -l /home/eelco/bla/result
|
||||
lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10
|
||||
```
|
||||
|
||||
Thus, when `/home/eelco/bla/result` is removed, the GC root in the
|
||||
`auto` directory becomes a dangling symlink and will be ignored by
|
||||
the collector.
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> Note that it is not possible to move or rename GC roots, since
|
||||
> the symlink in the `auto` directory will still point to the old
|
||||
> location.
|
||||
|
||||
If there are multiple results, then multiple symlinks will be
|
||||
created by sequentially numbering symlinks beyond the first one
|
||||
(e.g., `foo`, `foo-2`, `foo-3`, and so on).
|
||||
|
||||
- <span id="opt-stdin">[`--stdin`](#opt-stdin)</span>
|
||||
|
||||
Read *paths…* from the standard input.
|
||||
Useful for chaining nix-store commands.
|
||||
|
||||
# Operation `--realise`
|
||||
|
||||
## 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]: ../glossary.md#gloss-validity
|
||||
[substitutes]: ../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](../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
|
||||
|
||||
## Examples
|
||||
|
||||
This operation is typically used to build [store derivation]s produced by
|
||||
[`nix-instantiate`](./nix-instantiate.md):
|
||||
|
||||
[store derivation]: ../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`](nix-build.md) does.
|
||||
|
||||
To test whether a previously-built derivation is deterministic:
|
||||
|
||||
```console
|
||||
$ nix-build '<nixpkgs>' -A hello --check -K
|
||||
```
|
||||
|
||||
Use [`--read-log`](#operation---read-log) to show the stderr and stdout of a build:
|
||||
|
||||
```console
|
||||
$ nix-store --read-log $(nix-instantiate ./test.nix)
|
||||
```
|
||||
|
||||
# Operation `--serve`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--serve` [`--write`]
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--serve` provides access to the Nix store over stdin and
|
||||
stdout, and is intended to be used as a means of providing Nix store
|
||||
access to a restricted ssh user.
|
||||
|
||||
The following flags are available:
|
||||
|
||||
- `--write`\
|
||||
Allow the connected client to request the realization of
|
||||
derivations. In effect, this can be used to make the host act as a
|
||||
remote builder.
|
||||
|
||||
## Examples
|
||||
|
||||
To turn a host into a build server, the `authorized_keys` file can be
|
||||
used to provide build access to a given SSH public key:
|
||||
|
||||
```console
|
||||
$ cat <<EOF >>/root/.ssh/authorized_keys
|
||||
command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA...
|
||||
EOF
|
||||
```
|
||||
|
||||
# Operation `--gc`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--gc` [`--print-roots` | `--print-live` | `--print-dead`] [`--max-freed` *bytes*]
|
||||
|
||||
## Description
|
||||
|
||||
Without additional flags, the operation `--gc` performs a garbage
|
||||
collection on the Nix store. That is, all paths in the Nix store not
|
||||
reachable via file system references from a set of “roots”, are deleted.
|
||||
|
||||
The following suboperations may be specified:
|
||||
|
||||
- `--print-roots`\
|
||||
This operation prints on standard output the set of roots used by
|
||||
the garbage collector.
|
||||
|
||||
- `--print-live`\
|
||||
This operation prints on standard output the set of “live” store
|
||||
paths, which are all the store paths reachable from the roots. Live
|
||||
paths should never be deleted, since that would break consistency —
|
||||
it would become possible that applications are installed that
|
||||
reference things that are no longer present in the store.
|
||||
|
||||
- `--print-dead`\
|
||||
This operation prints out on standard output the set of “dead” store
|
||||
paths, which is just the opposite of the set of live paths: any path
|
||||
in the store that is not live (with respect to the roots) is dead.
|
||||
|
||||
By default, all unreachable paths are deleted. The following options
|
||||
control what gets deleted and in what order:
|
||||
|
||||
- `--max-freed` *bytes*\
|
||||
Keep deleting paths until at least *bytes* bytes have been deleted,
|
||||
then stop. The argument *bytes* can be followed by the
|
||||
multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
|
||||
or TiB units.
|
||||
|
||||
The behaviour of the collector is also influenced by the
|
||||
`keep-outputs` and `keep-derivations` settings in the Nix
|
||||
configuration file.
|
||||
|
||||
By default, the collector prints the total number of freed bytes when it
|
||||
finishes (or when it is interrupted). With `--print-dead`, it prints the
|
||||
number of bytes that would be freed.
|
||||
|
||||
## Examples
|
||||
|
||||
To delete all unreachable paths, just do:
|
||||
|
||||
```console
|
||||
$ nix-store --gc
|
||||
deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
|
||||
...
|
||||
8825586 bytes freed (8.42 MiB)
|
||||
```
|
||||
|
||||
To delete at least 100 MiBs of unreachable paths:
|
||||
|
||||
```console
|
||||
$ nix-store --gc --max-freed $((100 * 1024 * 1024))
|
||||
```
|
||||
|
||||
# Operation `--delete`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--delete` [`--ignore-liveness`] *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--delete` deletes the store paths *paths* from the Nix
|
||||
store, but only if it is safe to do so; that is, when the path is not
|
||||
reachable from a root of the garbage collector. This means that you can
|
||||
only delete paths that would also be deleted by `nix-store --gc`. Thus,
|
||||
`--delete` is a more targeted version of `--gc`.
|
||||
|
||||
With the option `--ignore-liveness`, reachability from the roots is
|
||||
ignored. However, the path still won’t be deleted if there are other
|
||||
paths in the store that refer to it (i.e., depend on it).
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4
|
||||
0 bytes freed (0.00 MiB)
|
||||
error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive
|
||||
```
|
||||
|
||||
# Operation `--query`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` {`--query` | `-q`}
|
||||
{`--outputs` | `--requisites` | `-R` | `--references` |
|
||||
`--referrers` | `--referrers-closure` | `--deriver` | `-d` |
|
||||
`--graph` | `--tree` | `--binding` *name* | `-b` *name* | `--hash` |
|
||||
`--size` | `--roots`}
|
||||
[`--use-output`] [`-u`] [`--force-realise`] [`-f`]
|
||||
*paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--query` displays information about [store path]s.
|
||||
The queries are described below. At most one query can be
|
||||
specified. The default query is `--outputs`.
|
||||
|
||||
The paths *paths* may also be symlinks from outside of the Nix store, to
|
||||
the Nix store. In that case, the query is applied to the target of the
|
||||
symlink.
|
||||
|
||||
## Common query options
|
||||
|
||||
- `--use-output`; `-u`\
|
||||
For each argument to the query that is a [store 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`](#operation---realise)).
|
||||
|
||||
## Queries
|
||||
|
||||
- `--outputs`\
|
||||
Prints out the [output path]s of the store
|
||||
derivations *paths*. These are the paths that will be produced when
|
||||
the derivation is built.
|
||||
|
||||
- `--requisites`; `-R`\
|
||||
Prints out the [closure] of the given *paths*.
|
||||
|
||||
This query has one option:
|
||||
|
||||
- `--include-outputs`
|
||||
Also include the existing output paths of [store 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
|
||||
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
|
||||
derivation and specifying the option `--include-outputs`.
|
||||
|
||||
- `--references`\
|
||||
Prints the set of [references]s of the store paths
|
||||
*paths*, that is, their immediate dependencies. (For *all*
|
||||
dependencies, use `--requisites`.)
|
||||
|
||||
[reference]: ../glossary.md#gloss-reference
|
||||
|
||||
- `--referrers`\
|
||||
Prints the set of *referrers* of the store paths *paths*, that is,
|
||||
the store paths currently existing in the Nix store that refer to
|
||||
one of *paths*. Note that contrary to the references, the set of
|
||||
referrers is not constant; it can change as store paths are added or
|
||||
removed.
|
||||
|
||||
- `--referrers-closure`\
|
||||
Prints the closure of the set of store paths *paths* under the
|
||||
referrers relation; that is, all store paths that directly or
|
||||
indirectly refer to one of *paths*. These are all the path currently
|
||||
in the Nix store that are dependent on *paths*.
|
||||
|
||||
- `--deriver`; `-d`\
|
||||
Prints the [deriver] of the store paths *paths*. If
|
||||
the path has no deriver (e.g., if it is a source file), or if the
|
||||
deriver is not known (e.g., in the case of a binary-only
|
||||
deployment), the string `unknown-deriver` is printed.
|
||||
|
||||
[deriver]: ../glossary.md#gloss-deriver
|
||||
|
||||
- `--graph`\
|
||||
Prints the references graph of the store paths *paths* in the format
|
||||
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,
|
||||
apply it to an output path.
|
||||
|
||||
- `--tree`\
|
||||
Prints the references graph of the store paths *paths* as a nested
|
||||
ASCII tree. References are ordered by descending closure size; this
|
||||
tends to flatten the tree, making it more readable. The query only
|
||||
recurses into a store path when it is first encountered; this
|
||||
prevents a blowup of the tree representation of the graph.
|
||||
|
||||
- `--graphml`\
|
||||
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
|
||||
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
|
||||
derivation to not have the specified attribute.
|
||||
|
||||
- `--hash`\
|
||||
Prints the SHA-256 hash of the contents of the store paths *paths*
|
||||
(that is, the hash of the output of `nix-store --dump` on the given
|
||||
paths). Since the hash is stored in the Nix database, this is a fast
|
||||
operation.
|
||||
|
||||
- `--size`\
|
||||
Prints the size in bytes of the contents of the store paths *paths*
|
||||
— to be precise, the size of the output of `nix-store --dump` on
|
||||
the given paths. Note that the actual disk space required by the
|
||||
store paths may be higher, especially on filesystems with large
|
||||
cluster sizes.
|
||||
|
||||
- `--roots`\
|
||||
Prints the garbage collector roots that point, directly or
|
||||
indirectly, at the store paths *paths*.
|
||||
|
||||
## Examples
|
||||
|
||||
Print the closure (runtime dependencies) of the `svn` program in the
|
||||
current user environment:
|
||||
|
||||
```console
|
||||
$ nix-store -qR $(which svn)
|
||||
/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
|
||||
/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
|
||||
...
|
||||
```
|
||||
|
||||
Print the build-time dependencies of `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -qR $(nix-store -qd $(which svn))
|
||||
/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv
|
||||
/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh
|
||||
/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv
|
||||
... lots of other paths ...
|
||||
```
|
||||
|
||||
The difference with the previous example is that we ask the closure of
|
||||
the derivation (`-qd`), not the closure of the output path that contains
|
||||
`svn`.
|
||||
|
||||
Show the build-time dependencies as a tree:
|
||||
|
||||
```console
|
||||
$ nix-store -q --tree $(nix-store -qd $(which svn))
|
||||
/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv
|
||||
+---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh
|
||||
+---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv
|
||||
| +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash
|
||||
| +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh
|
||||
...
|
||||
```
|
||||
|
||||
Show all paths that depend on the same OpenSSL library as `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
|
||||
/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
|
||||
/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
|
||||
/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3
|
||||
/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5
|
||||
```
|
||||
|
||||
Show all paths that directly or indirectly depend on the Glibc (C
|
||||
library) used by `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
|
||||
/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
|
||||
/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4
|
||||
...
|
||||
```
|
||||
|
||||
Note that `ldd` is a command that prints out the dynamic libraries used
|
||||
by an ELF executable.
|
||||
|
||||
Make a picture of the runtime dependency graph of the current user
|
||||
environment:
|
||||
|
||||
```console
|
||||
$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps
|
||||
$ gv graph.ps
|
||||
```
|
||||
|
||||
Show every garbage collector root that points to a store path that
|
||||
depends on `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -q --roots $(which svn)
|
||||
/nix/var/nix/profiles/default-81-link
|
||||
/nix/var/nix/profiles/default-82-link
|
||||
/home/eelco/.local/state/nix/profiles/profile-97-link
|
||||
```
|
||||
|
||||
# Operation `--add`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--add` *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--add` adds the specified paths to the Nix store. It
|
||||
prints the resulting paths in the Nix store on standard output.
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --add ./foo.c
|
||||
/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c
|
||||
```
|
||||
|
||||
# Operation `--add-fixed`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--add-fixed` [`--recursive`] *algorithm* *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--add-fixed` adds the specified paths to the Nix store.
|
||||
Unlike `--add` paths are registered using the specified hashing
|
||||
algorithm, resulting in the same output path as a fixed-output
|
||||
derivation. This can be used for sources that are not available from a
|
||||
public url or broke since the download expression was written.
|
||||
|
||||
This operation has the following options:
|
||||
|
||||
- `--recursive`\
|
||||
Use recursive instead of flat hashing mode, used when adding
|
||||
directories to the store.
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz
|
||||
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
|
||||
```
|
||||
|
||||
# Operation `--verify`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--verify` [`--check-contents`] [`--repair`]
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--verify` verifies the internal consistency of the Nix
|
||||
database, and the consistency between the Nix database and the Nix
|
||||
store. Any inconsistencies encountered are automatically repaired.
|
||||
Inconsistencies are generally the result of the Nix store or database
|
||||
being modified by non-Nix tools, or of bugs in Nix itself.
|
||||
|
||||
This operation has the following options:
|
||||
|
||||
- `--check-contents`\
|
||||
Checks that the contents of every valid store path has not been
|
||||
altered by computing a SHA-256 hash of the contents and comparing it
|
||||
with the hash stored in the Nix database at build time. Paths that
|
||||
have been modified are printed out. For large stores,
|
||||
`--check-contents` is obviously quite slow.
|
||||
|
||||
- `--repair`\
|
||||
If any valid path is missing from the store, or (if
|
||||
`--check-contents` is given) the contents of a valid path has been
|
||||
modified, then try to repair the path by redownloading it. See
|
||||
`nix-store --repair-path` for details.
|
||||
|
||||
# Operation `--verify-path`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--verify-path` *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--verify-path` compares the contents of the given store
|
||||
paths to their cryptographic hashes stored in Nix’s database. For every
|
||||
changed path, it prints a warning message. The exit status is 0 if no
|
||||
path has changed, and 1 otherwise.
|
||||
|
||||
## Example
|
||||
|
||||
To verify the integrity of the `svn` command and all its dependencies:
|
||||
|
||||
```console
|
||||
$ nix-store --verify-path $(nix-store -qR $(which svn))
|
||||
```
|
||||
|
||||
# Operation `--repair-path`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--repair-path` *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--repair-path` attempts to “repair” the specified paths
|
||||
by redownloading them using the available substituters. If no
|
||||
substitutes are available, then repair is not possible.
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> During repair, there is a very small time window during which the old
|
||||
> path (if it exists) is moved out of the way and replaced with the new
|
||||
> path. If repair is interrupted in between, then the system may be left
|
||||
> in a broken state (e.g., if the path contains a critical system
|
||||
> component like the GNU C Library).
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
|
||||
path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
|
||||
expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
|
||||
got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
|
||||
|
||||
$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
|
||||
fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
|
||||
…
|
||||
```
|
||||
|
||||
# Operation `--dump`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--dump` *path*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--dump` produces a NAR (Nix ARchive) file containing the
|
||||
contents of the file system tree rooted at *path*. The archive is
|
||||
written to standard output.
|
||||
|
||||
A NAR archive is like a TAR or Zip archive, but it contains only the
|
||||
information that Nix considers important. For instance, timestamps are
|
||||
elided because all files in the Nix store have their timestamp set to 1
|
||||
anyway. Likewise, all permissions are left out except for the execute
|
||||
bit, because all files in the Nix store have 444 or 555 permission.
|
||||
|
||||
Also, a NAR archive is *canonical*, meaning that “equal” paths always
|
||||
produce the same NAR archive. For instance, directory entries are
|
||||
always sorted so that the actual on-disk order doesn’t influence the
|
||||
result. This means that the cryptographic hash of a NAR dump of a
|
||||
path is usable as a fingerprint of the contents of the path. Indeed,
|
||||
the hashes of store paths stored in Nix’s database (see `nix-store -q
|
||||
--hash`) are SHA-256 hashes of the NAR dump of each store path.
|
||||
|
||||
NAR archives support filenames of unlimited length and 64-bit file
|
||||
sizes. They can contain regular files, directories, and symbolic links,
|
||||
but not other types of files (such as device nodes).
|
||||
|
||||
A Nix archive can be unpacked using `nix-store
|
||||
--restore`.
|
||||
|
||||
# Operation `--restore`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--restore` *path*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--restore` unpacks a NAR archive to *path*, which must
|
||||
not already exist. The archive is read from standard input.
|
||||
|
||||
# Operation `--export`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--export` *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--export` writes a serialisation of the specified store
|
||||
paths to standard output in a format that can be imported into another
|
||||
Nix store with `nix-store --import`. This is like `nix-store
|
||||
--dump`, except that the NAR archive produced by that command doesn’t
|
||||
contain the necessary meta-information to allow it to be imported into
|
||||
another Nix store (namely, the set of references of the path).
|
||||
|
||||
This command does not produce a *closure* of the specified paths, so if
|
||||
a store path references other store paths that are missing in the target
|
||||
Nix store, the import will fail. To copy a whole closure, do something
|
||||
like:
|
||||
|
||||
```console
|
||||
$ nix-store --export $(nix-store -qR paths) > out
|
||||
```
|
||||
|
||||
To import the whole closure again, run:
|
||||
|
||||
```console
|
||||
$ nix-store --import < out
|
||||
```
|
||||
|
||||
# Operation `--import`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--import`
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--import` reads a serialisation of a set of store paths
|
||||
produced by `nix-store --export` from standard input and adds those
|
||||
store paths to the Nix store. Paths that already exist in the Nix store
|
||||
are ignored. If a path refers to another path that doesn’t exist in the
|
||||
Nix store, the import fails.
|
||||
|
||||
# Operation `--optimise`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--optimise`
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--optimise` reduces Nix store disk space usage by finding
|
||||
identical files in the store and hard-linking them to each other. It
|
||||
typically reduces the size of the store by something like 25-35%. Only
|
||||
regular files and symlinks are hard-linked in this manner. Files are
|
||||
considered identical when they have the same NAR archive serialisation:
|
||||
that is, regular files must have the same contents and permission
|
||||
(executable or non-executable), and symlinks must have the same
|
||||
contents.
|
||||
|
||||
After completion, or when the command is interrupted, a report on the
|
||||
achieved savings is printed on standard error.
|
||||
|
||||
Use `-vv` or `-vvv` to get some progress indication.
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --optimise
|
||||
hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
|
||||
...
|
||||
541838819 bytes (516.74 MiB) freed by hard-linking 54143 files;
|
||||
there are 114486 files with equal contents out of 215894 files in total
|
||||
```
|
||||
|
||||
# Operation `--read-log`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` {`--read-log` | `-l`} *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--read-log` prints the build log of the specified store
|
||||
paths on standard output. The build log is whatever the builder of a
|
||||
derivation wrote to standard output and standard error. If a store path
|
||||
is not a derivation, the deriver of the store path is used.
|
||||
|
||||
Build logs are kept in `/nix/var/log/nix/drvs`. However, there is no
|
||||
guarantee that a build log is available for any particular store path.
|
||||
For instance, if the path was downloaded as a pre-built binary through a
|
||||
substitute, then the log is unavailable.
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store -l $(which ktorrent)
|
||||
building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1
|
||||
unpacking sources
|
||||
unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz
|
||||
ktorrent-2.2.1/
|
||||
ktorrent-2.2.1/NEWS
|
||||
...
|
||||
```
|
||||
|
||||
# Operation `--dump-db`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--dump-db` [*paths…*]
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--dump-db` writes a dump of the Nix database to standard
|
||||
output. It can be loaded into an empty Nix store using `--load-db`. This
|
||||
is useful for making backups and when migrating to different database
|
||||
schemas.
|
||||
|
||||
By default, `--dump-db` will dump the entire Nix database. When one or
|
||||
more store paths is passed, only the subset of the Nix database for
|
||||
those store paths is dumped. As with `--export`, the user is responsible
|
||||
for passing all the store paths for a closure. See `--export` for an
|
||||
example.
|
||||
|
||||
# Operation `--load-db`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--load-db`
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--load-db` reads a dump of the Nix database created by
|
||||
`--dump-db` from standard input and loads it into the Nix database.
|
||||
|
||||
# Operation `--print-env`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--print-env` *drvpath*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--print-env` prints out the environment of a derivation
|
||||
in a format that can be evaluated by a shell. The command line arguments
|
||||
of the builder are placed in the variable `_args`.
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox)
|
||||
…
|
||||
export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
|
||||
export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
|
||||
export system; system='x86_64-linux'
|
||||
export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
|
||||
```
|
||||
|
||||
# Operation `--generate-binary-cache-key`
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--generate-binary-cache-key` *key-name* *secret-key-file* *public-key-file*
|
||||
|
||||
## Description
|
||||
|
||||
This command generates an [Ed25519 key pair](http://ed25519.cr.yp.to/)
|
||||
that can be used to create a signed binary cache. It takes three
|
||||
mandatory parameters:
|
||||
|
||||
1. A key name, such as `cache.example.org-1`, that is used to look up
|
||||
keys on the client when it verifies signatures. It can be anything,
|
||||
but it’s suggested to use the host name of your cache (e.g.
|
||||
`cache.example.org`) with a suffix denoting the number of the key
|
||||
(to be incremented every time you need to revoke a key).
|
||||
|
||||
2. The file name where the secret key is to be stored.
|
||||
|
||||
3. The file name where the public key is to be stored.
|
||||
`nix-store` takes exactly one *operation* flag which indicates the subcommand to be performed. The following operations are available:
|
||||
|
||||
- [`--realise`](./nix-store/realise.md)
|
||||
- [`--serve`](./nix-store/serve.md)
|
||||
- [`--gc`](./nix-store/gc.md)
|
||||
- [`--delete`](./nix-store/delete.md)
|
||||
- [`--query`](./nix-store/query.md)
|
||||
- [`--add`](./nix-store/add.md)
|
||||
- [`--add-fixed`](./nix-store/add-fixed.md)
|
||||
- [`--verify`](./nix-store/verify.md)
|
||||
- [`--verify-path`](./nix-store/verify-path.md)
|
||||
- [`--repair-path`](./nix-store/repair-path.md)
|
||||
- [`--dump`](./nix-store/dump.md)
|
||||
- [`--restore`](./nix-store/restore.md)
|
||||
- [`--export`](./nix-store/export.md)
|
||||
- [`--import`](./nix-store/import.md)
|
||||
- [`--optimise`](./nix-store/optimise.md)
|
||||
- [`--read-log`](./nix-store/read-log.md)
|
||||
- [`--dump-db`](./nix-store/dump-db.md)
|
||||
- [`--load-db`](./nix-store/load-db.md)
|
||||
- [`--print-env`](./nix-store/print-env.md)
|
||||
- [`--generate-binary-cache-key`](./nix-store/generate-binary-cache-key.md)
|
||||
|
||||
These pages can be viewed offline:
|
||||
|
||||
- `man nix-store-<operation>`.
|
||||
|
||||
Example: `man nix-store-realise`
|
||||
|
||||
- `nix-store --help --<operation>`
|
||||
|
||||
Example: `nix-store --help --realise`
|
||||
|
|
|
|||
35
doc/manual/src/command-ref/nix-store/add-fixed.md
Normal file
35
doc/manual/src/command-ref/nix-store/add-fixed.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Name
|
||||
|
||||
`nix-store --add-fixed` - add paths to store using given hashing algorithm
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--add-fixed` [`--recursive`] *algorithm* *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--add-fixed` adds the specified paths to the Nix store.
|
||||
Unlike `--add` paths are registered using the specified hashing
|
||||
algorithm, resulting in the same output path as a fixed-output
|
||||
derivation. This can be used for sources that are not available from a
|
||||
public url or broke since the download expression was written.
|
||||
|
||||
This operation has the following options:
|
||||
|
||||
- `--recursive`\
|
||||
Use recursive instead of flat hashing mode, used when adding
|
||||
directories to the store.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz
|
||||
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
|
||||
```
|
||||
|
||||
25
doc/manual/src/command-ref/nix-store/add.md
Normal file
25
doc/manual/src/command-ref/nix-store/add.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Name
|
||||
|
||||
`nix-store --add` - add paths to Nix store
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--add` *paths…*
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--add` adds the specified paths to the Nix store. It
|
||||
prints the resulting paths in the Nix store on standard output.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Example
|
||||
|
||||
```console
|
||||
$ nix-store --add ./foo.c
|
||||
/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c
|
||||
```
|
||||
33
doc/manual/src/command-ref/nix-store/delete.md
Normal file
33
doc/manual/src/command-ref/nix-store/delete.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# Name
|
||||
|
||||
`nix-store --delete` - delete store paths
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--delete` [`--ignore-liveness`] *paths…*
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--delete` deletes the store paths *paths* from the Nix
|
||||
store, but only if it is safe to do so; that is, when the path is not
|
||||
reachable from a root of the garbage collector. This means that you can
|
||||
only delete paths that would also be deleted by `nix-store --gc`. Thus,
|
||||
`--delete` is a more targeted version of `--gc`.
|
||||
|
||||
With the option `--ignore-liveness`, reachability from the roots is
|
||||
ignored. However, the path still won’t be deleted if there are other
|
||||
paths in the store that refer to it (i.e., depend on it).
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Example
|
||||
|
||||
```console
|
||||
$ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4
|
||||
0 bytes freed (0.00 MiB)
|
||||
error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive
|
||||
```
|
||||
26
doc/manual/src/command-ref/nix-store/dump-db.md
Normal file
26
doc/manual/src/command-ref/nix-store/dump-db.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# Name
|
||||
|
||||
`nix-store --dump-db` - export Nix database
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--dump-db` [*paths…*]
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--dump-db` writes a dump of the Nix database to standard
|
||||
output. It can be loaded into an empty Nix store using `--load-db`. This
|
||||
is useful for making backups and when migrating to different database
|
||||
schemas.
|
||||
|
||||
By default, `--dump-db` will dump the entire Nix database. When one or
|
||||
more store paths is passed, only the subset of the Nix database for
|
||||
those store paths is dumped. As with `--export`, the user is responsible
|
||||
for passing all the store paths for a closure. See `--export` for an
|
||||
example.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
40
doc/manual/src/command-ref/nix-store/dump.md
Normal file
40
doc/manual/src/command-ref/nix-store/dump.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Name
|
||||
|
||||
`nix-store --dump` - write a single path to a Nix Archive
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--dump` *path*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--dump` produces a NAR (Nix ARchive) file containing the
|
||||
contents of the file system tree rooted at *path*. The archive is
|
||||
written to standard output.
|
||||
|
||||
A NAR archive is like a TAR or Zip archive, but it contains only the
|
||||
information that Nix considers important. For instance, timestamps are
|
||||
elided because all files in the Nix store have their timestamp set to 0
|
||||
anyway. Likewise, all permissions are left out except for the execute
|
||||
bit, because all files in the Nix store have 444 or 555 permission.
|
||||
|
||||
Also, a NAR archive is *canonical*, meaning that “equal” paths always
|
||||
produce the same NAR archive. For instance, directory entries are
|
||||
always sorted so that the actual on-disk order doesn’t influence the
|
||||
result. This means that the cryptographic hash of a NAR dump of a
|
||||
path is usable as a fingerprint of the contents of the path. Indeed,
|
||||
the hashes of store paths stored in Nix’s database (see `nix-store -q
|
||||
--hash`) are SHA-256 hashes of the NAR dump of each store path.
|
||||
|
||||
NAR archives support filenames of unlimited length and 64-bit file
|
||||
sizes. They can contain regular files, directories, and symbolic links,
|
||||
but not other types of files (such as device nodes).
|
||||
|
||||
A Nix archive can be unpacked using `nix-store
|
||||
--restore`.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
41
doc/manual/src/command-ref/nix-store/export.md
Normal file
41
doc/manual/src/command-ref/nix-store/export.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Name
|
||||
|
||||
`nix-store --export` - export store paths to a Nix Archive
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--export` *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--export` writes a serialisation of the specified store
|
||||
paths to standard output in a format that can be imported into another
|
||||
Nix store with `nix-store --import`. This is like `nix-store
|
||||
--dump`, except that the NAR archive produced by that command doesn’t
|
||||
contain the necessary meta-information to allow it to be imported into
|
||||
another Nix store (namely, the set of references of the path).
|
||||
|
||||
This command does not produce a *closure* of the specified paths, so if
|
||||
a store path references other store paths that are missing in the target
|
||||
Nix store, the import will fail.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To copy a whole closure, do something
|
||||
like:
|
||||
|
||||
```console
|
||||
$ nix-store --export $(nix-store -qR paths) > out
|
||||
```
|
||||
|
||||
To import the whole closure again, run:
|
||||
|
||||
```console
|
||||
$ nix-store --import < out
|
||||
```
|
||||
72
doc/manual/src/command-ref/nix-store/gc.md
Normal file
72
doc/manual/src/command-ref/nix-store/gc.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# Name
|
||||
|
||||
`nix-store --gc` - run garbage collection
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--gc` [`--print-roots` | `--print-live` | `--print-dead`] [`--max-freed` *bytes*]
|
||||
|
||||
# Description
|
||||
|
||||
Without additional flags, the operation `--gc` performs a garbage
|
||||
collection on the Nix store. That is, all paths in the Nix store not
|
||||
reachable via file system references from a set of “roots”, are deleted.
|
||||
|
||||
The following suboperations may be specified:
|
||||
|
||||
- `--print-roots`\
|
||||
This operation prints on standard output the set of roots used by
|
||||
the garbage collector.
|
||||
|
||||
- `--print-live`\
|
||||
This operation prints on standard output the set of “live” store
|
||||
paths, which are all the store paths reachable from the roots. Live
|
||||
paths should never be deleted, since that would break consistency —
|
||||
it would become possible that applications are installed that
|
||||
reference things that are no longer present in the store.
|
||||
|
||||
- `--print-dead`\
|
||||
This operation prints out on standard output the set of “dead” store
|
||||
paths, which is just the opposite of the set of live paths: any path
|
||||
in the store that is not live (with respect to the roots) is dead.
|
||||
|
||||
By default, all unreachable paths are deleted. The following options
|
||||
control what gets deleted and in what order:
|
||||
|
||||
- `--max-freed` *bytes*\
|
||||
Keep deleting paths until at least *bytes* bytes have been deleted,
|
||||
then stop. The argument *bytes* can be followed by the
|
||||
multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
|
||||
or TiB units.
|
||||
|
||||
The behaviour of the collector is also influenced by the
|
||||
`keep-outputs` and `keep-derivations` settings in the Nix
|
||||
configuration file.
|
||||
|
||||
By default, the collector prints the total number of freed bytes when it
|
||||
finishes (or when it is interrupted). With `--print-dead`, it prints the
|
||||
number of bytes that would be freed.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To delete all unreachable paths, just do:
|
||||
|
||||
```console
|
||||
$ nix-store --gc
|
||||
deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
|
||||
...
|
||||
8825586 bytes freed (8.42 MiB)
|
||||
```
|
||||
|
||||
To delete at least 100 MiBs of unreachable paths:
|
||||
|
||||
```console
|
||||
$ nix-store --gc --max-freed $((100 * 1024 * 1024))
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# Name
|
||||
|
||||
`nix-store --generate-binary-cache-key` - generate key pair to use for a binary cache
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--generate-binary-cache-key` *key-name* *secret-key-file* *public-key-file*
|
||||
|
||||
## Description
|
||||
|
||||
This command generates an [Ed25519 key pair](http://ed25519.cr.yp.to/)
|
||||
that can be used to create a signed binary cache. It takes three
|
||||
mandatory parameters:
|
||||
|
||||
1. A key name, such as `cache.example.org-1`, that is used to look up
|
||||
keys on the client when it verifies signatures. It can be anything,
|
||||
but it’s suggested to use the host name of your cache (e.g.
|
||||
`cache.example.org`) with a suffix denoting the number of the key
|
||||
(to be incremented every time you need to revoke a key).
|
||||
|
||||
2. The file name where the secret key is to be stored.
|
||||
|
||||
3. The file name where the public key is to be stored.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
21
doc/manual/src/command-ref/nix-store/import.md
Normal file
21
doc/manual/src/command-ref/nix-store/import.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Name
|
||||
|
||||
`nix-store --import` - import Nix Archive into the store
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--import`
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--import` reads a serialisation of a set of store paths
|
||||
produced by `nix-store --export` from standard input and adds those
|
||||
store paths to the Nix store. Paths that already exist in the Nix store
|
||||
are ignored. If a path refers to another path that doesn’t exist in the
|
||||
Nix store, the import fails.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
18
doc/manual/src/command-ref/nix-store/load-db.md
Normal file
18
doc/manual/src/command-ref/nix-store/load-db.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Name
|
||||
|
||||
`nix-store --load-db` - import Nix database
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--load-db`
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--load-db` reads a dump of the Nix database created by
|
||||
`--dump-db` from standard input and loads it into the Nix database.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
36
doc/manual/src/command-ref/nix-store/opt-common.md
Normal file
36
doc/manual/src/command-ref/nix-store/opt-common.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Options
|
||||
|
||||
The following options are allowed for all `nix-store` operations, but may not always have an effect.
|
||||
|
||||
- <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
|
||||
|
||||
Causes the result of a realisation (`--realise` and
|
||||
`--force-realise`) to be registered as a root of the garbage
|
||||
collector. *path* will be created as a symlink to the resulting
|
||||
store path. In addition, a uniquely named symlink to *path* will
|
||||
be created in `/nix/var/nix/gcroots/auto/`. For instance,
|
||||
|
||||
```console
|
||||
$ nix-store --add-root /home/eelco/bla/result -r ...
|
||||
|
||||
$ ls -l /nix/var/nix/gcroots/auto
|
||||
lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result
|
||||
|
||||
$ ls -l /home/eelco/bla/result
|
||||
lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10
|
||||
```
|
||||
|
||||
Thus, when `/home/eelco/bla/result` is removed, the GC root in the
|
||||
`auto` directory becomes a dangling symlink and will be ignored by
|
||||
the collector.
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> Note that it is not possible to move or rename GC roots, since
|
||||
> the symlink in the `auto` directory will still point to the old
|
||||
> location.
|
||||
|
||||
If there are multiple results, then multiple symlinks will be
|
||||
created by sequentially numbering symlinks beyond the first one
|
||||
(e.g., `foo`, `foo-2`, `foo-3`, and so on).
|
||||
|
||||
40
doc/manual/src/command-ref/nix-store/optimise.md
Normal file
40
doc/manual/src/command-ref/nix-store/optimise.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Name
|
||||
|
||||
`nix-store --optimise` - reduce disk space usage
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--optimise`
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--optimise` reduces Nix store disk space usage by finding
|
||||
identical files in the store and hard-linking them to each other. It
|
||||
typically reduces the size of the store by something like 25-35%. Only
|
||||
regular files and symlinks are hard-linked in this manner. Files are
|
||||
considered identical when they have the same NAR archive serialisation:
|
||||
that is, regular files must have the same contents and permission
|
||||
(executable or non-executable), and symlinks must have the same
|
||||
contents.
|
||||
|
||||
After completion, or when the command is interrupted, a report on the
|
||||
achieved savings is printed on standard error.
|
||||
|
||||
Use `-vv` or `-vvv` to get some progress indication.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --optimise
|
||||
hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
|
||||
...
|
||||
541838819 bytes (516.74 MiB) freed by hard-linking 54143 files;
|
||||
there are 114486 files with equal contents out of 215894 files in total
|
||||
```
|
||||
|
||||
31
doc/manual/src/command-ref/nix-store/print-env.md
Normal file
31
doc/manual/src/command-ref/nix-store/print-env.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# Name
|
||||
|
||||
`nix-store --print-env` - print the build environment of a derivation
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--print-env` *drvpath*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--print-env` prints out the environment of a derivation
|
||||
in a format that can be evaluated by a shell. The command line arguments
|
||||
of the builder are placed in the variable `_args`.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
## Example
|
||||
|
||||
```console
|
||||
$ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox)
|
||||
…
|
||||
export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
|
||||
export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
|
||||
export system; system='x86_64-linux'
|
||||
export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
|
||||
```
|
||||
|
||||
220
doc/manual/src/command-ref/nix-store/query.md
Normal file
220
doc/manual/src/command-ref/nix-store/query.md
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
# Name
|
||||
|
||||
`nix-store --query` - display information about store paths
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` {`--query` | `-q`}
|
||||
{`--outputs` | `--requisites` | `-R` | `--references` |
|
||||
`--referrers` | `--referrers-closure` | `--deriver` | `-d` |
|
||||
`--graph` | `--tree` | `--binding` *name* | `-b` *name* | `--hash` |
|
||||
`--size` | `--roots`}
|
||||
[`--use-output`] [`-u`] [`--force-realise`] [`-f`]
|
||||
*paths…*
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--query` displays various bits of information about the
|
||||
store paths . The queries are described below. At most one query can be
|
||||
specified. The default query is `--outputs`.
|
||||
|
||||
The paths *paths* may also be symlinks from outside of the Nix store, to
|
||||
the Nix store. In that case, the query is applied to the target of the
|
||||
symlink.
|
||||
|
||||
# Common query options
|
||||
|
||||
- `--use-output`; `-u`\
|
||||
For each argument to the query that is a [store 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
|
||||
|
||||
# Queries
|
||||
|
||||
- `--outputs`\
|
||||
Prints out the [output paths] of the store
|
||||
derivations *paths*. These are the paths that will be produced when
|
||||
the derivation is built.
|
||||
|
||||
[output paths]: ../../glossary.md#gloss-output-path
|
||||
|
||||
- `--requisites`; `-R`\
|
||||
Prints out the [closure] of the store path *paths*.
|
||||
|
||||
[closure]: ../../glossary.md#gloss-closure
|
||||
|
||||
This query has one option:
|
||||
|
||||
- `--include-outputs`
|
||||
Also include the existing output paths of [store 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
|
||||
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
|
||||
derivation and specifying the option `--include-outputs`.
|
||||
|
||||
- `--references`\
|
||||
Prints the set of [references] of the store paths
|
||||
*paths*, that is, their immediate dependencies. (For *all*
|
||||
dependencies, use `--requisites`.)
|
||||
|
||||
[references]: ../../glossary.md#gloss-reference
|
||||
|
||||
- `--referrers`\
|
||||
Prints the set of *referrers* of the store paths *paths*, that is,
|
||||
the store paths currently existing in the Nix store that refer to
|
||||
one of *paths*. Note that contrary to the references, the set of
|
||||
referrers is not constant; it can change as store paths are added or
|
||||
removed.
|
||||
|
||||
- `--referrers-closure`\
|
||||
Prints the closure of the set of store paths *paths* under the
|
||||
referrers relation; that is, all store paths that directly or
|
||||
indirectly refer to one of *paths*. These are all the path currently
|
||||
in the Nix store that are dependent on *paths*.
|
||||
|
||||
- `--deriver`; `-d`\
|
||||
Prints the [deriver] of the store paths *paths*. If
|
||||
the path has no deriver (e.g., if it is a source file), or if the
|
||||
deriver is not known (e.g., in the case of a binary-only
|
||||
deployment), the string `unknown-deriver` is printed.
|
||||
|
||||
[deriver]: ../../glossary.md#gloss-deriver
|
||||
|
||||
- `--graph`\
|
||||
Prints the references graph of the store paths *paths* in the format
|
||||
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,
|
||||
apply it to an output path.
|
||||
|
||||
- `--tree`\
|
||||
Prints the references graph of the store paths *paths* as a nested
|
||||
ASCII tree. References are ordered by descending closure size; this
|
||||
tends to flatten the tree, making it more readable. The query only
|
||||
recurses into a store path when it is first encountered; this
|
||||
prevents a blowup of the tree representation of the graph.
|
||||
|
||||
- `--graphml`\
|
||||
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
|
||||
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
|
||||
derivation to not have the specified attribute.
|
||||
|
||||
- `--hash`\
|
||||
Prints the SHA-256 hash of the contents of the store paths *paths*
|
||||
(that is, the hash of the output of `nix-store --dump` on the given
|
||||
paths). Since the hash is stored in the Nix database, this is a fast
|
||||
operation.
|
||||
|
||||
- `--size`\
|
||||
Prints the size in bytes of the contents of the store paths *paths*
|
||||
— to be precise, the size of the output of `nix-store --dump` on
|
||||
the given paths. Note that the actual disk space required by the
|
||||
store paths may be higher, especially on filesystems with large
|
||||
cluster sizes.
|
||||
|
||||
- `--roots`\
|
||||
Prints the garbage collector roots that point, directly or
|
||||
indirectly, at the store paths *paths*.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
Print the closure (runtime dependencies) of the `svn` program in the
|
||||
current user environment:
|
||||
|
||||
```console
|
||||
$ nix-store -qR $(which svn)
|
||||
/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
|
||||
/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
|
||||
...
|
||||
```
|
||||
|
||||
Print the build-time dependencies of `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -qR $(nix-store -qd $(which svn))
|
||||
/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv
|
||||
/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh
|
||||
/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv
|
||||
... lots of other paths ...
|
||||
```
|
||||
|
||||
The difference with the previous example is that we ask the closure of
|
||||
the derivation (`-qd`), not the closure of the output path that contains
|
||||
`svn`.
|
||||
|
||||
Show the build-time dependencies as a tree:
|
||||
|
||||
```console
|
||||
$ nix-store -q --tree $(nix-store -qd $(which svn))
|
||||
/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv
|
||||
+---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh
|
||||
+---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv
|
||||
| +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash
|
||||
| +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh
|
||||
...
|
||||
```
|
||||
|
||||
Show all paths that depend on the same OpenSSL library as `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
|
||||
/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
|
||||
/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
|
||||
/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3
|
||||
/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5
|
||||
```
|
||||
|
||||
Show all paths that directly or indirectly depend on the Glibc (C
|
||||
library) used by `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
|
||||
/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
|
||||
/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4
|
||||
...
|
||||
```
|
||||
|
||||
Note that `ldd` is a command that prints out the dynamic libraries used
|
||||
by an ELF executable.
|
||||
|
||||
Make a picture of the runtime dependency graph of the current user
|
||||
environment:
|
||||
|
||||
```console
|
||||
$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps
|
||||
$ gv graph.ps
|
||||
```
|
||||
|
||||
Show every garbage collector root that points to a store path that
|
||||
depends on `svn`:
|
||||
|
||||
```console
|
||||
$ nix-store -q --roots $(which svn)
|
||||
/nix/var/nix/profiles/default-81-link
|
||||
/nix/var/nix/profiles/default-82-link
|
||||
/home/eelco/.local/state/nix/profiles/profile-97-link
|
||||
```
|
||||
|
||||
38
doc/manual/src/command-ref/nix-store/read-log.md
Normal file
38
doc/manual/src/command-ref/nix-store/read-log.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
# Name
|
||||
|
||||
`nix-store --read-log` - print build log
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` {`--read-log` | `-l`} *paths…*
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--read-log` prints the build log of the specified store
|
||||
paths on standard output. The build log is whatever the builder of a
|
||||
derivation wrote to standard output and standard error. If a store path
|
||||
is not a derivation, the deriver of the store path is used.
|
||||
|
||||
Build logs are kept in `/nix/var/log/nix/drvs`. However, there is no
|
||||
guarantee that a build log is available for any particular store path.
|
||||
For instance, if the path was downloaded as a pre-built binary through a
|
||||
substitute, then the log is unavailable.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Example
|
||||
|
||||
```console
|
||||
$ nix-store -l $(which ktorrent)
|
||||
building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1
|
||||
unpacking sources
|
||||
unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz
|
||||
ktorrent-2.2.1/
|
||||
ktorrent-2.2.1/NEWS
|
||||
...
|
||||
```
|
||||
|
||||
118
doc/manual/src/command-ref/nix-store/realise.md
Normal file
118
doc/manual/src/command-ref/nix-store/realise.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
# 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)
|
||||
```
|
||||
35
doc/manual/src/command-ref/nix-store/repair-path.md
Normal file
35
doc/manual/src/command-ref/nix-store/repair-path.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Name
|
||||
|
||||
`nix --repair-path` - re-download path from substituter
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--repair-path` *paths…*
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--repair-path` attempts to “repair” the specified paths
|
||||
by redownloading them using the available substituters. If no
|
||||
substitutes are available, then repair is not possible.
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> During repair, there is a very small time window during which the old
|
||||
> path (if it exists) is moved out of the way and replaced with the new
|
||||
> path. If repair is interrupted in between, then the system may be left
|
||||
> in a broken state (e.g., if the path contains a critical system
|
||||
> component like the GNU C Library).
|
||||
|
||||
# Example
|
||||
|
||||
```console
|
||||
$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
|
||||
path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
|
||||
expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
|
||||
got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
|
||||
|
||||
$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
|
||||
fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
|
||||
…
|
||||
```
|
||||
|
||||
18
doc/manual/src/command-ref/nix-store/restore.md
Normal file
18
doc/manual/src/command-ref/nix-store/restore.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Name
|
||||
|
||||
`nix-store --restore` - extract a Nix archive
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--restore` *path*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--restore` unpacks a NAR archive to *path*, which must
|
||||
not already exist. The archive is read from standard input.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
38
doc/manual/src/command-ref/nix-store/serve.md
Normal file
38
doc/manual/src/command-ref/nix-store/serve.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
# Name
|
||||
|
||||
`nix-store --serve` - serve local Nix store over SSH
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--serve` [`--write`]
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--serve` provides access to the Nix store over stdin and
|
||||
stdout, and is intended to be used as a means of providing Nix store
|
||||
access to a restricted ssh user.
|
||||
|
||||
The following flags are available:
|
||||
|
||||
- `--write`\
|
||||
Allow the connected client to request the realization of
|
||||
derivations. In effect, this can be used to make the host act as a
|
||||
remote builder.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
# Examples
|
||||
|
||||
To turn a host into a build server, the `authorized_keys` file can be
|
||||
used to provide build access to a given SSH public key:
|
||||
|
||||
```console
|
||||
$ cat <<EOF >>/root/.ssh/authorized_keys
|
||||
command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA...
|
||||
EOF
|
||||
```
|
||||
|
||||
29
doc/manual/src/command-ref/nix-store/verify-path.md
Normal file
29
doc/manual/src/command-ref/nix-store/verify-path.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Name
|
||||
|
||||
`nix-store --verify-path` - check path contents against Nix database
|
||||
|
||||
## Synopsis
|
||||
|
||||
`nix-store` `--verify-path` *paths…*
|
||||
|
||||
## Description
|
||||
|
||||
The operation `--verify-path` compares the contents of the given store
|
||||
paths to their cryptographic hashes stored in Nix’s database. For every
|
||||
changed path, it prints a warning message. The exit status is 0 if no
|
||||
path has changed, and 1 otherwise.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
||||
## Example
|
||||
|
||||
To verify the integrity of the `svn` command and all its dependencies:
|
||||
|
||||
```console
|
||||
$ nix-store --verify-path $(nix-store -qR $(which svn))
|
||||
```
|
||||
|
||||
36
doc/manual/src/command-ref/nix-store/verify.md
Normal file
36
doc/manual/src/command-ref/nix-store/verify.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Name
|
||||
|
||||
`nix-store --verify` - check Nix database for consistency
|
||||
|
||||
# Synopsis
|
||||
|
||||
`nix-store` `--verify` [`--check-contents`] [`--repair`]
|
||||
|
||||
# Description
|
||||
|
||||
The operation `--verify` verifies the internal consistency of the Nix
|
||||
database, and the consistency between the Nix database and the Nix
|
||||
store. Any inconsistencies encountered are automatically repaired.
|
||||
Inconsistencies are generally the result of the Nix store or database
|
||||
being modified by non-Nix tools, or of bugs in Nix itself.
|
||||
|
||||
This operation has the following options:
|
||||
|
||||
- `--check-contents`\
|
||||
Checks that the contents of every valid store path has not been
|
||||
altered by computing a SHA-256 hash of the contents and comparing it
|
||||
with the hash stored in the Nix database at build time. Paths that
|
||||
have been modified are printed out. For large stores,
|
||||
`--check-contents` is obviously quite slow.
|
||||
|
||||
- `--repair`\
|
||||
If any valid path is missing from the store, or (if
|
||||
`--check-contents` is given) the contents of a valid path has been
|
||||
modified, then try to repair the path by redownloading it. See
|
||||
`nix-store --repair-path` for details.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
||||
|
||||
{{#include ../env-common.md}}
|
||||
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
Most Nix commands accept the following command-line options:
|
||||
|
||||
- [`--help`]{#opt-help}\
|
||||
- <span id="opt-help">[`--help`](#opt-help)</span>\
|
||||
Prints out a summary of the command syntax and exits.
|
||||
|
||||
- [`--version`]{#opt-version}\
|
||||
- <span id="opt-version">[`--version`](#opt-version)</span>\
|
||||
Prints out the Nix version number on standard output and exits.
|
||||
|
||||
- [`--verbose`]{#opt-verbose} / `-v`\
|
||||
- <span id="opt-verbose">[`--verbose`](#opt-verbose)</span> / `-v`\
|
||||
Increases the level of verbosity of diagnostic messages printed on
|
||||
standard error. For each Nix operation, the information printed on
|
||||
standard output is well-defined; any diagnostic information is
|
||||
|
|
@ -37,14 +37,14 @@ Most Nix commands accept the following command-line options:
|
|||
- 5\
|
||||
“Vomit”: print vast amounts of debug information.
|
||||
|
||||
- [`--quiet`]{#opt-quiet}\
|
||||
- <span id="opt-quiet">[`--quiet`](#opt-quiet)</span>\
|
||||
Decreases the level of verbosity of diagnostic messages printed on
|
||||
standard error. This is the inverse option to `-v` / `--verbose`.
|
||||
|
||||
This option may be specified repeatedly. See the previous verbosity
|
||||
levels list.
|
||||
|
||||
- [`--log-format`]{#opt-log-format} *format*\
|
||||
- <span id="opt-log-format">[`--log-format`](#opt-log-format)</span> *format*\
|
||||
This option can be used to change the output of the log format, with
|
||||
*format* being one of:
|
||||
|
||||
|
|
@ -66,14 +66,14 @@ Most Nix commands accept the following command-line options:
|
|||
- bar-with-logs\
|
||||
Display the raw logs, with the progress bar at the bottom.
|
||||
|
||||
- [`--no-build-output`]{#opt-no-build-output} / `-Q`\
|
||||
- <span id="opt-no-build-output">[`--no-build-output`](#opt-no-build-output)</span> / `-Q`\
|
||||
By default, output written by builders to standard output and
|
||||
standard error is echoed to the Nix command's standard error. This
|
||||
option suppresses this behaviour. Note that the builder's standard
|
||||
output and error are always written to a log file in
|
||||
`prefix/nix/var/log/nix`.
|
||||
|
||||
- [`--max-jobs`]{#opt-max-jobs} / `-j` *number*\
|
||||
- <span id="opt-max-jobs">[`--max-jobs`](#opt-max-jobs)</span> / `-j` *number*\
|
||||
Sets the maximum number of build jobs that Nix will perform in
|
||||
parallel to the specified number. Specify `auto` to use the number
|
||||
of CPUs in the system. The default is specified by the `max-jobs`
|
||||
|
|
@ -83,7 +83,7 @@ Most Nix commands accept the following command-line options:
|
|||
Setting it to `0` disallows building on the local machine, which is
|
||||
useful when you want builds to happen only on remote builders.
|
||||
|
||||
- [`--cores`]{#opt-cores}\
|
||||
- <span id="opt-cores">[`--cores`](#opt-cores)</span>\
|
||||
Sets the value of the `NIX_BUILD_CORES` environment variable in
|
||||
the invocation of builders. Builders can use this variable at
|
||||
their discretion to control the maximum amount of parallelism. For
|
||||
|
|
@ -94,18 +94,18 @@ Most Nix commands accept the following command-line options:
|
|||
means that the builder should use all available CPU cores in the
|
||||
system.
|
||||
|
||||
- [`--max-silent-time`]{#opt-max-silent-time}\
|
||||
- <span id="opt-max-silent-time">[`--max-silent-time`](#opt-max-silent-time)</span>\
|
||||
Sets the maximum number of seconds that a builder can go without
|
||||
producing any data on standard output or standard error. The
|
||||
default is specified by the `max-silent-time` configuration
|
||||
setting. `0` means no time-out.
|
||||
|
||||
- [`--timeout`]{#opt-timeout}\
|
||||
- <span id="opt-timeout">[`--timeout`](#opt-timeout)</span>\
|
||||
Sets the maximum number of seconds that a builder can run. The
|
||||
default is specified by the `timeout` configuration setting. `0`
|
||||
means no timeout.
|
||||
|
||||
- [`--keep-going`]{#opt-keep-going} / `-k`\
|
||||
- <span id="opt-keep-going">[`--keep-going`](#opt-keep-going)</span> / `-k`\
|
||||
Keep going in case of failed builds, to the greatest extent
|
||||
possible. That is, if building an input of some derivation fails,
|
||||
Nix will still build the other inputs, but not the derivation
|
||||
|
|
@ -113,13 +113,13 @@ Most Nix commands accept the following command-line options:
|
|||
for builds of substitutes), possibly killing builds in progress (in
|
||||
case of parallel or distributed builds).
|
||||
|
||||
- [`--keep-failed`]{#opt-keep-failed} / `-K`\
|
||||
- <span id="opt-keep-failed">[`--keep-failed`](#opt-keep-failed)</span> / `-K`\
|
||||
Specifies that in case of a build failure, the temporary directory
|
||||
(usually in `/tmp`) in which the build takes place should not be
|
||||
deleted. The path of the build directory is printed as an
|
||||
informational message.
|
||||
|
||||
- [`--fallback`]{#opt-fallback}\
|
||||
- <span id="opt-fallback">[`--fallback`](#opt-fallback)</span>\
|
||||
Whenever Nix attempts to build a derivation for which substitutes
|
||||
are known for each output path, but realising the output paths
|
||||
through the substitutes fails, fall back on building the derivation.
|
||||
|
|
@ -134,18 +134,18 @@ Most Nix commands accept the following command-line options:
|
|||
failure in obtaining the substitutes to lead to a full build from
|
||||
source (with the related consumption of resources).
|
||||
|
||||
- [`--readonly-mode`]{#opt-readonly-mode}\
|
||||
- <span id="opt-readonly-mode">[`--readonly-mode`](#opt-readonly-mode)</span>\
|
||||
When this option is used, no attempt is made to open the Nix
|
||||
database. Most Nix operations do need database access, so those
|
||||
operations will fail.
|
||||
|
||||
- [`--arg`]{#opt-arg} *name* *value*\
|
||||
- <span id="opt-arg">[`--arg`](#opt-arg)</span> *name* *value*\
|
||||
This option is accepted by `nix-env`, `nix-instantiate`,
|
||||
`nix-shell` and `nix-build`. When evaluating Nix expressions, the
|
||||
expression evaluator will automatically try to call functions that
|
||||
it encounters. It can automatically call functions for which every
|
||||
argument has a [default
|
||||
value](../language/constructs.md#functions) (e.g.,
|
||||
value](@docroot@/language/constructs.md#functions) (e.g.,
|
||||
`{ argName ? defaultValue }: ...`). With `--arg`, you can also
|
||||
call functions that have arguments without a default value (or
|
||||
override a default value). That is, if the evaluator encounters a
|
||||
|
|
@ -164,26 +164,26 @@ Most Nix commands accept the following command-line options:
|
|||
|
||||
So if you call this Nix expression (e.g., when you do `nix-env -iA
|
||||
pkgname`), the function will be called automatically using the
|
||||
value [`builtins.currentSystem`](../language/builtins.md) for
|
||||
value [`builtins.currentSystem`](@docroot@/language/builtins.md) for
|
||||
the `system` argument. You can override this using `--arg`, e.g.,
|
||||
`nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that
|
||||
since the argument is a Nix string literal, you have to escape the
|
||||
quotes.)
|
||||
|
||||
- [`--argstr`]{#opt-argstr} *name* *value*\
|
||||
- <span id="opt-argstr">[`--argstr`](#opt-argstr)</span> *name* *value*\
|
||||
This option is like `--arg`, only the value is not a Nix
|
||||
expression but a string. So instead of `--arg system
|
||||
\"i686-linux\"` (the outer quotes are to keep the shell happy) you
|
||||
can say `--argstr system i686-linux`.
|
||||
|
||||
- [`--attr`]{#opt-attr} / `-A` *attrPath*\
|
||||
- <span id="opt-attr">[`--attr`](#opt-attr)</span> / `-A` *attrPath*\
|
||||
Select an attribute from the top-level Nix expression being
|
||||
evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
|
||||
`nix-shell` only.) The *attribute path* *attrPath* is a sequence
|
||||
of attribute names separated by dots. For instance, given a
|
||||
top-level Nix expression *e*, the attribute path `xorg.xorgserver`
|
||||
would cause the expression `e.xorg.xorgserver` to be used. See
|
||||
[`nix-env --install`](nix-env.md#operation---install) for some
|
||||
[`nix-env --install`](@docroot@/command-ref/nix-env/install.md) for some
|
||||
concrete examples.
|
||||
|
||||
In addition to attribute names, you can also specify array indices.
|
||||
|
|
@ -191,7 +191,7 @@ Most Nix commands accept the following command-line options:
|
|||
attribute of the fourth element of the array in the `foo` attribute
|
||||
of the top-level expression.
|
||||
|
||||
- [`--expr`]{#opt-expr} / `-E`\
|
||||
- <span id="opt-expr">[`--expr`](#opt-expr)</span> / `-E`\
|
||||
Interpret the command line arguments as a list of Nix expressions to
|
||||
be parsed and evaluated, rather than as a list of file names of Nix
|
||||
expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.)
|
||||
|
|
@ -202,17 +202,17 @@ Most Nix commands accept the following command-line options:
|
|||
use, give your expression to the `nix-shell -p` convenience flag
|
||||
instead.
|
||||
|
||||
- [`-I`]{#opt-I} *path*\
|
||||
- <span id="opt-I">[`-I`](#opt-I)</span> *path*\
|
||||
Add a path to the Nix expression search path. This option may be
|
||||
given multiple times. See the `NIX_PATH` environment variable for
|
||||
information on the semantics of the Nix search path. Paths added
|
||||
through `-I` take precedence over `NIX_PATH`.
|
||||
|
||||
- [`--option`]{#opt-option} *name* *value*\
|
||||
- <span id="opt-option">[`--option`](#opt-option)</span> *name* *value*\
|
||||
Set the Nix configuration option *name* to *value*. This overrides
|
||||
settings in the Nix configuration file (see nix.conf5).
|
||||
|
||||
- [`--repair`]{#opt-repair}\
|
||||
- <span id="opt-repair">[`--repair`](#opt-repair)</span>\
|
||||
Fix corrupted or missing store paths by redownloading or rebuilding
|
||||
them. Note that this is slow because it requires computing a
|
||||
cryptographic hash of the contents of every path in the closure of
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@
|
|||
|
||||
This means either running the `builder` executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter].
|
||||
|
||||
See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](./command-ref/nix-store.md#operation---realise).
|
||||
See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md).
|
||||
|
||||
See [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental).
|
||||
|
||||
|
|
|
|||
|
|
@ -198,8 +198,7 @@ Derivations can declare some infrequently used optional attributes.
|
|||
|
||||
- `"recursive"`\
|
||||
The hash is computed over the NAR archive dump of the output
|
||||
(i.e., the result of [`nix-store
|
||||
--dump`](../command-ref/nix-store.md#operation---dump)). In
|
||||
(i.e., the result of [`nix-store --dump`](@docroot@/command-ref/nix-store/dump.md)). In
|
||||
this case, the output can be anything, including a directory
|
||||
tree.
|
||||
|
||||
|
|
|
|||
|
|
@ -31,3 +31,11 @@
|
|||
* The experimental command `nix describe-stores` has been removed.
|
||||
|
||||
* Nix stores and their settings are now documented in [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md).
|
||||
|
||||
* Documentation for operations of `nix-store` and `nix-env` are now available on separate pages of the manual.
|
||||
They include all common options that can be specified and common environment variables that affect these commands.
|
||||
|
||||
These pages can be viewed offline with `man` using
|
||||
|
||||
* `man nix-store-<operation>` and `man nix-env-<operation>`
|
||||
* `nix-store --help --<operation>` and `nix-env --help --<operation>`.
|
||||
|
|
|
|||
|
|
@ -1387,6 +1387,8 @@ static int main_nix_env(int argc, char * * argv)
|
|||
{
|
||||
Strings opFlags, opArgs;
|
||||
Operation op = 0;
|
||||
std::string opName;
|
||||
bool showHelp = false;
|
||||
RepairFlag repair = NoRepair;
|
||||
std::string file;
|
||||
|
||||
|
|
@ -1426,37 +1428,59 @@ static int main_nix_env(int argc, char * * argv)
|
|||
Operation oldOp = op;
|
||||
|
||||
if (*arg == "--help")
|
||||
showManPage("nix-env");
|
||||
showHelp = true;
|
||||
else if (*arg == "--version")
|
||||
op = opVersion;
|
||||
else if (*arg == "--install" || *arg == "-i")
|
||||
else if (*arg == "--install" || *arg == "-i") {
|
||||
op = opInstall;
|
||||
opName = "-install";
|
||||
}
|
||||
else if (*arg == "--force-name") // undocumented flag for nix-install-package
|
||||
globals.forceName = getArg(*arg, arg, end);
|
||||
else if (*arg == "--uninstall" || *arg == "-e")
|
||||
else if (*arg == "--uninstall" || *arg == "-e") {
|
||||
op = opUninstall;
|
||||
else if (*arg == "--upgrade" || *arg == "-u")
|
||||
opName = "-uninstall";
|
||||
}
|
||||
else if (*arg == "--upgrade" || *arg == "-u") {
|
||||
op = opUpgrade;
|
||||
else if (*arg == "--set-flag")
|
||||
opName = "-upgrade";
|
||||
}
|
||||
else if (*arg == "--set-flag") {
|
||||
op = opSetFlag;
|
||||
else if (*arg == "--set")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--set") {
|
||||
op = opSet;
|
||||
else if (*arg == "--query" || *arg == "-q")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--query" || *arg == "-q") {
|
||||
op = opQuery;
|
||||
opName = "-query";
|
||||
}
|
||||
else if (*arg == "--profile" || *arg == "-p")
|
||||
globals.profile = absPath(getArg(*arg, arg, end));
|
||||
else if (*arg == "--file" || *arg == "-f")
|
||||
file = getArg(*arg, arg, end);
|
||||
else if (*arg == "--switch-profile" || *arg == "-S")
|
||||
else if (*arg == "--switch-profile" || *arg == "-S") {
|
||||
op = opSwitchProfile;
|
||||
else if (*arg == "--switch-generation" || *arg == "-G")
|
||||
opName = "-switch-profile";
|
||||
}
|
||||
else if (*arg == "--switch-generation" || *arg == "-G") {
|
||||
op = opSwitchGeneration;
|
||||
else if (*arg == "--rollback")
|
||||
opName = "-switch-generation";
|
||||
}
|
||||
else if (*arg == "--rollback") {
|
||||
op = opRollback;
|
||||
else if (*arg == "--list-generations")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--list-generations") {
|
||||
op = opListGenerations;
|
||||
else if (*arg == "--delete-generations")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--delete-generations") {
|
||||
op = opDeleteGenerations;
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--dry-run") {
|
||||
printInfo("(dry run; not doing anything)");
|
||||
globals.dryRun = true;
|
||||
|
|
@ -1485,6 +1509,7 @@ static int main_nix_env(int argc, char * * argv)
|
|||
|
||||
myArgs.parseCmdline(argvToStrings(argc, argv));
|
||||
|
||||
if (showHelp) showManPage("nix-env" + opName);
|
||||
if (!op) throw UsageError("no operation specified");
|
||||
|
||||
auto store = openStore();
|
||||
|
|
|
|||
|
|
@ -1024,62 +1024,104 @@ static int main_nix_store(int argc, char * * argv)
|
|||
Strings opFlags, opArgs;
|
||||
Operation op = 0;
|
||||
bool readFromStdIn = false;
|
||||
std::string opName;
|
||||
bool showHelp = false;
|
||||
|
||||
parseCmdLine(argc, argv, [&](Strings::iterator & arg, const Strings::iterator & end) {
|
||||
Operation oldOp = op;
|
||||
|
||||
if (*arg == "--help")
|
||||
showManPage("nix-store");
|
||||
showHelp = true;
|
||||
else if (*arg == "--version")
|
||||
op = opVersion;
|
||||
else if (*arg == "--realise" || *arg == "--realize" || *arg == "-r")
|
||||
else if (*arg == "--realise" || *arg == "--realize" || *arg == "-r") {
|
||||
op = opRealise;
|
||||
else if (*arg == "--add" || *arg == "-A")
|
||||
opName = "-realise";
|
||||
}
|
||||
else if (*arg == "--add" || *arg == "-A"){
|
||||
op = opAdd;
|
||||
else if (*arg == "--add-fixed")
|
||||
opName = "-add";
|
||||
}
|
||||
else if (*arg == "--add-fixed") {
|
||||
op = opAddFixed;
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--print-fixed-path")
|
||||
op = opPrintFixedPath;
|
||||
else if (*arg == "--delete")
|
||||
else if (*arg == "--delete") {
|
||||
op = opDelete;
|
||||
else if (*arg == "--query" || *arg == "-q")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--query" || *arg == "-q") {
|
||||
op = opQuery;
|
||||
else if (*arg == "--print-env")
|
||||
opName = "-query";
|
||||
}
|
||||
else if (*arg == "--print-env") {
|
||||
op = opPrintEnv;
|
||||
else if (*arg == "--read-log" || *arg == "-l")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--read-log" || *arg == "-l") {
|
||||
op = opReadLog;
|
||||
else if (*arg == "--dump-db")
|
||||
opName = "-read-log";
|
||||
}
|
||||
else if (*arg == "--dump-db") {
|
||||
op = opDumpDB;
|
||||
else if (*arg == "--load-db")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--load-db") {
|
||||
op = opLoadDB;
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--register-validity")
|
||||
op = opRegisterValidity;
|
||||
else if (*arg == "--check-validity")
|
||||
op = opCheckValidity;
|
||||
else if (*arg == "--gc")
|
||||
else if (*arg == "--gc") {
|
||||
op = opGC;
|
||||
else if (*arg == "--dump")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--dump") {
|
||||
op = opDump;
|
||||
else if (*arg == "--restore")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--restore") {
|
||||
op = opRestore;
|
||||
else if (*arg == "--export")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--export") {
|
||||
op = opExport;
|
||||
else if (*arg == "--import")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--import") {
|
||||
op = opImport;
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--init")
|
||||
op = opInit;
|
||||
else if (*arg == "--verify")
|
||||
else if (*arg == "--verify") {
|
||||
op = opVerify;
|
||||
else if (*arg == "--verify-path")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--verify-path") {
|
||||
op = opVerifyPath;
|
||||
else if (*arg == "--repair-path")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--repair-path") {
|
||||
op = opRepairPath;
|
||||
else if (*arg == "--optimise" || *arg == "--optimize")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--optimise" || *arg == "--optimize") {
|
||||
op = opOptimise;
|
||||
else if (*arg == "--serve")
|
||||
opName = "-optimise";
|
||||
}
|
||||
else if (*arg == "--serve") {
|
||||
op = opServe;
|
||||
else if (*arg == "--generate-binary-cache-key")
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--generate-binary-cache-key") {
|
||||
op = opGenerateBinaryCacheKey;
|
||||
opName = arg->substr(1);
|
||||
}
|
||||
else if (*arg == "--add-root")
|
||||
gcRoot = absPath(getArg(*arg, arg, end));
|
||||
else if (*arg == "--stdin" && !isatty(STDIN_FILENO))
|
||||
|
|
@ -1109,6 +1151,7 @@ static int main_nix_store(int argc, char * * argv)
|
|||
return true;
|
||||
});
|
||||
|
||||
if (showHelp) showManPage("nix-store" + opName);
|
||||
if (!op) throw UsageError("no operation specified");
|
||||
|
||||
if (op != opDump && op != opRestore) /* !!! hack */
|
||||
|
|
|
|||
Loading…
Reference in a new issue