mirror of
https://github.com/privatevoid-net/nix-super.git
synced 2024-11-25 23:36:16 +02:00
Convert commands
This commit is contained in:
Eelco Dolstra
parent
efdb89994c
commit
504b7abc45
15 changed files with 2960 additions and 4 deletions
|
|
@ -47,8 +47,19 @@
|
|||
- [Command Reference](command-ref/command-ref.md)
|
||||
- [Common Options](command-ref/opt-common.md)
|
||||
- [Common Environment Variables](command-ref/env-common.md)
|
||||
- [Main Commands](command-ref/main-commands.md)
|
||||
- [nix-env](command-ref/nix-env.md)
|
||||
- [nix-build](command-ref/nix-build.md)
|
||||
- [nix-shell](command-ref/nix-shell.md)
|
||||
- [nix-store](command-ref/nix-store.md)
|
||||
- [Utilities](command-ref/utilities.md)
|
||||
- [nix-channel](command-ref/nix-channel.md)
|
||||
- [nix-collect-garbage](command-ref/nix-collect-garbage.md)
|
||||
- [nix-copy-closure](command-ref/nix-copy-closure.md)
|
||||
- [nix-daemon](command-ref/nix-daemon.md)
|
||||
- [nix-hash](command-ref/nix-hash.md)
|
||||
- [nix-instantiate](command-ref/nix-instantiate.md)
|
||||
- [nix-prefetch-url](command-ref/nix-prefetch-url.md)
|
||||
- [Files](command-ref/files.md)
|
||||
- [nix.conf](command-ref/conf-file.md)
|
||||
- [Glossary](glossary.md)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,2 @@
|
|||
# Command Reference
|
||||
|
||||
This section lists commands and options that you can use when you
|
||||
work with Nix.
|
||||
This section lists commands and options that you can use when you work
|
||||
with Nix.
|
||||
|
|
|
|||
4
doc/manual/src/command-ref/main-commands.md
Normal file
4
doc/manual/src/command-ref/main-commands.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# Main Commands
|
||||
|
||||
This section lists commands and options that you can use when you work
|
||||
with Nix.
|
||||
130
doc/manual/src/command-ref/nix-build.md
Normal file
130
doc/manual/src/command-ref/nix-build.md
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
nix-build
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-build
|
||||
|
||||
build a Nix expression
|
||||
|
||||
nix-build
|
||||
|
||||
\--arg
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--argstr
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--attr
|
||||
|
||||
\-A
|
||||
|
||||
attrPath
|
||||
|
||||
\--no-out-link
|
||||
|
||||
\--dry-run
|
||||
|
||||
\--out-link
|
||||
|
||||
\-o
|
||||
|
||||
outlink
|
||||
|
||||
paths
|
||||
|
||||
# Description
|
||||
|
||||
The `nix-build` command builds the derivations described by the Nix
|
||||
expressions in paths. If the build succeeds, it places a symlink to the
|
||||
result in the current directory. The symlink is called `result`. If
|
||||
there are multiple Nix expressions, or the Nix expressions evaluate to
|
||||
multiple derivations, multiple sequentially numbered symlinks are
|
||||
created (`result`, `result-2`, and so on).
|
||||
|
||||
If no paths are specified, then `nix-build` will use `default.nix` in
|
||||
the current directory, if it exists.
|
||||
|
||||
If an element of paths 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`.
|
||||
|
||||
`nix-build` is essentially a wrapper around
|
||||
[`nix-instantiate`](#sec-nix-instantiate) (to translate a high-level Nix
|
||||
expression to a low-level store derivation) and [`nix-store
|
||||
--realise`](#rsec-nix-store-realise) (to build the store derivation).
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> The result of the build is automatically registered as a root of the
|
||||
> Nix garbage collector. This root disappears automatically when the
|
||||
> `result` symlink is deleted or renamed. So don’t rename the symlink.
|
||||
|
||||
# Options
|
||||
|
||||
All options not listed here are passed to `nix-store
|
||||
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
|
||||
`nix-instantiate`. See also [???](#sec-common-options).
|
||||
|
||||
- `--no-out-link`
|
||||
Do not create a symlink to the output path. Note that as a result
|
||||
the output does not become a root of the garbage collector, and so
|
||||
might be deleted by `nix-store
|
||||
--gc`.
|
||||
|
||||
- `--dry-run`
|
||||
Show what store paths would be built or downloaded.
|
||||
|
||||
- `--out-link` / `-o` outlink
|
||||
Change the name of the symlink to the output path created from
|
||||
`result` to outlink.
|
||||
|
||||
The following common options are supported:
|
||||
|
||||
# Examples
|
||||
|
||||
$ nix-build '<nixpkgs>' -A firefox
|
||||
store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
|
||||
/nix/store/d18hyl92g30l...-firefox-1.5.0.7
|
||||
|
||||
$ ls -l result
|
||||
lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7
|
||||
|
||||
$ ls ./result/bin/
|
||||
firefox firefox-config
|
||||
|
||||
If a derivation has multiple outputs, `nix-build` will build the default
|
||||
(first) output. You can also build all outputs:
|
||||
|
||||
$ nix-build '<nixpkgs>' -A openssl.all
|
||||
|
||||
This will create a symlink for each output named `result-outputname`.
|
||||
The suffix is omitted if the output name is `out`. So if `openssl` has
|
||||
outputs `out`, `bin` and `man`, `nix-build` will create symlinks
|
||||
`result`, `result-bin` and `result-man`. It’s also possible to build a
|
||||
specific output:
|
||||
|
||||
$ nix-build '<nixpkgs>' -A openssl.man
|
||||
|
||||
This will create a symlink `result-man`.
|
||||
|
||||
Build a Nix expression given on the command line:
|
||||
|
||||
$ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
|
||||
$ cat ./result
|
||||
bar
|
||||
|
||||
Build the GNU Hello package from the latest revision of the master
|
||||
branch of Nixpkgs:
|
||||
|
||||
$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
|
||||
|
||||
# Environment variables
|
||||
116
doc/manual/src/command-ref/nix-channel.md
Normal file
116
doc/manual/src/command-ref/nix-channel.md
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
nix-channel
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-channel
|
||||
|
||||
manage Nix channels
|
||||
|
||||
nix-channel
|
||||
|
||||
\--add
|
||||
|
||||
url
|
||||
|
||||
name
|
||||
|
||||
\--remove
|
||||
|
||||
name
|
||||
|
||||
\--list
|
||||
|
||||
\--update
|
||||
|
||||
names
|
||||
|
||||
\--rollback
|
||||
|
||||
generation
|
||||
|
||||
# Description
|
||||
|
||||
A Nix channel is a mechanism that allows you to automatically stay
|
||||
up-to-date with a set of pre-built Nix expressions. A Nix channel is
|
||||
just a URL that points to a place containing a set of Nix expressions.
|
||||
See also [???](#sec-channels).
|
||||
|
||||
To see the list of official NixOS channels, visit
|
||||
<https://nixos.org/channels>.
|
||||
|
||||
This command has the following operations:
|
||||
|
||||
- `--add` url \[name\]
|
||||
Adds a channel named name with URL url to the list of subscribed
|
||||
channels. If name is omitted, it defaults to the last component of
|
||||
url, with the suffixes `-stable` or `-unstable` removed.
|
||||
|
||||
- `--remove` name
|
||||
Removes the channel named name from the list of subscribed channels.
|
||||
|
||||
- `--list`
|
||||
Prints the names and URLs of all subscribed channels on standard
|
||||
output.
|
||||
|
||||
- `--update` \[names…\]
|
||||
Downloads the Nix expressions of all subscribed channels (or only
|
||||
those included in names if specified) and makes them the default for
|
||||
`nix-env` operations (by symlinking them from the directory
|
||||
`~/.nix-defexpr`).
|
||||
|
||||
- `--rollback` \[generation\]
|
||||
Reverts the previous call to `nix-channel
|
||||
--update`. Optionally, you can specify a specific channel generation
|
||||
number to restore.
|
||||
|
||||
Note that `--add` does not automatically perform an update.
|
||||
|
||||
The list of subscribed channels is stored in `~/.nix-channels`.
|
||||
|
||||
# Examples
|
||||
|
||||
To subscribe to the Nixpkgs channel and install the GNU Hello package:
|
||||
|
||||
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
|
||||
$ nix-channel --update
|
||||
$ nix-env -iA nixpkgs.hello
|
||||
|
||||
You can revert channel updates using `--rollback`:
|
||||
|
||||
$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
|
||||
"14.04.527.0e935f1"
|
||||
|
||||
$ nix-channel --rollback
|
||||
switching from generation 483 to 482
|
||||
|
||||
$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
|
||||
"14.04.526.dbadfad"
|
||||
|
||||
# Files
|
||||
|
||||
- `/nix/var/nix/profiles/per-user/username/channels`
|
||||
`nix-channel` uses a `nix-env` profile to keep track of previous
|
||||
versions of the subscribed channels. Every time you run `nix-channel
|
||||
--update`, a new channel generation (that is, a symlink to the
|
||||
channel Nix expressions in the Nix store) is created. This enables
|
||||
`nix-channel --rollback` to revert to previous versions.
|
||||
|
||||
- `~/.nix-defexpr/channels`
|
||||
This is a symlink to
|
||||
`/nix/var/nix/profiles/per-user/username/channels`. It ensures that
|
||||
`nix-env` can find your channels. In a multi-user installation, you
|
||||
may also have `~/.nix-defexpr/channels_root`, which links to the
|
||||
channels of the root user.
|
||||
|
||||
# Channel format
|
||||
|
||||
A channel URL should point to a directory containing the following
|
||||
files:
|
||||
|
||||
- `nixexprs.tar.xz`
|
||||
A tarball containing Nix expressions and files referenced by them
|
||||
(such as build scripts and patches). At the top level, the tarball
|
||||
should contain a single directory. That directory must contain a
|
||||
file `default.nix` that serves as the channel’s “entry point”.
|
||||
46
doc/manual/src/command-ref/nix-collect-garbage.md
Normal file
46
doc/manual/src/command-ref/nix-collect-garbage.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
nix-collect-garbage
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-collect-garbage
|
||||
|
||||
delete unreachable store paths
|
||||
|
||||
nix-collect-garbage
|
||||
|
||||
\--delete-old
|
||||
|
||||
\-d
|
||||
|
||||
\--delete-older-than
|
||||
|
||||
period
|
||||
|
||||
\--max-freed
|
||||
|
||||
bytes
|
||||
|
||||
\--dry-run
|
||||
|
||||
# Description
|
||||
|
||||
The command `nix-collect-garbage` is mostly an alias of [`nix-store
|
||||
--gc`](#rsec-nix-store-gc), 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` by invoking
|
||||
`nix-env --delete-generations old` on all profiles (of course, this
|
||||
makes rollbacks to previous configurations impossible); and
|
||||
`--delete-older-than` period, where period is a value such as `30d`,
|
||||
which deletes all generations older than the specified number of days in
|
||||
all profiles in `/nix/var/nix/profiles` (except for the generations that
|
||||
were active at that point in time).
|
||||
|
||||
# Example
|
||||
|
||||
To delete from the Nix store everything that is not used by the current
|
||||
generations of each profile, do
|
||||
|
||||
$ nix-collect-garbage -d
|
||||
17
doc/manual/src/command-ref/nix-daemon.md
Normal file
17
doc/manual/src/command-ref/nix-daemon.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
nix-daemon
|
||||
|
||||
8
|
||||
|
||||
Nix
|
||||
|
||||
nix-daemon
|
||||
|
||||
Nix multi-user support daemon
|
||||
|
||||
nix-daemon
|
||||
|
||||
# Description
|
||||
|
||||
The Nix daemon is necessary in multi-user Nix installations. It performs
|
||||
build actions and other operations on the Nix store on behalf of
|
||||
unprivileged users.
|
||||
926
doc/manual/src/command-ref/nix-env.md
Normal file
926
doc/manual/src/command-ref/nix-env.md
Normal file
|
|
@ -0,0 +1,926 @@
|
|||
nix-env
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-env
|
||||
|
||||
manipulate or query Nix user environments
|
||||
|
||||
nix-env
|
||||
|
||||
\--arg
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--argstr
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--file
|
||||
|
||||
\-f
|
||||
|
||||
path
|
||||
|
||||
\--profile
|
||||
|
||||
\-p
|
||||
|
||||
path
|
||||
|
||||
\--system-filter
|
||||
|
||||
system
|
||||
|
||||
\--dry-run
|
||||
|
||||
operation
|
||||
|
||||
options
|
||||
|
||||
arguments
|
||||
|
||||
# Description
|
||||
|
||||
The command `nix-env` is used to manipulate Nix user environments. User
|
||||
environments are sets of software packages available to a user at some
|
||||
point in time. In other words, they are a synthesised view of the
|
||||
programs available in the Nix store. There may be many user
|
||||
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.
|
||||
|
||||
# Selectors
|
||||
|
||||
Several commands, such as `nix-env -q` and `nix-env -i`, take a list of
|
||||
arguments that specify the packages on which to operate. These are
|
||||
extended regular expressions that must match the entire name of the
|
||||
package. (For details on regular expressions, see regex7.) The match is
|
||||
case-sensitive. The regular expression can optionally be followed by a
|
||||
dash and a version number; if omitted, any version of the package will
|
||||
match. Here are some examples:
|
||||
|
||||
- `firefox`
|
||||
Matches the package name `firefox` and any version.
|
||||
|
||||
- `firefox-32.0`
|
||||
Matches the package name `firefox` and version `32.0`.
|
||||
|
||||
- `gtk\\+`
|
||||
Matches the package name `gtk+`. The `+` character must be escaped
|
||||
using a backslash to prevent it from being interpreted as a
|
||||
quantifier, and the backslash must be escaped in turn with another
|
||||
backslash to ensure that the shell passes it on.
|
||||
|
||||
- `.\*`
|
||||
Matches any package name. This is the default for most commands.
|
||||
|
||||
- `'.*zip.*'`
|
||||
Matches any package name containing the string `zip`. Note the dots:
|
||||
`'*zip*'` does not work, because in a regular expression, the
|
||||
character `*` is interpreted as a quantifier.
|
||||
|
||||
- `'.*(firefox|chromium).*'`
|
||||
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. See also [???](#sec-common-options).
|
||||
|
||||
- `--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](#gloss-substitute) (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`
|
||||
The source for the default Nix expressions used by the `--install`,
|
||||
`--upgrade`, and `--query
|
||||
--available` operations to obtain derivations. The `--file` option
|
||||
may be used to override this default.
|
||||
|
||||
If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If
|
||||
the expression is a set, it is used as the default Nix expression.
|
||||
If the expression is a function, an empty set is passed as argument
|
||||
and the return value is used as the default Nix expression.
|
||||
|
||||
If `~/.nix-defexpr` is a directory containing a `default.nix` file,
|
||||
that file is loaded as in the above paragraph.
|
||||
|
||||
If `~/.nix-defexpr` is a directory without a `default.nix` file,
|
||||
then its contents (both files and subdirectories) are loaded as Nix
|
||||
expressions. The expressions are combined into a single set, each
|
||||
expression under an attribute with the same name as the original
|
||||
file or subdirectory.
|
||||
|
||||
For example, if `~/.nix-defexpr` contains two files, `foo.nix` and
|
||||
`bar.nix`, then the default Nix expression will essentially be
|
||||
|
||||
{
|
||||
foo = import ~/.nix-defexpr/foo.nix;
|
||||
bar = import ~/.nix-defexpr/bar.nix;
|
||||
}
|
||||
|
||||
The file `manifest.nix` is always ignored. Subdirectories without a
|
||||
`default.nix` file are traversed recursively in search of more Nix
|
||||
expressions, but the names of these intermediate directories are not
|
||||
added to the attribute paths of the default Nix expression.
|
||||
|
||||
The command `nix-channel` places symlinks to the downloaded Nix
|
||||
expressions from each subscribed channel in this directory.
|
||||
|
||||
- `~/.nix-profile`
|
||||
A symbolic link to the user's current profile. By default, this
|
||||
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
|
||||
|
||||
\--preserve-installed
|
||||
|
||||
\-P
|
||||
|
||||
\--remove-all
|
||||
|
||||
\-r
|
||||
|
||||
args
|
||||
|
||||
## 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`](#opt-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](#ss-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, then these are
|
||||
[realised](#rsec-nix-store-realise), and the resulting output paths
|
||||
are installed.
|
||||
|
||||
- If args are store paths that are not store derivations, then these
|
||||
are [realised](#rsec-nix-store-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 specific version of `gcc` from the active Nix expression:
|
||||
|
||||
$ nix-env --install gcc-3.3.2
|
||||
installing `gcc-3.3.2'
|
||||
uninstalling `gcc-3.1'
|
||||
|
||||
Note the previously installed version is removed, since
|
||||
`--preserve-installed` was not specified.
|
||||
|
||||
To install an arbitrary version:
|
||||
|
||||
$ nix-env --install gcc
|
||||
installing `gcc-3.3.2'
|
||||
|
||||
To install using a specific attribute:
|
||||
|
||||
$ nix-env -i -A gcc40mips
|
||||
$ nix-env -i -A xorg.xorgserver
|
||||
|
||||
To install all derivations in the Nix expression `foo.nix`:
|
||||
|
||||
$ nix-env -f ~/foo.nix -i '.*'
|
||||
|
||||
To copy the store path with symbolic name `gcc` from another profile:
|
||||
|
||||
$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
|
||||
|
||||
To install a specific store derivation (typically created by
|
||||
`nix-instantiate`):
|
||||
|
||||
$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
|
||||
|
||||
To install a specific output path:
|
||||
|
||||
$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
|
||||
|
||||
To install from a Nix expression specified on the command-line:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
|
||||
|
||||
# Operation `--upgrade`
|
||||
|
||||
## Synopsis
|
||||
|
||||
nix-env
|
||||
|
||||
\--upgrade
|
||||
|
||||
\-u
|
||||
|
||||
\--lt
|
||||
|
||||
\--leq
|
||||
|
||||
\--eq
|
||||
|
||||
\--always
|
||||
|
||||
args
|
||||
|
||||
## 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`](#rsec-nix-env-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
|
||||
|
||||
$ nix-env --upgrade gcc
|
||||
upgrading `gcc-3.3.1' to `gcc-3.4'
|
||||
|
||||
$ nix-env -u gcc-3.3.2 --always (switch to a specific version)
|
||||
upgrading `gcc-3.4' to `gcc-3.3.2'
|
||||
|
||||
$ nix-env --upgrade pan
|
||||
(no upgrades available, so nothing happens)
|
||||
|
||||
$ nix-env -u (try to upgrade everything)
|
||||
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. `x` is considered an upgrade of `y`
|
||||
if their package names match, and the version of `y` is higher that 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 names are removed.
|
||||
|
||||
## Examples
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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`:
|
||||
|
||||
$ nix-env --set-flag priority 5 binutils
|
||||
$ nix-env --set-flag priority 10 gcc
|
||||
|
||||
# Operation `--query`
|
||||
|
||||
## Synopsis
|
||||
|
||||
nix-env
|
||||
|
||||
\--query
|
||||
|
||||
\-q
|
||||
|
||||
\--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
|
||||
|
||||
names
|
||||
|
||||
## 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](#opt-attr)
|
||||
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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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`:
|
||||
|
||||
$ nix-env -f ./foo.nix -qa
|
||||
foo-1.2.3
|
||||
|
||||
To compare installed versions to what’s available:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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
|
||||
|
||||
$ nix-env --delete-generations 3 4 8
|
||||
|
||||
$ nix-env --delete-generations +5
|
||||
|
||||
$ nix-env --delete-generations 30d
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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
|
||||
|
||||
$ nix-env --rollback
|
||||
switching from generation 92 to 91
|
||||
|
||||
$ 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.
|
||||
120
doc/manual/src/command-ref/nix-hash.md
Normal file
120
doc/manual/src/command-ref/nix-hash.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
nix-hash
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-hash
|
||||
|
||||
compute the cryptographic hash of a path
|
||||
|
||||
nix-hash
|
||||
|
||||
\--flat
|
||||
|
||||
\--base32
|
||||
|
||||
\--truncate
|
||||
|
||||
\--type
|
||||
|
||||
hashAlgo
|
||||
|
||||
path
|
||||
|
||||
nix-hash
|
||||
|
||||
\--to-base16
|
||||
|
||||
hash
|
||||
|
||||
nix-hash
|
||||
|
||||
\--to-base32
|
||||
|
||||
hash
|
||||
|
||||
# Description
|
||||
|
||||
The command `nix-hash` computes the cryptographic hash of the contents
|
||||
of each path and prints it on standard output. By default, it computes
|
||||
an MD5 hash, but other hash algorithms are available as well. The hash
|
||||
is printed in hexadecimal. To generate the same hash as
|
||||
`nix-prefetch-url` you have to specify multiple arguments, see below for
|
||||
an example.
|
||||
|
||||
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`](#refsec-nix-store-dump).
|
||||
Thus, `nix-hash
|
||||
path` yields the same cryptographic hash as `nix-store --dump
|
||||
path | md5sum`.
|
||||
|
||||
# Options
|
||||
|
||||
- `--flat`
|
||||
Print the cryptographic hash of the contents of each regular file
|
||||
path. That is, do not compute the hash over the dump of path. The
|
||||
result is identical to that produced by the GNU commands `md5sum`
|
||||
and `sha1sum`.
|
||||
|
||||
- `--base32`
|
||||
Print the hash in a base-32 representation rather than hexadecimal.
|
||||
This base-32 representation is more compact and can be used in Nix
|
||||
expressions (such as in calls to `fetchurl`).
|
||||
|
||||
- `--truncate`
|
||||
Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits.
|
||||
|
||||
- `--type` hashAlgo
|
||||
Use the specified cryptographic hash algorithm, which can be one of
|
||||
`md5`, `sha1`, and `sha256`.
|
||||
|
||||
- `--to-base16`
|
||||
Don’t hash anything, but convert the base-32 hash representation
|
||||
hash to hexadecimal.
|
||||
|
||||
- `--to-base32`
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
hash to base-32.
|
||||
|
||||
# Examples
|
||||
|
||||
Computing the same hash as `nix-prefetch-url`:
|
||||
|
||||
$ nix-prefetch-url file://<(echo test)
|
||||
1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
|
||||
$ nix-hash --type sha256 --flat --base32 <(echo test)
|
||||
1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
|
||||
|
||||
Computing hashes:
|
||||
|
||||
$ mkdir test
|
||||
$ echo "hello" > test/world
|
||||
|
||||
$ nix-hash test/ (MD5 hash; default)
|
||||
8179d3caeff1869b5ba1744e5a245c04
|
||||
|
||||
$ nix-store --dump test/ | md5sum (for comparison)
|
||||
8179d3caeff1869b5ba1744e5a245c04 -
|
||||
|
||||
$ nix-hash --type sha1 test/
|
||||
e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
|
||||
|
||||
$ nix-hash --type sha1 --base32 test/
|
||||
nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
|
||||
|
||||
$ nix-hash --type sha256 --flat test/
|
||||
error: reading file `test/': Is a directory
|
||||
|
||||
$ nix-hash --type sha256 --flat test/world
|
||||
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
|
||||
|
||||
Converting between hexadecimal and base-32:
|
||||
|
||||
$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
|
||||
nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
|
||||
|
||||
$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
|
||||
e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
|
||||
184
doc/manual/src/command-ref/nix-instantiate.md
Normal file
184
doc/manual/src/command-ref/nix-instantiate.md
Normal file
|
|
@ -0,0 +1,184 @@
|
|||
nix-instantiate
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-instantiate
|
||||
|
||||
instantiate store derivations from Nix expressions
|
||||
|
||||
nix-instantiate
|
||||
|
||||
\--parse
|
||||
|
||||
\--eval
|
||||
|
||||
\--strict
|
||||
|
||||
\--json
|
||||
|
||||
\--xml
|
||||
|
||||
\--read-write-mode
|
||||
|
||||
\--arg
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--attr
|
||||
|
||||
\-A
|
||||
|
||||
attrPath
|
||||
|
||||
\--add-root
|
||||
|
||||
path
|
||||
|
||||
\--indirect
|
||||
|
||||
\--expr
|
||||
|
||||
\-E
|
||||
|
||||
files
|
||||
|
||||
nix-instantiate
|
||||
|
||||
\--find-file
|
||||
|
||||
files
|
||||
|
||||
# Description
|
||||
|
||||
The command `nix-instantiate` generates [store
|
||||
derivations](#gloss-derivation) from (high-level) Nix expressions. It
|
||||
evaluates the Nix expressions in each of files (which defaults to
|
||||
./default.nix). Each top-level expression should evaluate to a
|
||||
derivation, a list of derivations, or a set of derivations. The paths of
|
||||
the resulting store derivations are printed on standard output.
|
||||
|
||||
If files is the character `-`, then a Nix expression will be read from
|
||||
standard input.
|
||||
|
||||
See also [???](#sec-common-options) for a list of common options.
|
||||
|
||||
# Options
|
||||
|
||||
- `--add-root` path; `--indirect`
|
||||
See the [corresponding options](#opt-add-root) in `nix-store`.
|
||||
|
||||
- `--parse`
|
||||
Just parse the input files, and print their abstract syntax trees on
|
||||
standard output in ATerm format.
|
||||
|
||||
- `--eval`
|
||||
Just parse and evaluate the input files, and print the resulting
|
||||
values on standard output. No instantiation of store derivations
|
||||
takes place.
|
||||
|
||||
- `--find-file`
|
||||
Look up the given files in Nix’s search path (as specified by the
|
||||
NIX\_PATH\</literal\> environment variable). If found, print the
|
||||
corresponding absolute paths on standard output. For instance, if
|
||||
`NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate
|
||||
--find-file nixpkgs/default.nix` will print
|
||||
`/home/alice/nixpkgs/default.nix`.
|
||||
|
||||
- `--strict`
|
||||
When used with `--eval`, recursively evaluate list elements and
|
||||
attributes. Normally, such sub-expressions are left unevaluated
|
||||
(since the Nix expression language is lazy).
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> This option can cause non-termination, because lazy data
|
||||
> structures can be infinitely large.
|
||||
|
||||
- `--json`
|
||||
When used with `--eval`, print the resulting value as an JSON
|
||||
representation of the abstract syntax tree rather than as an ATerm.
|
||||
|
||||
- `--xml`
|
||||
When used with `--eval`, print the resulting value as an XML
|
||||
representation of the abstract syntax tree rather than as an ATerm.
|
||||
The schema is the same as that used by the [`toXML`
|
||||
built-in](#builtin-toXML).
|
||||
|
||||
- `--read-write-mode`
|
||||
When used with `--eval`, perform evaluation in read/write mode so
|
||||
nix language features that require it will still work (at the cost
|
||||
of needing to do instantiation of every evaluated derivation). If
|
||||
this option is not enabled, there may be uninstantiated store paths
|
||||
in the final output.
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
# Examples
|
||||
|
||||
Instantiating store derivations from a Nix expression, and building them
|
||||
using `nix-store`:
|
||||
|
||||
$ nix-instantiate test.nix (instantiate)
|
||||
/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
|
||||
|
||||
$ nix-store -r $(nix-instantiate test.nix) (build)
|
||||
...
|
||||
/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)
|
||||
|
||||
$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
|
||||
dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib
|
||||
...
|
||||
|
||||
You can also give a Nix expression on the command line:
|
||||
|
||||
$ nix-instantiate -E 'with import <nixpkgs> { }; hello'
|
||||
/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
|
||||
|
||||
This is equivalent to:
|
||||
|
||||
$ nix-instantiate '<nixpkgs>' -A hello
|
||||
|
||||
Parsing and evaluating Nix expressions:
|
||||
|
||||
$ nix-instantiate --parse -E '1 + 2'
|
||||
1 + 2
|
||||
|
||||
$ nix-instantiate --eval -E '1 + 2'
|
||||
3
|
||||
|
||||
$ nix-instantiate --eval --xml -E '1 + 2'
|
||||
<?xml version='1.0' encoding='utf-8'?>
|
||||
<expr>
|
||||
<int value="3" />
|
||||
</expr>
|
||||
|
||||
The difference between non-strict and strict evaluation:
|
||||
|
||||
$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
|
||||
...
|
||||
<attr name="x">
|
||||
<string value="foo" />
|
||||
</attr>
|
||||
<attr name="y">
|
||||
<unevaluated />
|
||||
</attr>
|
||||
...
|
||||
|
||||
Note that `y` is left unevaluated (the XML representation doesn’t
|
||||
attempt to show non-normal forms).
|
||||
|
||||
$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
|
||||
...
|
||||
<attr name="x">
|
||||
<string value="foo" />
|
||||
</attr>
|
||||
<attr name="y">
|
||||
<string value="foo" />
|
||||
</attr>
|
||||
...
|
||||
|
||||
# Environment variables
|
||||
87
doc/manual/src/command-ref/nix-prefetch-url.md
Normal file
87
doc/manual/src/command-ref/nix-prefetch-url.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
nix-prefetch-url
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-prefetch-url
|
||||
|
||||
copy a file from a URL into the store and print its hash
|
||||
|
||||
nix-prefetch-url
|
||||
|
||||
\--version
|
||||
|
||||
\--type
|
||||
|
||||
hashAlgo
|
||||
|
||||
\--print-path
|
||||
|
||||
\--unpack
|
||||
|
||||
\--name
|
||||
|
||||
name
|
||||
|
||||
url
|
||||
|
||||
hash
|
||||
|
||||
# Description
|
||||
|
||||
The command `nix-prefetch-url` downloads the file referenced by the URL
|
||||
url, prints its cryptographic hash, and copies it into the Nix store.
|
||||
The file name in the store is `hash-baseName`, where baseName is
|
||||
everything following the final slash in url.
|
||||
|
||||
This command is just a convenience for Nix expression writers. Often a
|
||||
Nix expression fetches some source distribution from the network using
|
||||
the `fetchurl` expression contained in Nixpkgs. However, `fetchurl`
|
||||
requires a cryptographic hash. If you don't know the hash, you would
|
||||
have to download the file first, and then `fetchurl` would download it
|
||||
again when you build your Nix expression. Since `fetchurl` uses the same
|
||||
name for the downloaded file as `nix-prefetch-url`, the redundant
|
||||
download can be avoided.
|
||||
|
||||
If hash is specified, then a download is not performed if the Nix store
|
||||
already contains a file with the same hash and base name. Otherwise, the
|
||||
file is downloaded, and an error is signaled if the actual hash of the
|
||||
file does not match the specified hash.
|
||||
|
||||
This command prints the hash on standard output. Additionally, if the
|
||||
option `--print-path` is used, the path of the downloaded file in the
|
||||
Nix store is also printed.
|
||||
|
||||
# Options
|
||||
|
||||
- `--type` hashAlgo
|
||||
Use the specified cryptographic hash algorithm, which can be one of
|
||||
`md5`, `sha1`, and `sha256`.
|
||||
|
||||
- `--print-path`
|
||||
Print the store path of the downloaded file on standard output.
|
||||
|
||||
- `--unpack`
|
||||
Unpack the archive (which must be a tarball or zip file) and add the
|
||||
result to the Nix store. The resulting hash can be used with
|
||||
functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`.
|
||||
|
||||
- `--name` name
|
||||
Override the name of the file in the Nix store. By default, this is
|
||||
`hash-basename`, where basename is the last component of url.
|
||||
Overriding the name is necessary when basename contains characters
|
||||
that are not allowed in Nix store paths.
|
||||
|
||||
# Examples
|
||||
|
||||
$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
|
||||
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
|
||||
|
||||
$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
|
||||
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
|
||||
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
|
||||
|
||||
$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
|
||||
079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
|
||||
/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
|
||||
291
doc/manual/src/command-ref/nix-shell.md
Normal file
291
doc/manual/src/command-ref/nix-shell.md
Normal file
|
|
@ -0,0 +1,291 @@
|
|||
nix-shell
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-shell
|
||||
|
||||
start an interactive shell based on a Nix expression
|
||||
|
||||
nix-shell
|
||||
|
||||
\--arg
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--argstr
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
|
||||
\--attr
|
||||
|
||||
\-A
|
||||
|
||||
attrPath
|
||||
|
||||
\--command
|
||||
|
||||
cmd
|
||||
|
||||
\--run
|
||||
|
||||
cmd
|
||||
|
||||
\--exclude
|
||||
|
||||
regexp
|
||||
|
||||
\--pure
|
||||
|
||||
\--keep
|
||||
|
||||
name
|
||||
|
||||
\--packages
|
||||
|
||||
\-p
|
||||
|
||||
packages
|
||||
|
||||
expressions
|
||||
|
||||
path
|
||||
|
||||
# Description
|
||||
|
||||
The command `nix-shell` will build the dependencies of the specified
|
||||
derivation, but not the derivation itself. It will then start an
|
||||
interactive shell in which all environment variables defined by the
|
||||
derivation path have been set to their corresponding values, and the
|
||||
script `$stdenv/setup` has been sourced. This is useful for reproducing
|
||||
the environment of a derivation for development.
|
||||
|
||||
If path is not given, `nix-shell` defaults to `shell.nix` if it exists,
|
||||
and `default.nix` otherwise.
|
||||
|
||||
If path 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`.
|
||||
|
||||
If the derivation defines the variable `shellHook`, it will be evaluated
|
||||
after `$stdenv/setup` has been sourced. Since this hook is not executed
|
||||
by regular Nix builds, it allows you to perform initialisation specific
|
||||
to `nix-shell`. For example, the derivation attribute
|
||||
|
||||
shellHook =
|
||||
''
|
||||
echo "Hello shell"
|
||||
'';
|
||||
|
||||
will cause `nix-shell` to print `Hello shell`.
|
||||
|
||||
# Options
|
||||
|
||||
All options not listed here are passed to `nix-store
|
||||
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
|
||||
`nix-instantiate`. See also [???](#sec-common-options).
|
||||
|
||||
- `--command` cmd
|
||||
In the environment of the derivation, run the shell command cmd.
|
||||
This command is executed in an interactive shell. (Use `--run` to
|
||||
use a non-interactive shell instead.) However, a call to `exit` is
|
||||
implicitly added to the command, so the shell will exit after
|
||||
running the command. To prevent this, add `return` at the end; e.g.
|
||||
`--command
|
||||
"echo Hello; return"` will print `Hello` and then drop you into the
|
||||
interactive shell. This can be useful for doing any additional
|
||||
initialisation.
|
||||
|
||||
- `--run` cmd
|
||||
Like `--command`, but executes the command in a non-interactive
|
||||
shell. This means (among other things) that if you hit Ctrl-C while
|
||||
the command is running, the shell exits.
|
||||
|
||||
- `--exclude` regexp
|
||||
Do not build any dependencies whose store path matches the regular
|
||||
expression regexp. This option may be specified multiple times.
|
||||
|
||||
- `--pure`
|
||||
If this flag is specified, the environment is almost entirely
|
||||
cleared before the interactive shell is started, so you get an
|
||||
environment that more closely corresponds to the “real” Nix build. A
|
||||
few variables, in particular `HOME`, `USER` and `DISPLAY`, are
|
||||
retained. Note that `~/.bashrc` and (depending on your Bash
|
||||
installation) `/etc/bashrc` are still sourced, so any variables set
|
||||
there will affect the interactive shell.
|
||||
|
||||
- `--packages` / `-p` packages…
|
||||
Set up an environment in which the specified packages are present.
|
||||
The command line arguments are interpreted as attribute names inside
|
||||
the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk`
|
||||
will start a shell in which the packages denoted by the attribute
|
||||
names `libjpeg` and `openjdk` are present.
|
||||
|
||||
- `-i` interpreter
|
||||
The chained script interpreter to be invoked by `nix-shell`. Only
|
||||
applicable in `#!`-scripts (described
|
||||
[below](#ssec-nix-shell-shebang)).
|
||||
|
||||
- `--keep` name
|
||||
When a `--pure` shell is started, keep the listed environment
|
||||
variables.
|
||||
|
||||
The following common options are supported:
|
||||
|
||||
# Environment variables
|
||||
|
||||
- `NIX_BUILD_SHELL`
|
||||
Shell used to start the interactive environment. Defaults to the
|
||||
`bash` found in `PATH`.
|
||||
|
||||
# Examples
|
||||
|
||||
To build the dependencies of the package Pan, and start an interactive
|
||||
shell in which to build it:
|
||||
|
||||
$ nix-shell '<nixpkgs>' -A pan
|
||||
[nix-shell]$ unpackPhase
|
||||
[nix-shell]$ cd pan-*
|
||||
[nix-shell]$ configurePhase
|
||||
[nix-shell]$ buildPhase
|
||||
[nix-shell]$ ./pan/gui/pan
|
||||
|
||||
To clear the environment first, and do some additional automatic
|
||||
initialisation of the interactive shell:
|
||||
|
||||
$ nix-shell '<nixpkgs>' -A pan --pure \
|
||||
--command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
|
||||
|
||||
Nix expressions can also be given on the command line using the `-E` and
|
||||
`-p` flags. For instance, the following starts a shell containing the
|
||||
packages `sqlite` and `libX11`:
|
||||
|
||||
$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
|
||||
|
||||
A shorter way to do the same is:
|
||||
|
||||
$ nix-shell -p sqlite xorg.libX11
|
||||
[nix-shell]$ echo $NIX_LDFLAGS
|
||||
… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
|
||||
|
||||
Note that `-p` accepts multiple full nix expressions that are valid in
|
||||
the `buildInputs = [ ... ]` shown above, not only package names. So the
|
||||
following is also legal:
|
||||
|
||||
$ nix-shell -p sqlite 'git.override { withManual = false; }'
|
||||
|
||||
The `-p` flag looks up Nixpkgs in the Nix search path. You can override
|
||||
it by passing `-I` or setting `NIX_PATH`. For example, the following
|
||||
gives you a shell containing the Pan package from a specific revision of
|
||||
Nixpkgs:
|
||||
|
||||
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
|
||||
|
||||
[nix-shell:~]$ pan --version
|
||||
Pan 0.139
|
||||
|
||||
# Use as a `#!`-interpreter
|
||||
|
||||
You can use `nix-shell` as a script interpreter to allow scripts written
|
||||
in arbitrary languages to obtain their own dependencies via Nix. This is
|
||||
done by starting the script with the following lines:
|
||||
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell -i real-interpreter -p packages
|
||||
|
||||
where real-interpreter is the “real” script interpreter that will be
|
||||
invoked by `nix-shell` after it has obtained the dependencies and
|
||||
initialised the environment, and packages are the attribute names of the
|
||||
dependencies in Nixpkgs.
|
||||
|
||||
The lines starting with `#! nix-shell` specify `nix-shell` options (see
|
||||
above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...`
|
||||
because many operating systems only allow one argument in `#!` lines.
|
||||
|
||||
For example, here is a Python script that depends on Python and the
|
||||
`prettytable` package:
|
||||
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell -i python -p python pythonPackages.prettytable
|
||||
|
||||
import prettytable
|
||||
|
||||
# Print a simple table.
|
||||
t = prettytable.PrettyTable(["N", "N^2"])
|
||||
for n in range(1, 10): t.add_row([n, n * n])
|
||||
print t
|
||||
|
||||
Similarly, the following is a Perl script that specifies that it
|
||||
requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
|
||||
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
|
||||
|
||||
use HTML::TokeParser::Simple;
|
||||
|
||||
# Fetch nixos.org and print all hrefs.
|
||||
my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
|
||||
|
||||
while (my $token = $p->get_tag("a")) {
|
||||
my $href = $token->get_attr("href");
|
||||
print "$href\n" if $href;
|
||||
}
|
||||
|
||||
Sometimes you need to pass a simple Nix expression to customize a
|
||||
package like Terraform:
|
||||
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
|
||||
|
||||
terraform apply
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> You must use double quotes (`"`) when passing a simple Nix expression
|
||||
> in a nix-shell shebang.
|
||||
|
||||
Finally, using the merging of multiple nix-shell shebangs the following
|
||||
Haskell script uses a specific branch of Nixpkgs/NixOS (the 18.03 stable
|
||||
branch):
|
||||
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])"
|
||||
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz
|
||||
|
||||
import Network.HTTP
|
||||
import Text.HTML.TagSoup
|
||||
|
||||
-- Fetch nixos.org and print all hrefs.
|
||||
main = do
|
||||
resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
|
||||
body <- getResponseBody resp
|
||||
let tags = filter (isTagOpenName "a") $ parseTags body
|
||||
let tags' = map (fromAttrib "href") tags
|
||||
mapM_ putStrLn $ filter (/= "") tags'
|
||||
|
||||
If you want to be even more precise, you can specify a specific revision
|
||||
of Nixpkgs:
|
||||
|
||||
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
|
||||
|
||||
The examples above all used `-p` to get dependencies from Nixpkgs. You
|
||||
can also use a Nix expression to build your own dependencies. For
|
||||
example, the Python example could have been written as:
|
||||
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell deps.nix -i python
|
||||
|
||||
where the file `deps.nix` in the same directory as the `#!`-script
|
||||
contains:
|
||||
|
||||
with import <nixpkgs> {};
|
||||
|
||||
runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
|
||||
|
||||
# Environment variables
|
||||
954
doc/manual/src/command-ref/nix-store.md
Normal file
954
doc/manual/src/command-ref/nix-store.md
Normal file
|
|
@ -0,0 +1,954 @@
|
|||
nix-store
|
||||
|
||||
1
|
||||
|
||||
Nix
|
||||
|
||||
nix-store
|
||||
|
||||
manipulate or query the Nix store
|
||||
|
||||
nix-store
|
||||
|
||||
\--add-root
|
||||
|
||||
path
|
||||
|
||||
\--indirect
|
||||
|
||||
operation
|
||||
|
||||
options
|
||||
|
||||
arguments
|
||||
|
||||
# Description
|
||||
|
||||
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. See also [???](#sec-common-options) for a list of common
|
||||
options.
|
||||
|
||||
- `--add-root` path
|
||||
Causes the result of a realisation (`--realise` and
|
||||
`--force-realise`) to be registered as a root of the garbage
|
||||
collector(see [???](#ssec-gc-roots)). The root is stored in path,
|
||||
which must be inside a directory that is scanned for roots by the
|
||||
garbage collector (i.e., typically in a subdirectory of
|
||||
`/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used.
|
||||
|
||||
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).
|
||||
|
||||
- `--indirect`
|
||||
In conjunction with `--add-root`, this option allows roots to be
|
||||
stored *outside* of the GC roots directory. This is useful for
|
||||
commands such as `nix-build` that place a symlink to the build
|
||||
result in the current directory; such a build result should not be
|
||||
garbage-collected unless the symlink is removed.
|
||||
|
||||
The `--indirect` flag causes a uniquely named symlink to path to be
|
||||
stored in `/nix/var/nix/gcroots/auto/`. For instance,
|
||||
|
||||
$ nix-store --add-root /home/eelco/bla/result --indirect -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 indirect GC roots,
|
||||
> since the symlink in the `auto` directory will still point to the
|
||||
> old location.
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
# 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](#gloss-validity) (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](#gloss-substitute) that produce the
|
||||
outputs (e.g., by downloading them). Finally, the outputs can be
|
||||
produced by performing the build action 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)
|
||||
subsitutes, realisation fails.
|
||||
|
||||
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.`
|
||||
|
||||
See also the `build-repeat` configuration option, which repeats a
|
||||
derivation a number of times and prevents its outputs from being
|
||||
registered as “valid” in the Nix store unless they are identical.
|
||||
|
||||
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`](#conf-timeout).
|
||||
|
||||
- `102`
|
||||
Hash mismatch, the build output was rejected because it does not
|
||||
match the specified [`outputHash`](#fixed-output-drvs).
|
||||
|
||||
- `104`
|
||||
Not deterministic, the build succeeded in check mode but the
|
||||
resulting output is not binary reproducable.
|
||||
|
||||
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 derivations produced by
|
||||
[`nix-instantiate`](#sec-nix-instantiate):
|
||||
|
||||
$ nix-store -r $(nix-instantiate ./test.nix)
|
||||
/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1
|
||||
|
||||
This is essentially what [`nix-build`](#sec-nix-build) does.
|
||||
|
||||
To test whether a previously-built derivation is deterministic:
|
||||
|
||||
$ nix-build '<nixpkgs>' -A hello --check -K
|
||||
|
||||
# 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:
|
||||
|
||||
$ 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. What constitutes a root is described in
|
||||
[???](#ssec-gc-roots).
|
||||
|
||||
- `--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`](#conf-keep-outputs) and
|
||||
[`keep-derivations`](#conf-keep-derivations) variables 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:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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 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`](#rsec-nix-store-realise)).
|
||||
|
||||
## Queries
|
||||
|
||||
- `--outputs`
|
||||
Prints out the [output paths](#gloss-output-path) of the store
|
||||
derivations paths. These are the paths that will be produced when
|
||||
the derivation is built.
|
||||
|
||||
- `--requisites`; `-R`
|
||||
Prints out the [closure](#gloss-closure) of the store path paths.
|
||||
|
||||
This query has one option:
|
||||
|
||||
- `--include-outputs`
|
||||
Also include the output path of store derivations, 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](#gloss-reference) of the store paths
|
||||
paths, that is, their immediate dependencies. (For *all*
|
||||
dependencies, use `--requisites`.)
|
||||
|
||||
- `--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](#gloss-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.
|
||||
|
||||
- `--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 derivations 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:
|
||||
|
||||
$ 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`:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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`:
|
||||
|
||||
$ 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`:
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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`:
|
||||
|
||||
$ nix-store -q --roots $(which svn)
|
||||
/nix/var/nix/profiles/default-81-link
|
||||
/nix/var/nix/profiles/default-82-link
|
||||
/nix/var/nix/profiles/per-user/eelco/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
|
||||
|
||||
$ nix-store --add ./foo.c
|
||||
/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c
|
||||
|
||||
# Operation `--add-fixed`
|
||||
|
||||
## Synopsis
|
||||
|
||||
nix-store
|
||||
|
||||
\--recursive
|
||||
|
||||
\--add-fixed
|
||||
|
||||
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
|
||||
|
||||
$ 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:
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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 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`](#refsec-nix-store-query)) 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:
|
||||
|
||||
$ nix-store --export $(nix-store -qR paths) > out
|
||||
|
||||
To import the whole closure again, run:
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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
|
||||
|
||||
$ 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.
|
||||
|
||||
# Environment variables
|
||||
57
doc/manual/src/command-ref/opt-common-syn.md
Normal file
57
doc/manual/src/command-ref/opt-common-syn.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
\--help
|
||||
|
||||
\--version
|
||||
|
||||
\--verbose
|
||||
|
||||
\-v
|
||||
|
||||
\--quiet
|
||||
|
||||
\--log-format
|
||||
|
||||
format
|
||||
|
||||
\--no-build-output
|
||||
|
||||
\-Q
|
||||
|
||||
\--max-jobs
|
||||
|
||||
\-j
|
||||
|
||||
number
|
||||
|
||||
\--cores
|
||||
|
||||
number
|
||||
|
||||
\--max-silent-time
|
||||
|
||||
number
|
||||
|
||||
\--timeout
|
||||
|
||||
number
|
||||
|
||||
\--keep-going
|
||||
|
||||
\-k
|
||||
|
||||
\--keep-failed
|
||||
|
||||
\-K
|
||||
|
||||
\--fallback
|
||||
|
||||
\--readonly-mode
|
||||
|
||||
\-I
|
||||
|
||||
path
|
||||
|
||||
\--option
|
||||
|
||||
name
|
||||
|
||||
value
|
||||
15
doc/manual/src/command-ref/opt-inst-syn.md
Normal file
15
doc/manual/src/command-ref/opt-inst-syn.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
\--prebuilt-only
|
||||
|
||||
\-b
|
||||
|
||||
\--attr
|
||||
|
||||
\-A
|
||||
|
||||
\--from-expression
|
||||
|
||||
\-E
|
||||
|
||||
\--from-profile
|
||||
|
||||
path
|
||||
Loading…
Reference in a new issue