diff options
Diffstat (limited to 'doc/manual')
21 files changed, 247 insertions, 264 deletions
diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md index 4f24febb0..76a5380bf 100644 --- a/doc/manual/src/advanced-topics/distributed-builds.md +++ b/doc/manual/src/advanced-topics/distributed-builds.md @@ -134,8 +134,7 @@ causes the list of machines in `/etc/nix/machines` to be included. (This is the default.) If you want the builders to use caches, you likely want to set the -option [`builders-use-substitutes`](#conf-builders-use-substitutes) in -your local `nix.conf`. +option `builders-use-substitutes` in your local `nix.conf`. To build only on remote builders and disable building on the local machine, you can use the option `--max-jobs 0`. diff --git a/doc/manual/src/advanced-topics/post-build-hook.md b/doc/manual/src/advanced-topics/post-build-hook.md index 0d02a8ff3..7b3ae58fb 100644 --- a/doc/manual/src/advanced-topics/post-build-hook.md +++ b/doc/manual/src/advanced-topics/post-build-hook.md @@ -108,5 +108,4 @@ We now have a Nix installation configured to automatically sign and upload every local build to a remote binary cache. Before deploying this to production, be sure to consider the -implementation caveats in [Implementation -Caveats](#chap-post-build-hook-caveats). +[implementation caveats](#implementation-caveats). 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` diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md index 3582fa268..bfee28acf 100644 --- a/doc/manual/src/expressions/advanced-attributes.md +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -89,10 +89,10 @@ Derivations can declare some infrequently used optional attributes. to make it use the proxy server configuration specified by the user in the environment variables `http_proxy` and friends. - This attribute is only allowed in [fixed-output - derivations](#fixed-output-drvs), where impurities such as these are - okay since (the hash of) the output is known in advance. It is - ignored for all other derivations. + This attribute is only allowed in *fixed-output derivations* (see + below), where impurities such as these are okay since (the hash + of) the output is known in advance. It is ignored for all other + derivations. > **Warning** > @@ -183,13 +183,14 @@ Derivations can declare some infrequently used optional attributes. - `"recursive"` The hash is computed over the NAR archive dump of the output (i.e., the result of [`nix-store - --dump`](#refsec-nix-store-dump)). In this case, the output can - be anything, including a directory tree. - - The `outputHash` attribute, finally, must be a string containing the - hash in either hexadecimal or base-32 notation. (See the [`nix-hash` - command](#sec-nix-hash) for information about converting to and from - base-32 notation.) + --dump`](../command-ref/nix-store.md#operation---dump)). In + this case, the output can be anything, including a directory + tree. + + The `outputHash` attribute, finally, must be a string containing + the hash in either hexadecimal or base-32 notation. (See the + [`nix-hash` command](../command-ref/nix-hash.md) for information + about converting to and from base-32 notation.) - `passAsFile` A list of names of attributes that should be passed via files rather @@ -213,10 +214,11 @@ Derivations can declare some infrequently used optional attributes. - `preferLocalBuild` If this attribute is set to `true` and [distributed building is - enabled](#chap-distributed-builds), then, if possible, the derivaton - will be built locally instead of forwarded to a remote machine. This - is appropriate for trivial builders where the cost of doing a - download or remote build would exceed the cost of building locally. + enabled](../advanced-topics/distributed-builds.md), then, if + possible, the derivaton will be built locally instead of forwarded + to a remote machine. This is appropriate for trivial builders + where the cost of doing a download or remote build would exceed + the cost of building locally. - `allowSubstitutes` If this attribute is set to `false`, then Nix will always build this diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md index 3c9bb4533..22f133c33 100644 --- a/doc/manual/src/expressions/builtins.md +++ b/doc/manual/src/expressions/builtins.md @@ -57,19 +57,19 @@ For instance, `derivation` is also available as `builtins.derivation`. installations that don’t have the desired built-in function. - `builtins.compareVersions` *s1* *s2* - Compare two strings representing versions and return `-1` if version - *s1* is older than version *s2*, `0` if they are the same, and `1` - if *s1* is newer than *s2*. The version comparison algorithm is the - same as the one used by [`nix-env - -u`](#ssec-version-comparisons). + Compare two strings representing versions and return `-1` if + version *s1* is older than version *s2*, `0` if they are the same, + and `1` if *s1* is newer than *s2*. The version comparison + algorithm is the same as the one used by [`nix-env + -u`](../command-ref/nix-env.md#operation---upgrade). - `builtins.concatLists` *lists* Concatenate a list of lists into a single list. - `builtins.concatStringsSep` *separator* *list* - Concatenate a list of strings with a separator between each element, - e.g. `concatStringsSep "/" - ["usr" "local" "bin"] == "usr/local/bin"` + Concatenate a list of strings with a separator between each + element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] == + "usr/local/bin"` - `builtins.currentSystem` The built-in value `currentSystem` evaluates to the Nix platform @@ -77,10 +77,9 @@ For instance, `derivation` is also available as `builtins.derivation`. evaluated, such as `"i686-linux"` or `"x86_64-darwin"`. - `builtins.deepSeq` *e1* *e2* - This is like `seq - e1 - e2`, except that *e1* is evaluated *deeply*: if it’s a list or set, - its elements or attributes are also evaluated recursively. + This is like `seq e1 e2`, except that *e1* is evaluated *deeply*: + if it’s a list or set, its elements or attributes are also + evaluated recursively. - `derivation` *attrs*; `builtins.derivation` *attrs* `derivation` is described in [its own section](derivations.md). @@ -104,7 +103,7 @@ For instance, `derivation` is also available as `builtins.derivation`. - `builtins.fetchurl` *url* Download the specified URL and return the path of the downloaded file. This function is not available if [restricted evaluation - mode](#conf-restrict-eval) is enabled. + mode](../command-ref/conf-file.md) is enabled. - `fetchTarball` *url*; `builtins.fetchTarball` *url* Download the specified URL, unpack it and return the path of the @@ -140,7 +139,7 @@ For instance, `derivation` is also available as `builtins.derivation`. stdenv.mkDerivation { … } This function is not available if [restricted evaluation - mode](#conf-restrict-eval) is enabled. + mode](../command-ref/conf-file.md) is enabled. - `builtins.fetchGit` *args* Fetch a path from git. *args* can be a URL, in which case the HEAD @@ -491,9 +490,8 @@ For instance, `derivation` is also available as `builtins.derivation`. name is everything up to but not including the first dash followed by a digit, and the version is everything following that dash. The result is returned in a set `{ name, version }`. Thus, - `builtins.parseDrvName "nix-0.12pre12876"` returns `{ name = "nix"; - version = "0.12pre12876"; - }`. + `builtins.parseDrvName "nix-0.12pre12876"` returns `{ name = + "nix"; version = "0.12pre12876"; }`. - `builtins.path` *args* An enrichment of the built-in path type, based on the attributes @@ -508,9 +506,8 @@ For instance, `derivation` is also available as `builtins.derivation`. like `@`. - filter - A function of the type expected by - [builtins.filterSource](#builtin-filterSource), with the same - semantics. + A function of the type expected by `builtins.filterSource`, + with the same semantics. - recursive When `false`, when `path` is added to the store it is with a @@ -609,7 +606,7 @@ For instance, `derivation` is also available as `builtins.derivation`. - `builtins.splitVersion` *s* Split a string representing a version into its components, by the same version splitting logic underlying the version comparison in - [`nix-env -u`](#ssec-version-comparisons). + [`nix-env -u`](../command-ref/nix-env.md#operation---upgrade). - `builtins.stringLength` *e* Return the length of the string *e*. If *e* is not a string, diff --git a/doc/manual/src/expressions/simple-building-testing.md b/doc/manual/src/expressions/simple-building-testing.md index c3e8d7f82..ca422acea 100644 --- a/doc/manual/src/expressions/simple-building-testing.md +++ b/doc/manual/src/expressions/simple-building-testing.md @@ -19,11 +19,11 @@ yet. The best way to test the package is by using the command $ ./result/bin/hello Hello, world! -The [`-A`](#opt-attr) option selects the `hello` attribute. This is -faster than using the symbolic package name specified by the `name` -attribute (which also happens to be `hello`) and is unambiguous (there -can be multiple packages with the symbolic name `hello`, but there can -be only one attribute in a set named `hello`). +The `-A` option selects the `hello` attribute. This is faster than +using the symbolic package name specified by the `name` attribute +(which also happens to be `hello`) and is unambiguous (there can be +multiple packages with the symbolic name `hello`, but there can be +only one attribute in a set named `hello`). `nix-build` registers the `./result` symlink as a garbage collection root, so unless and until you delete the `./result` symlink, the output diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md index 6983452d3..a1dd993c4 100644 --- a/doc/manual/src/installation/installing-binary.md +++ b/doc/manual/src/installation/installing-binary.md @@ -8,7 +8,7 @@ easiest way to install Nix is to run the following command: ``` If you're using macOS 10.15 (Catalina) or newer, consult [the macOS -installation instructions](#sect-macos-installation) before installing. +installation instructions](#macos-installation) before installing. As of Nix 2.1.0, the Nix installer will always default to creating a single-user installation, however opting in to the multi-user @@ -64,7 +64,7 @@ will invoke `sudo` as needed. > > If you need Nix to use a different group ID or user ID set, you will > have to download the tarball manually and [edit the install -> script](#sect-nix-install-binary-tarball). +> script](#installing-from-a-binary-tarball). The installer will modify `/etc/bashrc`, and `/etc/zshrc` if they exist. The installer will first back up these files with a `.backup-before-nix` diff --git a/doc/manual/src/installation/multi-user.md b/doc/manual/src/installation/multi-user.md index 4a861691d..de159b603 100644 --- a/doc/manual/src/installation/multi-user.md +++ b/doc/manual/src/installation/multi-user.md @@ -39,16 +39,16 @@ expect to do many builds at the same time. ## Running the daemon -The [Nix daemon](#sec-nix-daemon) should be started as follows (as -`root`): +The [Nix daemon](../command-ref/nix-daemon.md) should be started as +follows (as `root`): $ nix-daemon You’ll want to put that line somewhere in your system’s boot scripts. To let unprivileged users use the daemon, they should set the -[`NIX_REMOTE` environment variable](#envar-remote) to `daemon`. So you -should put a line like +[`NIX_REMOTE` environment variable](../command-ref/env-common.md) to +`daemon`. So you should put a line like export NIX_REMOTE=daemon diff --git a/doc/manual/src/package-management/basic-package-mgmt.md b/doc/manual/src/package-management/basic-package-mgmt.md index 8edaca6b0..17b5cc9c2 100644 --- a/doc/manual/src/package-management/basic-package-mgmt.md +++ b/doc/manual/src/package-management/basic-package-mgmt.md @@ -1,8 +1,9 @@ # Basic Package Management -The main command for package management is [`nix-env`](#sec-nix-env). -You can use it to install, upgrade, and erase packages, and to query -what packages are installed or are available for installation. +The main command for package management is +[`nix-env`](../command-ref/nix-env.md). You can use it to install, +upgrade, and erase packages, and to query what packages are installed +or are available for installation. In Nix, different users can have different “views” on the set of installed applications. That is, there might be lots of applications diff --git a/doc/manual/src/package-management/channels.md b/doc/manual/src/package-management/channels.md index 8a3e92d70..c239998d9 100644 --- a/doc/manual/src/package-management/channels.md +++ b/doc/manual/src/package-management/channels.md @@ -7,8 +7,8 @@ better way: *Nix channels*. A Nix channel is just a URL that points to a place that contains a set of Nix expressions and a manifest. Using the command -[`nix-channel`](#sec-nix-channel) you can automatically stay up to date -with whatever is available at that URL. +[`nix-channel`](../command-ref/nix-channel.md) you can automatically +stay up to date with whatever is available at that URL. To see the list of official NixOS channels, visit <https://nixos.org/channels>. diff --git a/doc/manual/src/package-management/s3-substituter.md b/doc/manual/src/package-management/s3-substituter.md index d96114e3c..2824c1a9b 100644 --- a/doc/manual/src/package-management/s3-substituter.md +++ b/doc/manual/src/package-management/s3-substituter.md @@ -1,9 +1,9 @@ # Serving a Nix store via S3 Nix has built-in support for storing and fetching store paths from -Amazon S3 and S3-compatible services. This uses the same *binary* cache -mechanism that Nix usually uses to fetch prebuilt binaries from -[cache.nixos.org](cache.nixos.org). +Amazon S3 and S3-compatible services. This uses the same *binary* +cache mechanism that Nix usually uses to fetch prebuilt binaries from +[cache.nixos.org](https://cache.nixos.org/). The following options can be specified as URL parameters to the S3 URL: @@ -85,8 +85,8 @@ caches. Your bucket will need a bucket policy allowing the desired users to perform the `s3:GetObject` and `s3:GetBucketLocation` action on all -objects in the bucket. The anonymous policy in [Anonymous Reads to your -S3-compatible binary cache](#ssec-s3-substituter-anonymous-reads) can be +objects in the bucket. The [anonymous policy given +above](#anonymous-reads-to-your-s3-compatible-binary-cache) can be updated to have a restricted `Principal` to support this. ## Authenticated Writes to your S3-compatible binary cache diff --git a/doc/manual/src/release-notes/rl-2.0.md b/doc/manual/src/release-notes/rl-2.0.md index 170275f89..9f6d4aa83 100644 --- a/doc/manual/src/release-notes/rl-2.0.md +++ b/doc/manual/src/release-notes/rl-2.0.md @@ -148,11 +148,11 @@ This release has the following new features: `nix-store --verify-path`. - - `nix log` shows the build log of a package or path. If the build - log is not available locally, it will try to obtain it from the - configured substituters (such as - [cache.nixos.org](cache.nixos.org), which now provides build - logs). + - `nix log` shows the build log of a package or path. If the + build log is not available locally, it will try to obtain it + from the configured substituters (such as + [cache.nixos.org](https://cache.nixos.org/), which now + provides build logs). - `nix edit` opens the source code of a package in your editor. @@ -213,16 +213,17 @@ This release has the following new features: current values. - The store abstraction that Nix has had for a long time to support - store access via the Nix daemon has been extended significantly. In - particular, substituters (which used to be external programs such as - `download-from-binary-cache`) are now subclasses of the abstract - `Store` class. This allows many Nix commands to operate on such - store types. For example, `nix path-info` shows information about - paths in your local Nix store, while `nix path-info --store - https://cache.nixos.org/` shows information about paths in the - specified binary cache. Similarly, `nix-copy-closure`, `nix-push` - and substitution are all instances of the general notion of copying - paths between different kinds of Nix stores. + store access via the Nix daemon has been extended + significantly. In particular, substituters (which used to be + external programs such as `download-from-binary-cache`) are now + subclasses of the abstract `Store` class. This allows many Nix + commands to operate on such store types. For example, `nix + path-info` shows information about paths in your local Nix store, + while `nix path-info --store https://cache.nixos.org/` shows + information about paths in the specified binary cache. Similarly, + `nix-copy-closure`, `nix-push` and substitution are all instances + of the general notion of copying paths between different kinds of + Nix stores. Stores are specified using an URI-like syntax, e.g. <https://cache.nixos.org/> or <ssh://machine>. The following store @@ -241,7 +242,7 @@ This release has the following new features: `/home/alice/nix/store`) to differ from its “logical” location (typically `/nix/store`). This allows non-root users to use Nix while still getting the benefits from prebuilt binaries from - [cache.nixos.org](cache.nixos.org). + [cache.nixos.org](https://cache.nixos.org/). - `BinaryCacheStore` is the abstract superclass of all binary cache stores. It supports writing build logs and NAR content @@ -356,11 +357,11 @@ This release has the following new features: - `NIX_PATH` is now lazy, so URIs in the path are only downloaded if they are needed for evaluation. - - You can now use <channel:> as a short-hand for + - You can now use `channel:` as a short-hand for <https://nixos.org/channels//nixexprs.tar.xz>. For example, `nix-build channel:nixos-15.09 -A hello` will build the GNU Hello - package from the `nixos-15.09` channel. In the future, this may use - Git to fetch updates more efficiently. + package from the `nixos-15.09` channel. In the future, this may + use Git to fetch updates more efficiently. - When `--no-build-output` is given, the last 10 lines of the build log will be shown if a build fails. @@ -382,7 +383,7 @@ This release has the following new features: in all places where Nix allows URIs. - Brotli compression is now supported. In particular, - [cache.nixos.org](cache.nixos.org) build logs are now compressed + [cache.nixos.org](https://cache.nixos.org/) build logs are now compressed using Brotli. - `nix-env` diff --git a/doc/manual/src/release-notes/rl-2.1.md b/doc/manual/src/release-notes/rl-2.1.md index 08986ef9d..b88834c83 100644 --- a/doc/manual/src/release-notes/rl-2.1.md +++ b/doc/manual/src/release-notes/rl-2.1.md @@ -4,18 +4,18 @@ This is primarily a bug fix release. It also reduces memory consumption in certain situations. In addition, it has the following new features: - The Nix installer will no longer default to the Multi-User - installation for macOS. You can still [instruct the installer to run - in multi-user mode](#sect-multi-user-installation). - - - The Nix installer now supports performing a Multi-User installation - for Linux computers which are running systemd. You can [select a - Multi-User installation](#sect-multi-user-installation) by passing - the `--daemon` flag to the installer: `sh <(curl - https://nixos.org/nix/install) --daemon`. - - The multi-user installer cannot handle systems with SELinux. If your - system has SELinux enabled, you can [force the installer to run in - single-user mode](#sect-single-user-installation). + installation for macOS. You can still instruct the installer to + run in multi-user mode. + + - The Nix installer now supports performing a Multi-User + installation for Linux computers which are running systemd. You + can select a Multi-User installation by passing the `--daemon` + flag to the installer: `sh <(curl https://nixos.org/nix/install) + --daemon`. + + The multi-user installer cannot handle systems with SELinux. If + your system has SELinux enabled, you can force the installer to + run in single-user mode. - New builtin functions: `builtins.bitAnd`, `builtins.bitOr`, `builtins.bitXor`, `builtins.fromTOML`, `builtins.concatMap`, |