diff options
Diffstat (limited to 'doc/manual/src/command-ref')
| -rw-r--r-- | doc/manual/src/command-ref/env-common.md | 74 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-build.md | 6 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-channel.md | 16 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-copy-closure.md | 14 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-env.md | 76 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-hash.md | 12 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-instantiate.md | 16 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-prefetch-url.md | 10 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-shell.md | 20 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-store.md | 62 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/opt-common.md | 96 |
11 files changed, 202 insertions, 200 deletions
diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md index c670d82b8..6e2403461 100644 --- a/doc/manual/src/command-ref/env-common.md +++ b/doc/manual/src/command-ref/env-common.md @@ -2,45 +2,49 @@ Most Nix commands interpret the following environment variables: - - `IN_NIX_SHELL` + - `IN_NIX_SHELL`\ Indicator that tells if the current environment was set up by `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"` - - `NIX_PATH` + - `NIX_PATH`\ A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (i.e., `<path>`). For instance, the value - + /home/eelco/Dev:/etc/nixos - + will cause Nix to look for paths relative to `/home/eelco/Dev` and `/etc/nixos`, in this order. It is also possible to match paths against a prefix. For example, the value - + nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos - + will cause Nix to search for `<nixpkgs/path>` in `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`. - + If a path in the Nix search 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 consist of a single top-level directory. For example, setting `NIX_PATH` to - - nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz - - tells Nix to download the latest revision in the Nixpkgs/NixOS 15.09 - channel. - - A following shorthand can be used to refer to the official channels: - - nixpkgs=channel:nixos-15.09 - - The search path can be extended using the `-I` option, which takes - precedence over `NIX_PATH`. - - - `NIX_IGNORE_SYMLINK_STORE` + + nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz + + tells Nix to download and use the current contents of the + `master` branch in the `nixpkgs` repository. + + The URLs of the tarballs from the official nixos.org channels (see + [the manual for `nix-channel`](nix-channel.md)) can be abbreviated + as `channel:<channel-name>`. For instance, the following two + values of `NIX_PATH` are equivalent: + + nixpkgs=channel:nixos-21.05 + nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz + + The Nix search path can also be extended using the `-I` option to + many Nix commands, which takes precedence over `NIX_PATH`. + + - `NIX_IGNORE_SYMLINK_STORE`\ Normally, the Nix store directory (typically `/nix/store`) is not allowed to contain any symlink components. This is to prevent “impure” builds. Builders sometimes “canonicalise” paths by @@ -50,7 +54,7 @@ Most Nix commands interpret the following environment variables: builds are deployed to machines where `/nix/store` resolves differently. If you are sure that you’re not going to do that, you can set `NIX_IGNORE_SYMLINK_STORE` to `1`. - + Note that if you’re symlinking the Nix store so that you can put it on another file system than the root file system, on Linux you’re better off using `bind` mount points, e.g., @@ -59,44 +63,44 @@ Most Nix commands interpret the following environment variables: $ mkdir /nix $ mount -o bind /mnt/otherdisk/nix /nix ``` - + Consult the mount 8 manual page for details. - - `NIX_STORE_DIR` + - `NIX_STORE_DIR`\ Overrides the location of the Nix store (default `prefix/store`). - - `NIX_DATA_DIR` + - `NIX_DATA_DIR`\ Overrides the location of the Nix static data directory (default `prefix/share`). - - `NIX_LOG_DIR` + - `NIX_LOG_DIR`\ Overrides the location of the Nix log directory (default `prefix/var/log/nix`). - - `NIX_STATE_DIR` + - `NIX_STATE_DIR`\ Overrides the location of the Nix state directory (default `prefix/var/nix`). - - `NIX_CONF_DIR` + - `NIX_CONF_DIR`\ Overrides the location of the system Nix configuration directory (default `prefix/etc/nix`). - - `NIX_CONFIG` + - `NIX_CONFIG`\ Applies settings from Nix configuration from the environment. The content is treated as if it was read from a Nix configuration file. Settings are separated by the newline character. - - `NIX_USER_CONF_FILES` + - `NIX_USER_CONF_FILES`\ Overrides the location of the user Nix configuration files to load from (defaults to the XDG spec locations). The variable is treated as a list separated by the `:` token. - - `TMPDIR` + - `TMPDIR`\ Use the specified directory to store temporary files. In particular, this includes temporary build directories; these can take up substantial amounts of disk space. The default is `/tmp`. - - `NIX_REMOTE` + - `NIX_REMOTE`\ This variable should be set to `daemon` if you want to use the Nix daemon to execute Nix operations. This is necessary in [multi-user Nix installations](../installation/multi-user.md). If the Nix @@ -104,16 +108,16 @@ Most Nix commands interpret the following environment variables: should be set to `unix://path/to/socket`. Otherwise, it should be left unset. - - `NIX_SHOW_STATS` + - `NIX_SHOW_STATS`\ If set to `1`, Nix will print some evaluation statistics, such as the number of values allocated. - - `NIX_COUNT_CALLS` + - `NIX_COUNT_CALLS`\ If set to `1`, Nix will print how often functions were called during Nix expression evaluation. This is useful for profiling your Nix expressions. - - `GC_INITIAL_HEAP_SIZE` + - `GC_INITIAL_HEAP_SIZE`\ If Nix has been configured to use the Boehm garbage collector, this variable sets the initial size of the heap in bytes. It defaults to 384 MiB. Setting it to a low value reduces memory consumption, but diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 4565bfbc2..43de7a6e6 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -47,16 +47,16 @@ All options not listed here are passed to `nix-store --realise`, except for `--arg` and `--attr` / `-A` which are passed to `nix-instantiate`. - - `--no-out-link` + - `--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` + - `--dry-run`\ Show what store paths would be built or downloaded. - - `--out-link` / `-o` *outlink* + - `--out-link` / `-o` *outlink*\ Change the name of the symlink to the output path created from `result` to *outlink*. diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md index 4ca12d2cc..24353525f 100644 --- a/doc/manual/src/command-ref/nix-channel.md +++ b/doc/manual/src/command-ref/nix-channel.md @@ -17,26 +17,26 @@ To see the list of official NixOS channels, visit This command has the following operations: - - `--add` *url* \[*name*\] + - `--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* + - `--remove` *name*\ Removes the channel named *name* from the list of subscribed channels. - - `--list` + - `--list`\ Prints the names and URLs of all subscribed channels on standard output. - - `--update` \[*names*…\] + - `--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*\] + - `--rollback` \[*generation*\]\ Reverts the previous call to `nix-channel --update`. Optionally, you can specify a specific channel generation number to restore. @@ -70,14 +70,14 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' # Files - - `/nix/var/nix/profiles/per-user/username/channels` + - `/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` + - `~/.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 @@ -89,7 +89,7 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' A channel URL should point to a directory containing the following files: - - `nixexprs.tar.xz` + - `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 diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md index dcb844a72..7047d3012 100644 --- a/doc/manual/src/command-ref/nix-copy-closure.md +++ b/doc/manual/src/command-ref/nix-copy-closure.md @@ -35,21 +35,21 @@ and second to send the dump of those paths. If this bothers you, use # Options - - `--to` + - `--to`\ Copy the closure of _paths_ from the local Nix store to the Nix store on _machine_. This is the default. - - `--from` + - `--from`\ Copy the closure of _paths_ from the Nix store on _machine_ to the local Nix store. - - `--gzip` + - `--gzip`\ Enable compression of the SSH connection. - - `--include-outputs` + - `--include-outputs`\ Also copy the outputs of store derivations included in the closure. - - `--use-substitutes` / `-s` + - `--use-substitutes` / `-s`\ Attempt to download missing paths on the target machine using Nix’s substitute mechanism. Any paths that cannot be substituted on the target are still copied normally from the source. This is useful, @@ -58,12 +58,12 @@ and second to send the dump of those paths. If this bothers you, use `nixos.org` (the default binary cache server) is fast. - - `-v` + - `-v`\ Show verbose output. # Environment variables - - `NIX_SSHOPTS` + - `NIX_SSHOPTS`\ Additional options to be passed to `ssh` on the command line. diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index 1c23bb0ad..9138fa05a 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -36,27 +36,27 @@ 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` + - `firefox`\ Matches the package name `firefox` and any version. - - `firefox-32.0` + - `firefox-32.0`\ Matches the package name `firefox` and version `32.0`. - - `gtk\\+` + - `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.*'` + - `'.*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).*'` + - `'.*(firefox|chromium).*'`\ Matches any package name containing the strings `firefox` or `chromium`. @@ -66,7 +66,7 @@ This section lists the options that are common to all operations. These options are allowed for every subcommand, though they may not always have an effect. - - `--file` / `-f` *path* + - `--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 @@ -77,13 +77,13 @@ have an effect. 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* + - `--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` + - `--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 @@ -93,7 +93,7 @@ have an effect. [substituted](../glossary.md) (i.e., downloaded) and which paths will be built from source (because no substitute is available). - - `--system-filter` *system* + - `--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*. @@ -102,7 +102,7 @@ have an effect. # Files - - `~/.nix-defexpr` + - `~/.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 @@ -140,7 +140,7 @@ have an effect. The command `nix-channel` places symlinks to the downloaded Nix expressions from each subscribed channel in this directory. - - `~/.nix-profile` + - `~/.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 @@ -217,13 +217,13 @@ a number of possible ways: ## Flags - - `--prebuilt-only` / `-b` + - `--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` + - `--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 @@ -231,7 +231,7 @@ a number of possible ways: clashes between the two versions. However, this is not the case for all packages. - - `--remove-all`; `-r` + - `--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. @@ -346,24 +346,24 @@ version is installed. ## Flags - - `--lt` + - `--lt`\ Only upgrade a derivation to newer versions. This is the default. - - `--leq` + - `--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` + - `--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` + - `--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 @@ -578,11 +578,11 @@ The derivations are sorted by their `name` attributes. The following flags specify the set of things on which the query operates. - - `--installed` + - `--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` + - `--available`; `-a`\ The query operates on the derivations that are available in the active Nix expression. @@ -593,24 +593,24 @@ 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` + - `--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` + - `--json`\ Print the result in a JSON representation suitable for automatic processing by other tools. - - `--prebuilt-only` / `-b` + - `--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` + - `--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 @@ -621,49 +621,49 @@ derivation is shown unless `--no-name` is specified. derivation to be built. The third is `S` or `-`, indicating whether a substitute is available for the derivation. - - `--attr-path`; `-P` + - `--attr-path`; `-P`\ Print the *attribute path* of the derivation, which can be used to unambiguously select it using the `--attr` option available in commands that install derivations like `nix-env --install`. This option only works together with `--available` - - `--no-name` + - `--no-name`\ Suppress printing of the `name` attribute of each derivation. - - `--compare-versions` / `-c` + - `--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* + - `<` *version*\ A newer version of the package is available or installed. - - `=` *version* + - `=` *version*\ At most the same version of the package is available or installed. - - `>` *version* + - `>` *version*\ Only older versions of the package are available or installed. - - `- ?` + - `- ?`\ No version of the package is available or installed. - - `--system` + - `--system`\ Print the `system` attribute of the derivation. - - `--drv-path` + - `--drv-path`\ Print the path of the store derivation. - - `--out-path` + - `--out-path`\ Print the output path of the derivation. - - `--description` + - `--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` + - `--meta`\ Print all of the meta-attributes of the derivation. This option is only available with `--xml` or `--json`. @@ -874,7 +874,7 @@ error: no generation older than the current (91) exists # Environment variables - - `NIX_PROFILE` + - `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 index de0459b9e..45f67f1c5 100644 --- a/doc/manual/src/command-ref/nix-hash.md +++ b/doc/manual/src/command-ref/nix-hash.md @@ -29,29 +29,29 @@ md5sum`. # Options - - `--flat` + - `--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` + - `--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`\ Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits. - - `--type` *hashAlgo* + - `--type` *hashAlgo*\ Use the specified cryptographic hash algorithm, which can be one of `md5`, `sha1`, `sha256`, and `sha512`. - - `--to-base16` + - `--to-base16`\ Don’t hash anything, but convert the base-32 hash representation *hash* to hexadecimal. - - `--to-base32` + - `--to-base32`\ Don’t hash anything, but convert the hexadecimal hash representation *hash* to base-32. diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index c369397b6..2e198daed 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -29,26 +29,26 @@ standard input. # Options - - `--add-root` *path* + - `--add-root` *path*\ See the [corresponding option](nix-store.md) in `nix-store`. - - `--parse` + - `--parse`\ Just parse the input files, and print their abstract syntax trees on standard output in ATerm format. - - `--eval` + - `--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` + - `--find-file`\ Look up the given files in Nix’s search path (as specified by the `NIX_PATH` 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` + - `--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). @@ -58,17 +58,17 @@ standard input. > This option can cause non-termination, because lazy data > structures can be infinitely large. - - `--json` + - `--json`\ When used with `--eval`, print the resulting value as an JSON representation of the abstract syntax tree rather than as an ATerm. - - `--xml` + - `--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](../expressions/builtins.md). - - `--read-write-mode` + - `--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 diff --git a/doc/manual/src/command-ref/nix-prefetch-url.md b/doc/manual/src/command-ref/nix-prefetch-url.md index 59ab89b29..3bcd209e2 100644 --- a/doc/manual/src/command-ref/nix-prefetch-url.md +++ b/doc/manual/src/command-ref/nix-prefetch-url.md @@ -37,22 +37,22 @@ Nix store is also printed. # Options - - `--type` *hashAlgo* + - `--type` *hashAlgo*\ Use the specified cryptographic hash algorithm, which can be one of `md5`, `sha1`, `sha256`, and `sha512`. - - `--print-path` + - `--print-path`\ Print the store path of the downloaded file on standard output. - - `--unpack` + - `--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`. - - `--executable` + - `--executable`\ Set the executable bit on the downloaded file. - - `--name` *name* + - `--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 diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md index 54812a49f..72f6730f1 100644 --- a/doc/manual/src/command-ref/nix-shell.md +++ b/doc/manual/src/command-ref/nix-shell.md @@ -54,7 +54,7 @@ All options not listed here are passed to `nix-store --realise`, except for `--arg` and `--attr` / `-A` which are passed to `nix-instantiate`. - - `--command` *cmd* + - `--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 @@ -64,36 +64,34 @@ All options not listed here are passed to `nix-store drop you into the interactive shell. This can be useful for doing any additional initialisation. - - `--run` *cmd* + - `--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* + - `--exclude` *regexp*\ Do not build any dependencies whose store path matches the regular expression *regexp*. This option may be specified multiple times. - - `--pure` + - `--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 (depending on your Bash - installation) `/etc/bashrc` is still sourced, so any variables set - there will affect the interactive shell. + retained. - - `--packages` / `-p` *packages*… + - `--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* + - `-i` *interpreter*\ The chained script interpreter to be invoked by `nix-shell`. Only applicable in `#!`-scripts (described below). - - `--keep` *name* + - `--keep` *name*\ When a `--pure` shell is started, keep the listed environment variables. @@ -101,7 +99,7 @@ The following common options are supported: # Environment variables - - `NIX_BUILD_SHELL` + - `NIX_BUILD_SHELL`\ Shell used to start the interactive environment. Defaults to the `bash` found in `PATH`. diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md index 49d06f31e..7a131dc02 100644 --- a/doc/manual/src/command-ref/nix-store.md +++ b/doc/manual/src/command-ref/nix-store.md @@ -22,7 +22,7 @@ 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. - - `--add-root` *path* + - `--add-root` *path*\ Causes the result of a realisation (`--realise` and `--force-realise`) to be registered as a root of the garbage collector. *path* will be created as a symlink to the resulting @@ -86,15 +86,15 @@ non-derivations argument, the argument itself is printed.) The following flags are available: - - `--dry-run` + - `--dry-run`\ Print on standard error a description of what packages would be built or downloaded, without actually performing the operation. - - `--ignore-unknown` + - `--ignore-unknown`\ If a non-derivation path does not have a substitute, then silently ignore it. - - `--check` + - `--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, @@ -110,20 +110,20 @@ The following flags are available: Special exit codes: - - `100` + - `100`\ Generic build failure, the builder process returned with a non-zero exit code. - - `101` + - `101`\ Build timeout, the build was aborted because it did not complete within the specified `timeout`. - - `102` + - `102`\ Hash mismatch, the build output was rejected because it does not match the [`outputHash` attribute of the derivation](../expressions/advanced-attributes.md). - - `104` + - `104`\ Not deterministic, the build succeeded in check mode but the resulting output is not binary reproducable. @@ -170,7 +170,7 @@ access to a restricted ssh user. The following flags are available: - - `--write` + - `--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. @@ -200,18 +200,18 @@ reachable via file system references from a set of “roots”, are deleted. The following suboperations may be specified: - - `--print-roots` + - `--print-roots`\ This operation prints on standard output the set of roots used by the garbage collector. - - `--print-live` + - `--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` + - `--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. @@ -219,7 +219,7 @@ The following suboperations may be specified: By default, all unreachable paths are deleted. The following options control what gets deleted and in what order: - - `--max-freed` *bytes* + - `--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 @@ -300,22 +300,22 @@ symlink. ## Common query options - - `--use-output`; `-u` + - `--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` + - `--force-realise`; `-f`\ Realise each argument to the query first (see [`nix-store --realise`](#operation---realise)). ## Queries - - `--outputs` + - `--outputs`\ Prints out the [output paths](../glossary.md) of the store derivations *paths*. These are the paths that will be produced when the derivation is built. - - `--requisites`; `-R` + - `--requisites`; `-R`\ Prints out the [closure](../glossary.md) of the store path *paths*. This query has one option: @@ -332,31 +332,31 @@ symlink. dependencies) is obtained by distributing the closure of a store derivation and specifying the option `--include-outputs`. - - `--references` + - `--references`\ Prints the set of [references](../glossary.md) of the store paths *paths*, that is, their immediate dependencies. (For *all* dependencies, use `--requisites`.) - - `--referrers` + - `--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` + - `--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` + - `--deriver`; `-d`\ Prints the [deriver](../glossary.md) 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` + - `--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 @@ -364,39 +364,39 @@ symlink. this to a store derivation. To obtain a runtime dependency graph, apply it to an output path. - - `--tree` + - `--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` + - `--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* + - `--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` + - `--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` + - `--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` + - `--roots`\ Prints the garbage collector roots that point, directly or indirectly, at the store paths *paths*. @@ -513,7 +513,7 @@ public url or broke since the download expression was written. This operation has the following options: - - `--recursive` + - `--recursive`\ Use recursive instead of flat hashing mode, used when adding directories to the store. @@ -540,14 +540,14 @@ being modified by non-Nix tools, or of bugs in Nix itself. This operation has the following options: - - `--check-contents` + - `--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` + - `--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 diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md index bc8eb6796..47862bc09 100644 --- a/doc/manual/src/command-ref/opt-common.md +++ b/doc/manual/src/command-ref/opt-common.md @@ -2,56 +2,56 @@ Most Nix commands accept the following command-line options: - - `--help` + - `--help`\ Prints out a summary of the command syntax and exits. - - `--version` + - `--version`\ Prints out the Nix version number on standard output and exits. - - `--verbose` / `-v` + - `--verbose` / `-v`\ Increases the level of verbosity of diagnostic messages printed on standard error. For each Nix operation, the information printed on standard output is well-defined; any diagnostic information is printed on standard error, never on standard output. - + This option may be specified repeatedly. Currently, the following verbosity levels exist: - - - 0 + + - 0\ “Errors only”: only print messages explaining why the Nix invocation failed. - - - 1 + + - 1\ “Informational”: print *useful* messages about what Nix is doing. This is the default. - - - 2 + + - 2\ “Talkative”: print more informational messages. - - - 3 + + - 3\ “Chatty”: print even more informational messages. - - - 4 + + - 4\ “Debug”: print debug information. - - - 5 + + - 5\ “Vomit”: print vast amounts of debug information. - - `--quiet` + - `--quiet`\ Decreases the level of verbosity of diagnostic messages printed on standard error. This is the inverse option to `-v` / `--verbose`. - + This option may be specified repeatedly. See the previous verbosity levels list. - - `--log-format` *format* + - `--log-format` *format*\ This option can be used to change the output of the log format, with *format* being one of: - - - raw + + - raw\ This is the raw format, as outputted by nix-build. - - - internal-json + + - internal-json\ Outputs the logs in a structured manner. > **Warning** @@ -60,30 +60,30 @@ Most Nix commands accept the following command-line options: > the error-messages (namely of the `msg`-field) can change > between releases. - - bar + - bar\ Only display a progress bar during the builds. - - - bar-with-logs + + - bar-with-logs\ Display the raw logs, with the progress bar at the bottom. - - `--no-build-output` / `-Q` + - `--no-build-output` / `-Q`\ By default, output written by builders to standard output and standard error is echoed to the Nix command's standard error. This option suppresses this behaviour. Note that the builder's standard output and error are always written to a log file in `prefix/nix/var/log/nix`. - - `--max-jobs` / `-j` *number* + - `--max-jobs` / `-j` *number*\ Sets the maximum number of build jobs that Nix will perform in parallel to the specified number. Specify `auto` to use the number of CPUs in the system. The default is specified by the `max-jobs` configuration setting, which itself defaults to `1`. A higher value is useful on SMP systems or to exploit I/O latency. - + Setting it to `0` disallows building on the local machine, which is useful when you want builds to happen only on remote builders. - - `--cores` + - `--cores`\ Sets the value of the `NIX_BUILD_CORES` environment variable in the invocation of builders. Builders can use this variable at their discretion to control the maximum amount of parallelism. For @@ -94,18 +94,18 @@ Most Nix commands accept the following command-line options: means that the builder should use all available CPU cores in the system. - - `--max-silent-time` + - `--max-silent-time`\ Sets the maximum number of seconds that a builder can go without producing any data on standard output or standard error. The default is specified by the `max-silent-time` configuration setting. `0` means no time-out. - - `--timeout` + - `--timeout`\ Sets the maximum number of seconds that a builder can run. The default is specified by the `timeout` configuration setting. `0` means no timeout. - - `--keep-going` / `-k` + - `--keep-going` / `-k`\ Keep going in case of failed builds, to the greatest extent possible. That is, if building an input of some derivation fails, Nix will still build the other inputs, but not the derivation @@ -113,17 +113,17 @@ Most Nix commands accept the following command-line options: for builds of substitutes), possibly killing builds in progress (in case of parallel or distributed builds). - - `--keep-failed` / `-K` + - `--keep-failed` / `-K`\ Specifies that in case of a build failure, the temporary directory (usually in `/tmp`) in which the build takes place should not be deleted. The path of the build directory is printed as an informational message. - - `--fallback` + - `--fallback`\ Whenever Nix attempts to build a derivation for which substitutes are known for each output path, but realising the output paths through the substitutes fails, fall back on building the derivation. - + The most common scenario in which this is useful is when we have registered substitutes in order to perform binary distribution from, say, a network repository. If the repository is down, the @@ -134,12 +134,12 @@ Most Nix commands accept the following command-line options: failure in obtaining the substitutes to lead to a full build from source (with the related consumption of resources). - - `--readonly-mode` + - `--readonly-mode`\ When this option is used, no attempt is made to open the Nix database. Most Nix operations do need database access, so those operations will fail. - - `--arg` *name* *value* + - `--arg` *name* *value*\ This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell` and `nix-build`. When evaluating Nix expressions, the expression evaluator will automatically try to call functions that @@ -151,7 +151,7 @@ Most Nix commands accept the following command-line options: override a default value). That is, if the evaluator encounters a function with an argument named *name*, it will call it with value *value*. - + For instance, the top-level `default.nix` in Nixpkgs is actually a function: @@ -161,7 +161,7 @@ Most Nix commands accept the following command-line options: ... }: ... ``` - + So if you call this Nix expression (e.g., when you do `nix-env -i pkgname`), the function will be called automatically using the value [`builtins.currentSystem`](../expressions/builtins.md) for @@ -170,13 +170,13 @@ Most Nix commands accept the following command-line options: since the argument is a Nix string literal, you have to escape the quotes.) - - `--argstr` *name* *value* + - `--argstr` *name* *value*\ This option is like `--arg`, only the value is not a Nix expression but a string. So instead of `--arg system \"i686-linux\"` (the outer quotes are to keep the shell happy) you can say `--argstr system i686-linux`. - - `--attr` / `-A` *attrPath* + - `--attr` / `-A` *attrPath*\ Select an attribute from the top-level Nix expression being evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and `nix-shell` only.) The *attribute path* *attrPath* is a sequence @@ -185,34 +185,34 @@ Most Nix commands accept the following command-line options: would cause the expression `e.xorg.xorgserver` to be used. See [`nix-env --install`](nix-env.md#operation---install) for some concrete examples. - + In addition to attribute names, you can also specify array indices. For instance, the attribute path `foo.3.bar` selects the `bar` attribute of the fourth element of the array in the `foo` attribute of the top-level expression. - - `--expr` / `-E` + - `--expr` / `-E`\ Interpret the command line arguments as a list of Nix expressions to be parsed and evaluated, rather than as a list of file names of Nix expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.) - + For `nix-shell`, this option is commonly used to give you a shell in which you can build the packages returned by the expression. If you want to get a shell which contain the *built* packages ready for use, give your expression to the `nix-shell -p` convenience flag instead. - - `-I` *path* + - `-I` *path*\ Add a path to the Nix expression search path. This option may be given multiple times. See the `NIX_PATH` environment variable for information on the semantics of the Nix search path. Paths added through `-I` take precedence over `NIX_PATH`. - - `--option` *name* *value* + - `--option` *name* *value*\ Set the Nix configuration option *name* to *value*. This overrides settings in the Nix configuration file (see nix.conf5). - - `--repair` + - `--repair`\ Fix corrupted or missing store paths by redownloading or rebuilding them. Note that this is slow because it requires computing a cryptographic hash of the contents of every path in the closure of |