diff options
Diffstat (limited to 'doc/manual/src/command-ref')
| -rw-r--r-- | doc/manual/src/command-ref/conf-file.md | 99 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/env-common.md | 7 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-build.md | 5 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-collect-garbage.md | 20 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-env.md | 37 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-hash.md | 14 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-instantiate.md | 10 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-store.md | 50 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/opt-common.md | 84 |
9 files changed, 155 insertions, 171 deletions
diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md index bedf1ec6b..306ad23f5 100644 --- a/doc/manual/src/command-ref/conf-file.md +++ b/doc/manual/src/command-ref/conf-file.md @@ -141,10 +141,10 @@ The following settings are currently available: the builder should use all available CPU cores in the system. - `diff-hook` - Absolute path to an executable capable of diffing build results. The - hook executes if [varlistentry\_title](#conf-run-diff-hook) is true, - and the output of a build is known to not be the same. This program - is not executed to determine if two results are the same. + Absolute path to an executable capable of diffing build + results. The hook is executed if `run-diff-hook` is true, and the + output of a build is known to not be the same. This program is not + executed to determine if two results are the same. The diff hook is executed by the same user and group who ran the build. However, the diff hook does not have write access to the @@ -169,7 +169,7 @@ The following settings are currently available: configuration file, and cannot be passed at the command line. - `enforce-determinism` - See [varlistentry\_title](#conf-repeat). + See `repeat`. - `extra-sandbox-paths` A list of additional paths appended to `sandbox-paths`. Useful if @@ -343,7 +343,7 @@ The following settings are currently available: password my-password For the exact syntax, see [the `curl` - documentation.](https://ec.haxx.se/usingcurl-netrc.html) + documentation](https://ec.haxx.se/usingcurl-netrc.html). > **Note** > @@ -434,9 +434,9 @@ The following settings are currently available: deterministic. The default value is 0. If the value is non-zero, every build is repeated the specified number of times. If the contents of any of the runs differs from the previous ones and - [varlistentry\_title](#conf-enforce-determinism) is true, the build - is rejected and the resulting store paths are not registered as - “valid” in Nix’s database. + `enforce-determinism` is true, the build is rejected and the + resulting store paths are not registered as “valid” in Nix’s + database. - `require-sigs` If set to `true` (the default), any non-content-addressed path added @@ -461,20 +461,21 @@ The following settings are currently available: - `sandbox` If set to `true`, builds will be performed in a *sandboxed environment*, i.e., they’re isolated from the normal file system - hierarchy and will only see their dependencies in the Nix store, the - temporary build directory, private versions of `/proc`, `/dev`, - `/dev/shm` and `/dev/pts` (on Linux), and the paths configured with - the [`sandbox-paths` option](#conf-sandbox-paths). This is useful to + hierarchy and will only see their dependencies in the Nix store, + the temporary build directory, private versions of `/proc`, + `/dev`, `/dev/shm` and `/dev/pts` (on Linux), and the paths + configured with the `sandbox-paths` option. This is useful to prevent undeclared dependencies on files in directories such as - `/usr/bin`. In addition, on Linux, builds run in private PID, mount, - network, IPC and UTS namespaces to isolate them from other processes - in the system (except that fixed-output derivations do not run in - private network namespace to ensure they can access the network). + `/usr/bin`. In addition, on Linux, builds run in private PID, + mount, network, IPC and UTS namespaces to isolate them from other + processes in the system (except that fixed-output derivations do + not run in private network namespace to ensure they can access the + network). Currently, sandboxing only work on Linux and macOS. The use of a sandbox requires that Nix is run as root (so you should use the - [“build users” feature](#conf-build-users-group) to perform the - actual builds under different users than root). + “build users” feature to perform the actual builds under different + users than root). If this option is set to `relaxed`, then fixed-output derivations and derivations that have the `__noChroot` attribute set to `true` @@ -631,81 +632,61 @@ The following settings are currently available: ## Deprecated Settings - `binary-caches` - *Deprecated:* `binary-caches` is now an alias to - [varlistentry\_title](#conf-substituters). + *Deprecated:* `binary-caches` is now an alias to `substituters`. - `binary-cache-public-keys` - *Deprecated:* `binary-cache-public-keys` is now an alias to - [varlistentry\_title](#conf-trusted-public-keys). + *Deprecated:* `binary-cache-public-keys` is now an alias `trusted-public-keys`. - `build-compress-log` - *Deprecated:* `build-compress-log` is now an alias to - [varlistentry\_title](#conf-compress-build-log). + *Deprecated:* `build-compress-log` is now an alias to `compress-build-log`. - `build-cores` - *Deprecated:* `build-cores` is now an alias to - [varlistentry\_title](#conf-cores). + *Deprecated:* `build-cores` is now an alias to `cores`. - `build-extra-chroot-dirs` - *Deprecated:* `build-extra-chroot-dirs` is now an alias to - [varlistentry\_title](#conf-extra-sandbox-paths). + *Deprecated:* `build-extra-chroot-dirs` is now an alias to `extra-sandbox-paths`. - `build-extra-sandbox-paths` - *Deprecated:* `build-extra-sandbox-paths` is now an alias to - [varlistentry\_title](#conf-extra-sandbox-paths). + *Deprecated:* `build-extra-sandbox-paths` is now an alias to `extra-sandbox-paths`. - `build-fallback` - *Deprecated:* `build-fallback` is now an alias to - [varlistentry\_title](#conf-fallback). + *Deprecated:* `build-fallback` is now an alias to `fallback`. - `build-max-jobs` - *Deprecated:* `build-max-jobs` is now an alias to - [varlistentry\_title](#conf-max-jobs). + *Deprecated:* `build-max-jobs` is now an alias to `max-jobs`. - `build-max-log-size` - *Deprecated:* `build-max-log-size` is now an alias to - [varlistentry\_title](#conf-max-build-log-size). + *Deprecated:* `build-max-log-size` is now an alias to `max-build-log-size`. - `build-max-silent-time` - *Deprecated:* `build-max-silent-time` is now an alias to - [varlistentry\_title](#conf-max-silent-time). + *Deprecated:* `build-max-silent-time` is now an alias to `max-silent-time`. - `build-repeat` - *Deprecated:* `build-repeat` is now an alias to - [varlistentry\_title](#conf-repeat). + *Deprecated:* `build-repeat` is now an alias to `repeat`. - `build-timeout` - *Deprecated:* `build-timeout` is now an alias to - [varlistentry\_title](#conf-timeout). + *Deprecated:* `build-timeout` is now an alias to `timeout`. - `build-use-chroot` - *Deprecated:* `build-use-chroot` is now an alias to - [varlistentry\_title](#conf-sandbox). + *Deprecated:* `build-use-chroot` is now an alias to `sandbox`. - `build-use-sandbox` - *Deprecated:* `build-use-sandbox` is now an alias to - [varlistentry\_title](#conf-sandbox). + *Deprecated:* `build-use-sandbox` is now an alias to `sandbox`. - `build-use-substitutes` - *Deprecated:* `build-use-substitutes` is now an alias to - [varlistentry\_title](#conf-substitute). + *Deprecated:* `build-use-substitutes` is now an alias to `substitute`. - `gc-keep-derivations` - *Deprecated:* `gc-keep-derivations` is now an alias to - [varlistentry\_title](#conf-keep-derivations). + *Deprecated:* `gc-keep-derivations` is now an alias to `keep-derivations`. - `gc-keep-outputs` - *Deprecated:* `gc-keep-outputs` is now an alias to - [varlistentry\_title](#conf-keep-outputs). + *Deprecated:* `gc-keep-outputs` is now an alias to `keep-outputs`. - `env-keep-derivations` - *Deprecated:* `env-keep-derivations` is now an alias to - [varlistentry\_title](#conf-keep-env-derivations). + *Deprecated:* `env-keep-derivations` is now an alias to `keep-env-derivations`. - `extra-binary-caches` - *Deprecated:* `extra-binary-caches` is now an alias to - [varlistentry\_title](#conf-extra-substituters). + *Deprecated:* `extra-binary-caches` is now an alias to `extra-substituters`. - `trusted-binary-caches` - *Deprecated:* `trusted-binary-caches` is now an alias to - [varlistentry\_title](#conf-trusted-substituters). + *Deprecated:* `trusted-binary-caches` is now an alias to `trusted-substituters`. diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md index 14e08e0f1..e5fd45a7f 100644 --- a/doc/manual/src/command-ref/env-common.md +++ b/doc/manual/src/command-ref/env-common.md @@ -92,9 +92,10 @@ Most Nix commands interpret the following environment variables: - `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](#ssec-multi-user). If the Nix daemon's Unix - socket is at some non-standard path, this variable should be set to - `unix://path/to/socket`. Otherwise, it should be left unset. + Nix installations](../installation/multi-user.md). If the Nix + daemon's Unix socket is at some non-standard path, this variable + should be set to `unix://path/to/socket`. Otherwise, it should be + left unset. - `NIX_SHOW_STATS` If set to `1`, Nix will print some evaluation statistics, such as diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 81dc26a39..026495c8d 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -32,9 +32,10 @@ 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 +[`nix-instantiate`](nix-instantiate.md) (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). +--realise`](nix-store.md#operation---realise) (to build the store +derivation). > **Warning** > diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md index 7b246f3b3..37587c7e1 100644 --- a/doc/manual/src/command-ref/nix-collect-garbage.md +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -11,16 +11,16 @@ Title: nix-collect-garbage # 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). +--gc`](nix-store.md#operation---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 diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index ab1d10c08..c5fcce316 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -92,7 +92,7 @@ have an effect. 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 + [substituted](../glossary.md) (i.e., downloaded) and which paths will be built from source (because no substitute is available). - `--system-filter` *system* @@ -186,11 +186,11 @@ a number of possible ways: 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 + - If `--attr` (`-A`) is specified, the arguments are *attribute + paths* that select attributes from the top-level Nix expression. This is faster than using derivation names and - unambiguous. To find out the attribute paths of available packages, - use `nix-env -qaP`. + 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 @@ -198,18 +198,19 @@ a number of possible ways: 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. + [functions](../expressions/language-constructs.md#functions) + that are called with the active Nix expression as their single + argument. The derivations returned by those function calls are + installed. This allows derivations to be specified in an + unambiguous way, which is necessary if there are multiple + derivations with the same name. - If *args* are store derivations, then these are - [realised](#rsec-nix-store-realise), and the resulting output paths + [realised](nix-store.md#operation---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. + are [realised](nix-store.md#operation---realise) and installed. - By default all outputs are installed for each derivation. That can be reduced by setting `meta.outputsToInstall`. @@ -319,9 +320,9 @@ 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. +[`--install`](#operation---install). If *args* describes multiple +store paths with the same symbolic name, only the one with the highest +version is installed. ## Flags @@ -584,9 +585,9 @@ derivation is shown unless `--no-name` is specified. - `--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` + unambiguously select it using the `--attr` option available in + commands that install derivations like `nix-env --install`. This + option only works together with `--available` - `--no-name` Suppress printing of the `name` attribute of each derivation. diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md index 38c9e0f67..edb331e1c 100644 --- a/doc/manual/src/command-ref/nix-hash.md +++ b/doc/manual/src/command-ref/nix-hash.md @@ -21,13 +21,13 @@ 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`. +The hash is computed over a *serialisation* of each path: a dump of +the file system tree rooted at the path. This allows directories and +symlinks to be hashed as well as regular files. The dump is in the +*NAR format* produced by [`nix-store +--dump`](nix-store.md#operation---dump). Thus, `nix-hash path` +yields the same cryptographic hash as `nix-store --dump path | +md5sum`. # Options diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index ca9ef1fc9..2d6525e77 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -21,11 +21,11 @@ Title: nix-instantiate # Description The command `nix-instantiate` generates [store -derivations](#gloss-derivation) from (high-level) Nix expressions. It +derivations](../glossary.md) 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. +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. @@ -33,7 +33,7 @@ standard input. # Options - `--add-root` *path*; `--indirect` - See the [corresponding options](#opt-add-root) in `nix-store`. + See the [corresponding options](nix-store.md) in `nix-store`. - `--parse` Just parse the input files, and print their abstract syntax trees on @@ -69,7 +69,7 @@ standard input. 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). + built-in](../expressions/builtins.md). - `--read-write-mode` When used with `--eval`, perform evaluation in read/write mode so diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md index b15340fde..1842f8858 100644 --- a/doc/manual/src/command-ref/nix-store.md +++ b/doc/manual/src/command-ref/nix-store.md @@ -79,13 +79,14 @@ 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. + output paths of the derivation are [valid](../glossary.md) (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](../glossary.md) + 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 @@ -129,11 +130,12 @@ Special exit codes: - `101` Build timeout, the build was aborted because it did not complete - within the specified [`timeout`](#conf-timeout). + within the specified `timeout`. - `102` Hash mismatch, the build output was rejected because it does not - match the specified [`outputHash`](#fixed-output-drvs). + match the [`outputHash` attribute of the + derivation](../expressions/advanced-attributes.md). - `104` Not deterministic, the build succeeded in check mode but the @@ -153,12 +155,12 @@ or. ## Examples This operation is typically used to build store derivations produced by -[`nix-instantiate`](#sec-nix-instantiate): +[`nix-instantiate`](nix-instantiate.md): $ nix-store -r $(nix-instantiate ./test.nix) /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1 -This is essentially what [`nix-build`](#sec-nix-build) does. +This is essentially what [`nix-build`](nix-build.md) does. To test whether a previously-built derivation is deterministic: @@ -232,8 +234,7 @@ control what gets deleted and in what order: 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 +`keep-outputs` and `keep-derivations` variables in the Nix configuration file. By default, the collector prints the total number of freed bytes when it @@ -307,17 +308,17 @@ symlink. - `--force-realise`; `-f` Realise each argument to the query first (see [`nix-store - --realise`](#rsec-nix-store-realise)). + --realise`](#operation---realise)). ## Queries - `--outputs` - Prints out the [output paths](#gloss-output-path) of the store + 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` - Prints out the [closure](#gloss-closure) of the store path *paths*. + Prints out the [closure](../glossary.md) of the store path *paths*. This query has one option: @@ -334,7 +335,7 @@ symlink. derivation and specifying the option `--include-outputs`. - `--references` - Prints the set of [references](#gloss-reference) of the store paths + Prints the set of [references](../glossary.md) of the store paths *paths*, that is, their immediate dependencies. (For *all* dependencies, use `--requisites`.) @@ -352,7 +353,7 @@ symlink. in the Nix store that are dependent on *paths*. - `--deriver`; `-d` - Prints the [deriver](#gloss-deriver) of the store paths *paths*. If + 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. @@ -605,13 +606,12 @@ 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. +produce the same NAR archive. For instance, directory entries are +always sorted so that the actual on-disk order doesn’t influence the +result. This means that the cryptographic hash of a NAR dump of a +path is usable as a fingerprint of the contents of the path. Indeed, +the hashes of store paths stored in Nix’s database (see `nix-store -q +--hash`) are SHA-256 hashes of the NAR dump of each store path. NAR archives support filenames of unlimited length and 64-bit file sizes. They can contain regular files, directories, and symbolic links, diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md index b9c65c81d..ee8419fd2 100644 --- a/doc/manual/src/command-ref/opt-common.md +++ b/doc/manual/src/command-ref/opt-common.md @@ -71,35 +71,34 @@ Most Nix commands accept the following command-line options: - `--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`](#conf-max-jobs) configuration setting, which itself - defaults to `1`. A higher value is useful on SMP systems or to - exploit I/O latency. + 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` - 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 + 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 instance, in Nixpkgs, if the derivation attribute `enableParallelBuilding` is set to `true`, the builder passes the - `-jN` flag to GNU Make. It defaults to the value of the - [`cores`](#conf-cores) configuration setting, if set, or `1` - otherwise. The value `0` means that the builder should use all - available CPU cores in the system. + `-jN` flag to GNU Make. It defaults to the value of the `cores` + configuration setting, if set, or `1` otherwise. The value `0` + means that the builder should use all available CPU cores in the + system. - `--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`](#conf-max-silent-time) - configuration setting. `0` means no time-out. + 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` Sets the maximum number of seconds that a builder can run. The - default is specified by the [`timeout`](#conf-timeout) configuration - setting. `0` means no timeout. + default is specified by the `timeout` configuration setting. `0` + means no timeout. - `--keep-going` / `-k` Keep going in case of failed builds, to the greatest extent @@ -145,16 +144,17 @@ Most Nix commands accept the following command-line options: operations will fail. - `--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 it - encounters. It can automatically call functions for which every - argument has a [default value](#ss-functions) (e.g., `{ argName ? - defaultValue }: - ...`). With `--arg`, you can also call functions that have arguments - without a default value (or override a default value). That is, if - the evaluator encounters a function with an argument named *name*, - it will call it with value *value*. + This option is accepted by `nix-env`, `nix-instantiate`, + `nix-shell` and `nix-build`. When evaluating Nix expressions, the + expression evaluator will automatically try to call functions that + it encounters. It can automatically call functions for which every + argument has a [default + value](../expressions/language-constructs.md#functions) (e.g., + `{ argName ? defaultValue }: ...`). With `--arg`, you can also + call functions that have arguments without a default value (or + override a default value). That is, if the evaluator encounters a + 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: @@ -165,28 +165,28 @@ 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`](#builtin-currentSystem) for the `system` - argument. You can override this using `--arg`, e.g., `nix-env -i - pkgname --arg system - \"i686-freebsd\"`. (Note that since the argument is a Nix string - literal, you have to escape the quotes.) + pkgname`), the function will be called automatically using the + value [`builtins.currentSystem`](../expressions/builtins.md) for + the `system` argument. You can override this using `--arg`, e.g., + `nix-env -i pkgname --arg system \"i686-freebsd\"`. (Note that + since the argument is a Nix string literal, you have to escape the + quotes.) - `--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`. + 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* Select an attribute from the top-level Nix expression being evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and - `nix-shell` only.) The *attribute path* *attrPath* is a sequence of - attribute names separated by dots. For instance, given a top-level - Nix expression *e*, the attribute path `xorg.xorgserver` would cause - the expression `e.xorg.xorgserver` to be used. See [`nix-env - --install`](#refsec-nix-env-install-examples) for some concrete - examples. + `nix-shell` only.) The *attribute path* *attrPath* is a sequence + of attribute names separated by dots. For instance, given a + top-level Nix expression *e*, the attribute path `xorg.xorgserver` + would cause the expression `e.xorg.xorgserver` to be used. See + [`nix-env --install`](nix-env.md#operation---install) for some + concrete examples. In addition to attribute names, you can also specify array indices. For instance, the attribute path `foo.3.bar` selects the `bar` |