diff options
Diffstat (limited to 'doc/manual/src')
| -rw-r--r-- | doc/manual/src/SUMMARY.md | 11 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/command-ref.md | 6 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/main-commands.md | 4 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-build.md | 130 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-channel.md | 116 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-collect-garbage.md | 46 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-daemon.md | 17 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-env.md | 926 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-hash.md | 120 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-instantiate.md | 184 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-prefetch-url.md | 87 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-shell.md | 291 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-store.md | 954 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/opt-common-syn.md | 57 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/opt-inst-syn.md | 15 |
15 files changed, 2960 insertions, 4 deletions
diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md index e8baf489b..80a41f8d7 100644 --- a/doc/manual/src/SUMMARY.md +++ b/doc/manual/src/SUMMARY.md @@ -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) diff --git a/doc/manual/src/command-ref/command-ref.md b/doc/manual/src/command-ref/command-ref.md index 2c7dbf22e..6a78075db 100644 --- a/doc/manual/src/command-ref/command-ref.md +++ b/doc/manual/src/command-ref/command-ref.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. diff --git a/doc/manual/src/command-ref/main-commands.md b/doc/manual/src/command-ref/main-commands.md new file mode 100644 index 000000000..e4f1f1d0e --- /dev/null +++ b/doc/manual/src/command-ref/main-commands.md @@ -0,0 +1,4 @@ +# Main Commands + +This section lists commands and options that you can use when you work +with Nix. diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md new file mode 100644 index 000000000..7d0567760 --- /dev/null +++ b/doc/manual/src/command-ref/nix-build.md @@ -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 diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md new file mode 100644 index 000000000..d427151a0 --- /dev/null +++ b/doc/manual/src/command-ref/nix-channel.md @@ -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”. diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md new file mode 100644 index 000000000..7946dc875 --- /dev/null +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -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 diff --git a/doc/manual/src/command-ref/nix-daemon.md b/doc/manual/src/command-ref/nix-daemon.md new file mode 100644 index 000000000..b0570789c --- /dev/null +++ b/doc/manual/src/command-ref/nix-daemon.md @@ -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. diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md new file mode 100644 index 000000000..90bf6ea08 --- /dev/null +++ b/doc/manual/src/command-ref/nix-env.md @@ -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. diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md new file mode 100644 index 000000000..d433cbc5b --- /dev/null +++ b/doc/manual/src/command-ref/nix-hash.md @@ -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 diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md new file mode 100644 index 000000000..449f5f70f --- /dev/null +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -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 diff --git a/doc/manual/src/command-ref/nix-prefetch-url.md b/doc/manual/src/command-ref/nix-prefetch-url.md new file mode 100644 index 000000000..bf8084e45 --- /dev/null +++ b/doc/manual/src/command-ref/nix-prefetch-url.md @@ -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 diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md new file mode 100644 index 000000000..c6910e3f5 --- /dev/null +++ b/doc/manual/src/command-ref/nix-shell.md @@ -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 diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md new file mode 100644 index 000000000..703e71076 --- /dev/null +++ b/doc/manual/src/command-ref/nix-store.md @@ -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 diff --git a/doc/manual/src/command-ref/opt-common-syn.md b/doc/manual/src/command-ref/opt-common-syn.md new file mode 100644 index 000000000..b66d318c2 --- /dev/null +++ b/doc/manual/src/command-ref/opt-common-syn.md @@ -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 diff --git a/doc/manual/src/command-ref/opt-inst-syn.md b/doc/manual/src/command-ref/opt-inst-syn.md new file mode 100644 index 000000000..1703c40e3 --- /dev/null +++ b/doc/manual/src/command-ref/opt-inst-syn.md @@ -0,0 +1,15 @@ +\--prebuilt-only + +\-b + +\--attr + +\-A + +\--from-expression + +\-E + +\--from-profile + +path |