diff options
| author | Eelco Dolstra <edolstra@gmail.com> | 2020-07-23 10:44:54 +0200 |
|---|---|---|
| committer | Eelco Dolstra <edolstra@gmail.com> | 2020-07-23 18:27:11 +0200 |
| commit | f3903035667e158112dfd414091d8d50ef90c5f4 (patch) | |
| tree | 4b9e6e9568104e1cf46cfd0e6f5e7103ddfadd27 /doc | |
| parent | c20c0823838d257b1e18e71c307f53afac0d2b39 (diff) | |
Reconvert
Diffstat (limited to 'doc')
29 files changed, 433 insertions, 95 deletions
diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md index f562d1db4..f9ef1b060 100644 --- a/doc/manual/src/SUMMARY.md +++ b/doc/manual/src/SUMMARY.md @@ -45,6 +45,8 @@ - [Verifying Build Reproducibility](advanced-topics/diff-hook.md) - [Using the `post-build-hook`](advanced-topics/post-build-hook.md) - [Command Reference](command-ref/command-ref.md) + - [Common Options](command-ref/opt-common.md) + - [Common Environment Variables](command-ref/env-common.md) - [Utilities](command-ref/utilities.md) - [nix-copy-closure](command-ref/nix-copy-closure.md) - [Glossary](glossary.md) diff --git a/doc/manual/src/advanced-topics/cores-vs-jobs.md b/doc/manual/src/advanced-topics/cores-vs-jobs.md index 846b6356e..91e95d5b4 100644 --- a/doc/manual/src/advanced-topics/cores-vs-jobs.md +++ b/doc/manual/src/advanced-topics/cores-vs-jobs.md @@ -16,18 +16,18 @@ configuration trade-offs. -j`. The [???](#conf-cores) setting determines the value of -NIX\_BUILD\_CORES. NIX\_BUILD\_CORES is equal to [???](#conf-cores), -unless [???](#conf-cores) equals `0`, in which case NIX\_BUILD\_CORES +`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to [???](#conf-cores), +unless [???](#conf-cores) equals `0`, in which case `NIX_BUILD_CORES` will be the total number of cores in the system. The maximum number of consumed cores is a simple multiplication, -[???](#conf-max-jobs) \* NIX\_BUILD\_CORES. +[???](#conf-max-jobs) \* `NIX_BUILD_CORES`. The balance on how to set these two independent variables depends upon each builder's workload and hardware. Here are a few example scenarios on a machine with 24 cores: -| [???](#conf-max-jobs) | [???](#conf-cores) | NIX\_BUILD\_CORES | Maximum Processes | Result | +| [???](#conf-max-jobs) | [???](#conf-cores) | `NIX_BUILD_CORES` | Maximum Processes | Result | | --------------------- | ------------------ | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | 24 | 24 | 24 | One derivation will be built at a time, each one can use 24 cores. Undersold if a job can’t use 24 cores. | | 4 | 6 | 6 | 24 | Four derivations will be built at once, each given access to six cores. | @@ -38,5 +38,5 @@ on a machine with 24 cores: Balancing 24 Build Cores It is up to the derivations' build script to respect host's requested -cores-per-build by following the value of the NIX\_BUILD\_CORES +cores-per-build by following the value of the `NIX_BUILD_CORES` environment variable. diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md index 197708ee5..4f24febb0 100644 --- a/doc/manual/src/advanced-topics/distributed-builds.md +++ b/doc/manual/src/advanced-topics/distributed-builds.md @@ -27,7 +27,7 @@ If you get the error bash: nix-store: command not found error: cannot connect to 'mac' -then you need to ensure that the PATH of non-interactive login shells +then you need to ensure that the `PATH` of non-interactive login shells contains Nix. > **Warning** diff --git a/doc/manual/src/command-ref/command-ref.md b/doc/manual/src/command-ref/command-ref.md index b15a50a3b..2c7dbf22e 100644 --- a/doc/manual/src/command-ref/command-ref.md +++ b/doc/manual/src/command-ref/command-ref.md @@ -1,2 +1,4 @@ +# Command Reference + This section lists commands and options that you can use when you work with Nix. diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md new file mode 100644 index 000000000..14e08e0f1 --- /dev/null +++ b/doc/manual/src/command-ref/env-common.md @@ -0,0 +1,112 @@ +# Common Environment Variables + +Most Nix commands interpret the following environment variables: + + - `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` + 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` + 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 + resolving all symlink components. Thus, builds on different machines + (with `/nix/store` resolving to different locations) could yield + different results. This is generally not a problem, except when + 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., + + $ mkdir /nix + $ mount -o bind /mnt/otherdisk/nix /nix + + Consult the mount 8 manual page for details. + + - `NIX_STORE_DIR` + Overrides the location of the Nix store (default `prefix/store`). + + - `NIX_DATA_DIR` + Overrides the location of the Nix static data directory (default + `prefix/share`). + + - `NIX_LOG_DIR` + Overrides the location of the Nix log directory (default + `prefix/var/log/nix`). + + - `NIX_STATE_DIR` + Overrides the location of the Nix state directory (default + `prefix/var/nix`). + + - `NIX_CONF_DIR` + Overrides the location of the system Nix configuration directory + (default `prefix/etc/nix`). + + - `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` + 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` + 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_SHOW_STATS` + If set to `1`, Nix will print some evaluation statistics, such as + the number of values allocated. + + - `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` + 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 + will increase runtime due to the overhead of garbage collection. diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md new file mode 100644 index 000000000..ac9d996c3 --- /dev/null +++ b/doc/manual/src/command-ref/opt-common.md @@ -0,0 +1,221 @@ +# Common Options + +Most Nix commands accept the following command-line options: + + - `--help` + Prints out a summary of the command syntax and exits. + + - `--version` + Prints out the Nix version number on standard output and exits. + + - `--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 + “Errors only”: only print messages explaining why the Nix + invocation failed. + + - 1 + “Informational”: print *useful* messages about what Nix is + doing. This is the default. + + - 2 + “Talkative”: print more informational messages. + + - 3 + “Chatty”: print even more informational messages. + + - 4 + “Debug”: print debug information. + + - 5 + “Vomit”: print vast amounts of debug information. + + - `--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 + This option can be used to change the output of the log format, with + format being one of: + + - raw + This is the raw format, as outputted by nix-build. + + - internal-json + Outputs the logs in a structured manner. NOTE: the json schema + is not guarantees to be stable between releases. + + - bar + Only display a progress bar during the builds. + + - bar-with-logs + Display the raw logs, with the progress bar at the bottom. + + - `--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 + 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. + + 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 + 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. + + - `--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. + + - `--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. + + - `--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 + itself. Without this option, Nix stops if any build fails (except + for builds of substitutes), possibly killing builds in progress (in + case of parallel or distributed builds). + + - `--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` + 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 + realisation of the derivation will fail. When this option is + specified, Nix will build the derivation instead. Thus, installation + from binaries falls back on installation from source. This option is + not the default since it is generally not desirable for a transient + failure in obtaining the substitutes to lead to a full build from + source (with the related consumption of resources). + + - `--no-build-hook` + Disables the build hook mechanism. This allows to ignore remote + builders if they are setup on the machine. + + It's useful in cases where the bandwidth between the client and the + remote builder is too low. In that case it can take more time to + upload the sources to the remote builder and fetch back the result + than to do the computation locally. + + - `--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 + 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. + + For instance, the top-level `default.nix` in Nixpkgs is actually a + function: + + { # The system (e.g., `i686-linux') for which to build the packages. + system ? builtins.currentSystem + ... + }: ... + + 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.) + + - `--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 + 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. + + 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` + 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 + Add a path to the Nix expression search path. This option may be + given multiple times. See the NIX\_PATH\</literal\> environment + variable for information on the semantics of the Nix search path. + Paths added through `-I` take precedence over `NIX_PATH`. + + - `--option` name value + Set the Nix configuration option name to value. This overrides + settings in the Nix configuration file (see nix.conf5). + + - `--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 + the build. Also note the warning under `nix-store --repair-path`. diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md index 683b504a7..01e18513d 100644 --- a/doc/manual/src/expressions/advanced-attributes.md +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -87,7 +87,7 @@ Derivations can declare some infrequently used optional attributes. impureEnvVars = [ "http_proxy" "https_proxy" ... ]; to make it use the proxy server configuration specified by the user - in the environment variables http\_proxy and friends. + 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 @@ -201,15 +201,15 @@ Derivations can declare some infrequently used optional attributes. ``` - then when the builder runs, the environment variable bigPath will + then when the builder runs, the environment variable `bigPath` will contain the absolute path to a temporary file containing `a very long string`. That is, for any attribute x listed in `passAsFile`, Nix - will pass an environment variable xPath holding the path of the file - containing the value of attribute x. This is useful when you need to - pass large strings to a builder, since most operating systems impose - a limit on the size of the environment (typically, a few hundred - kilobyte). + will pass an environment variable `xPath` holding the path of the + file containing the value of attribute x. This is useful when you + need to pass large strings to a builder, since most operating + systems impose a limit on the size of the environment (typically, a + few hundred kilobyte). - `preferLocalBuild` If this attribute is set to `true` and [distributed building is diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md index 256a5cd44..a359ebc46 100644 --- a/doc/manual/src/expressions/build-script.md +++ b/doc/manual/src/expressions/build-script.md @@ -19,29 +19,29 @@ what a builder does. It performs the following steps: - When Nix runs a builder, it initially completely clears the environment (except for the attributes declared in the derivation). - For instance, the PATH variable is empty\[1\]. This is done to + For instance, the `PATH` variable is empty\[1\]. This is done to prevent undeclared inputs from being used in the build process. If - for example the PATH contained `/usr/bin`, then you might + for example the `PATH` contained `/usr/bin`, then you might accidentally use `/usr/bin/gcc`. So the first step is to set up the environment. This is done by calling the `setup` script of the standard environment. The - environment variable stdenv points to the location of the standard + environment variable `stdenv` points to the location of the standard environment being used. (It wasn't specified explicitly as an attribute in [???](#ex-hello-nix), but `mkDerivation` adds it automatically.) - Since Hello needs Perl, we have to make sure that Perl is in the - PATH. The perl environment variable points to the location of the - Perl package (since it was passed in as an attribute to the + `PATH`. The `perl` environment variable points to the location of + the Perl package (since it was passed in as an attribute to the derivation), so `$perl/bin` is the directory containing the Perl interpreter. - Now we have to unpack the sources. The `src` attribute was bound to the result of fetching the Hello source tarball from the network, so - the src environment variable points to the location in the Nix store - to which the tarball was downloaded. After unpacking, we `cd` to the - resulting source directory. + the `src` environment variable points to the location in the Nix + store to which the tarball was downloaded. After unpacking, we `cd` + to the resulting source directory. The whole build is performed in a temporary directory created in `/tmp`, by the way. This directory is removed after the builder @@ -55,13 +55,13 @@ what a builder does. It performs the following steps: separate location in the Nix store, for instance `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix computes this path by cryptographically hashing all attributes of - the derivation. The path is passed to the builder through the out + the derivation. The path is passed to the builder through the `out` environment variable. So here we give `configure` the parameter `--prefix=$out` to cause Hello to be installed in the expected location. - Finally we build Hello (`make`) and install it into the location - specified by out (`make install`). + specified by `out` (`make install`). If you are wondering about the absence of error checking on the result of various commands called in the builder: this is because the shell diff --git a/doc/manual/src/expressions/builder-syntax.md b/doc/manual/src/expressions/builder-syntax.md index c92acf106..916159d40 100644 --- a/doc/manual/src/expressions/builder-syntax.md +++ b/doc/manual/src/expressions/builder-syntax.md @@ -19,29 +19,29 @@ what a builder does. It performs the following steps: - When Nix runs a builder, it initially completely clears the environment (except for the attributes declared in the derivation). - For instance, the PATH variable is empty\[1\]. This is done to + For instance, the `PATH` variable is empty\[1\]. This is done to prevent undeclared inputs from being used in the build process. If - for example the PATH contained `/usr/bin`, then you might + for example the `PATH` contained `/usr/bin`, then you might accidentally use `/usr/bin/gcc`. So the first step is to set up the environment. This is done by calling the `setup` script of the standard environment. The - environment variable stdenv points to the location of the standard + environment variable `stdenv` points to the location of the standard environment being used. (It wasn't specified explicitly as an attribute in [???](#ex-hello-nix), but `mkDerivation` adds it automatically.) - Since Hello needs Perl, we have to make sure that Perl is in the - PATH. The perl environment variable points to the location of the - Perl package (since it was passed in as an attribute to the + `PATH`. The `perl` environment variable points to the location of + the Perl package (since it was passed in as an attribute to the derivation), so `$perl/bin` is the directory containing the Perl interpreter. - Now we have to unpack the sources. The `src` attribute was bound to the result of fetching the Hello source tarball from the network, so - the src environment variable points to the location in the Nix store - to which the tarball was downloaded. After unpacking, we `cd` to the - resulting source directory. + the `src` environment variable points to the location in the Nix + store to which the tarball was downloaded. After unpacking, we `cd` + to the resulting source directory. The whole build is performed in a temporary directory created in `/tmp`, by the way. This directory is removed after the builder @@ -55,13 +55,13 @@ what a builder does. It performs the following steps: separate location in the Nix store, for instance `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix computes this path by cryptographically hashing all attributes of - the derivation. The path is passed to the builder through the out + the derivation. The path is passed to the builder through the `out` environment variable. So here we give `configure` the parameter `--prefix=$out` to cause Hello to be installed in the expected location. - Finally we build Hello (`make`) and install it into the location - specified by out (`make install`). + specified by `out` (`make install`). If you are wondering about the absence of error checking on the result of various commands called in the builder: this is because the shell diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md index 7ffc6fabe..a4df20baa 100644 --- a/doc/manual/src/expressions/derivations.md +++ b/doc/manual/src/expressions/derivations.md @@ -83,32 +83,32 @@ as a command-line argument. See the Nixpkgs manual for details. The builder is executed as follows: - A temporary directory is created under the directory specified by - TMPDIR (default `/tmp`) where the build will take place. The current - directory is changed to this directory. + `TMPDIR` (default `/tmp`) where the build will take place. The + current directory is changed to this directory. - The environment is cleared and set to the derivation attributes, as specified above. - In addition, the following variables are set: - - NIX\_BUILD\_TOP contains the path of the temporary directory for + - `NIX_BUILD_TOP` contains the path of the temporary directory for this build. - - Also, TMPDIR, TEMPDIR, TMP, TEMP are set to point to the + - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the temporary directory. This is to prevent the builder from accidentally writing temporary files anywhere else. Doing so might cause interference by other processes. - - PATH is set to `/path-not-set` to prevent shells from + - `PATH` is set to `/path-not-set` to prevent shells from initialising it to their built-in default value. - - HOME is set to `/homeless-shelter` to prevent programs from + - `HOME` is set to `/homeless-shelter` to prevent programs from using `/etc/passwd` or the like to find the user's home - directory, which could cause impurity. Usually, when HOME is + directory, which could cause impurity. Usually, when `HOME` is set, it is used as the location of the home directory, even if it points to a non-existent path. - - NIX\_STORE is set to the path of the top-level Nix store + - `NIX_STORE` is set to the path of the top-level Nix store directory (typically, `/nix/store`). - For each output declared in `outputs`, the corresponding diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index cbc484199..a00b08b55 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -22,9 +22,9 @@ build facilities in shown in [example\_title](#ex-hello-builder2). genericBuild - - The buildInputs variable tells `setup` to use the indicated packages - as “inputs”. This means that if a package provides a `bin` - subdirectory, it's added to PATH; if it has a `include` + - The `buildInputs` variable tells `setup` to use the indicated + packages as “inputs”. This means that if a package provides a `bin` + subdirectory, it's added to `PATH`; if it has a `include` subdirectory, it's added to GCC's header search path; and so on.\[1\] @@ -37,7 +37,7 @@ build facilities in shown in [example\_title](#ex-hello-builder2). It can be customised in many ways; see the Nixpkgs manual for details. -Discerning readers will note that the buildInputs could just as well +Discerning readers will note that the `buildInputs` could just as well have been set in the Nix expression, like this: ``` @@ -57,5 +57,6 @@ entirely. 1. How does it work? `setup` tries to source the file `pkg/nix-support/setup-hook` of all dependencies. These “setup hooks” can then set up whatever environment variables they want; - for instance, the setup hook for Perl sets the PERL5LIB environment - variable to contain the `lib/site_perl` directories of all inputs. + for instance, the setup hook for Perl sets the `PERL5LIB` + environment variable to contain the `lib/site_perl` directories of + all inputs. diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index 98ad97c97..fac0be47e 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -120,8 +120,8 @@ Nix has the following basic data types: Paths can also be specified between angle brackets, e.g. `<nixpkgs>`. This means that the directories listed in the - environment variable NIX\_PATH will be searched for the given file - or directory name. + environment variable NIX\_PATH\</literal\> will be searched for the + given file or directory name. - *Booleans* with values `true` and `false`. diff --git a/doc/manual/src/expressions/simple-building-testing.md b/doc/manual/src/expressions/simple-building-testing.md index bc064c733..c3e8d7f82 100644 --- a/doc/manual/src/expressions/simple-building-testing.md +++ b/doc/manual/src/expressions/simple-building-testing.md @@ -32,7 +32,7 @@ of the build will be safely kept on your system. You can use Nix has transactional semantics. Once a build finishes successfully, Nix makes a note of this in its database: it registers that the path denoted -by out is now “valid”. If you try to build the derivation again, Nix +by `out` is now “valid”. If you try to build the derivation again, Nix will see that the path is already valid and finish immediately. If a build fails, either because it returns a non-zero exit code, because Nix or the builder are killed, or because the machine crashes, then the diff --git a/doc/manual/src/installation/env-variables.md b/doc/manual/src/installation/env-variables.md index 7946ac437..6e78245c9 100644 --- a/doc/manual/src/installation/env-variables.md +++ b/doc/manual/src/installation/env-variables.md @@ -1,7 +1,7 @@ # Environment Variables To use Nix, some environment variables should be set. In particular, -PATH should contain the directories `prefix/bin` and +`PATH` should contain the directories `prefix/bin` and `~/.nix-profile/bin`. The first directory contains the Nix tools themselves, while `~/.nix-profile` is a symbolic link to the current *user environment* (an automatically generated package consisting of @@ -12,13 +12,13 @@ this: source prefix/etc/profile.d/nix.sh -# NIX\_SSL\_CERT\_FILE +# `NIX_SSL_CERT_FILE` If you need to specify a custom certificate bundle to account for an HTTPS-intercepting man in the middle proxy, you must specify the path to -the certificate bundle in the environment variable NIX\_SSL\_CERT\_FILE. +the certificate bundle in the environment variable `NIX_SSL_CERT_FILE`. -If you don't specify a NIX\_SSL\_CERT\_FILE manually, Nix will install +If you don't specify a `NIX_SSL_CERT_FILE` manually, Nix will install and use its own certificate bundle. Set the environment variable and install Nix @@ -36,7 +36,7 @@ In the shell profile and rc files (for example, `/etc/bashrc`, > You must not add the export and then do the install, as the Nix > installer will detect the presense of Nix configuration, and abort. -## NIX\_SSL\_CERT\_FILE with macOS and the Nix daemon +## `NIX_SSL_CERT_FILE` with macOS and the Nix daemon On macOS you must specify the environment variable for the Nix daemon service, then restart it: diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md index d4e412e67..6983452d3 100644 --- a/doc/manual/src/installation/installing-binary.md +++ b/doc/manual/src/installation/installing-binary.md @@ -34,8 +34,8 @@ manually create `/nix` first as root, e.g.: The install script will modify the first writable file from amongst `.bash_profile`, `.bash_login` and `.profile` to source `~/.nix-profile/etc/profile.d/nix.sh`. You can set the -NIX\_INSTALLER\_NO\_MODIFY\_PROFILE environment variable before -executing the install script to disable this behaviour. +`NIX_INSTALLER_NO_MODIFY_PROFILE` environment variable before executing +the install script to disable this behaviour. You can uninstall Nix simply by running: diff --git a/doc/manual/src/installation/multi-user.md b/doc/manual/src/installation/multi-user.md index 17286fdc5..6493e717b 100644 --- a/doc/manual/src/installation/multi-user.md +++ b/doc/manual/src/installation/multi-user.md @@ -43,7 +43,7 @@ The [Nix daemon](#sec-nix-daemon) should be started as follows (as 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 +[`NIX_REMOTE` environment variable](#envar-remote) 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 f5c550fd7..04dad3339 100644 --- a/doc/manual/src/package-management/basic-package-mgmt.md +++ b/doc/manual/src/package-management/basic-package-mgmt.md @@ -8,10 +8,10 @@ In Nix, different users can have different “views” on the set of installed applications. That is, there might be lots of applications present on the system (possibly in many different versions), but users can have a specific selection of those active — where “active” just -means that it appears in a directory in the user’s PATH. Such a view on -the set of installed applications is called a *user environment*, which -is just a directory tree consisting of symlinks to the files of the -active applications. +means that it appears in a directory in the user’s `PATH`. Such a view +on the set of installed applications is called a *user environment*, +which is just a directory tree consisting of symlinks to the files of +the active applications. Components are installed from a set of *Nix expressions* that tell Nix how to build those packages, including, if necessary, their diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md index c46adf538..984afca55 100644 --- a/doc/manual/src/package-management/profiles.md +++ b/doc/manual/src/package-management/profiles.md @@ -24,9 +24,9 @@ Of course, you wouldn’t want to type $ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn every time you want to run Subversion. Of course we could set up the -PATH environment variable to include the `bin` directory of every +`PATH` environment variable to include the `bin` directory of every package we want to use, but this is not very convenient since changing -PATH doesn’t take effect for already existing processes. The solution +`PATH` doesn’t take effect for already existing processes. The solution Nix uses is to create directory trees of symlinks to *activated* packages. These are called *user environments* and they are packages themselves (though automatically generated by `nix-env`), so they too @@ -89,9 +89,9 @@ also see all available generations: $ nix-env --list-generations You generally wouldn’t have `/nix/var/nix/profiles/some-profile/bin` in -your PATH. Rather, there is a symlink `~/.nix-profile` that points to +your `PATH`. Rather, there is a symlink `~/.nix-profile` that points to your current profile. This means that you should put -`~/.nix-profile/bin` in your PATH (and indeed, that’s what the +`~/.nix-profile/bin` in your `PATH` (and indeed, that’s what the initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it easier to switch to a different profile. You can do that using the command `nix-env --switch-profile`: diff --git a/doc/manual/src/release-notes/rl-0.10.md b/doc/manual/src/release-notes/rl-0.10.md index bf0e59fad..07b19ff05 100644 --- a/doc/manual/src/release-notes/rl-0.10.md +++ b/doc/manual/src/release-notes/rl-0.10.md @@ -124,8 +124,8 @@ URL` allows a package to be installed directly from the given URL. - Nix now works behind an HTTP proxy server; just set the standard - environment variables http\_proxy, https\_proxy, ftp\_proxy or - all\_proxy appropriately. Functions such as `fetchurl` in Nixpkgs + environment variables `http_proxy`, `https_proxy`, `ftp_proxy` or + `all_proxy` appropriately. Functions such as `fetchurl` in Nixpkgs also respect these variables. - `nix-build -o diff --git a/doc/manual/src/release-notes/rl-0.12.md b/doc/manual/src/release-notes/rl-0.12.md index 0dc727b69..aaecfbb70 100644 --- a/doc/manual/src/release-notes/rl-0.12.md +++ b/doc/manual/src/release-notes/rl-0.12.md @@ -33,7 +33,7 @@ (remote) Nix stores mounted somewhere in the filesystem. For instance, you can speed up an installation by mounting some remote Nix store that already has the packages in question via NFS or - `sshfs`. The environment variable NIX\_OTHER\_STORES specifies the + `sshfs`. The environment variable `NIX_OTHER_STORES` specifies the locations of the remote Nix directories, e.g. `/mnt/remote-fs/nix`. - New `nix-store` operations `--dump-db` and `--load-db` to dump and @@ -111,7 +111,7 @@ (integer multiplication), `builtins.div` (integer division). - `nix-prefetch-url` now supports `mirror://` URLs, provided that the - environment variable NIXPKGS\_ALL points at a Nixpkgs tree. + environment variable `NIXPKGS_ALL` points at a Nixpkgs tree. - Removed the commands `nix-pack-closure` and `nix-unpack-closure`. You can do almost the same thing but much more efficiently by doing diff --git a/doc/manual/src/release-notes/rl-0.16.md b/doc/manual/src/release-notes/rl-0.16.md index 121bbde28..79074fcdc 100644 --- a/doc/manual/src/release-notes/rl-0.16.md +++ b/doc/manual/src/release-notes/rl-0.16.md @@ -14,7 +14,7 @@ This release has the following improvements: performed in parallel was not configurable. Nix now has an option `--cores N` as well as a configuration setting `build-cores = - N` that causes the environment variable NIX\_BUILD\_CORES to be set + N` that causes the environment variable `NIX_BUILD_CORES` to be set to N when the builder is invoked. The builder can use this at its discretion to perform a parallel build, e.g., by calling `make -j N`. In Nixpkgs, this can be enabled on a per-package basis by diff --git a/doc/manual/src/release-notes/rl-1.0.md b/doc/manual/src/release-notes/rl-1.0.md index 025f827d9..cdb257787 100644 --- a/doc/manual/src/release-notes/rl-1.0.md +++ b/doc/manual/src/release-notes/rl-1.0.md @@ -14,7 +14,7 @@ release. Here are the most significant: significant speedup. - Nix now has an search path for expressions. The search path is set - using the environment variable NIX\_PATH and the `-I` command line + using the environment variable `NIX_PATH` and the `-I` command line option. In Nix expressions, paths between angle brackets are used to specify files that must be looked up in the search path. For instance, the expression `<nixpkgs/default.nix>` looks for a file diff --git a/doc/manual/src/release-notes/rl-1.2.md b/doc/manual/src/release-notes/rl-1.2.md index e62b2dac9..25b830955 100644 --- a/doc/manual/src/release-notes/rl-1.2.md +++ b/doc/manual/src/release-notes/rl-1.2.md @@ -77,7 +77,7 @@ This release has the following improvements and changes: about twice as fast. - Basic Nix expression evaluation profiling: setting the environment - variable NIX\_COUNT\_CALLS to `1` will cause Nix to print how many + variable `NIX_COUNT_CALLS` to `1` will cause Nix to print how many times each primop or function was executed. - New primops: `concatLists`, `elem`, `elemAt` and `filter`. diff --git a/doc/manual/src/release-notes/rl-1.6.md b/doc/manual/src/release-notes/rl-1.6.md index a4583f4e6..9b83d9274 100644 --- a/doc/manual/src/release-notes/rl-1.6.md +++ b/doc/manual/src/release-notes/rl-1.6.md @@ -13,7 +13,7 @@ features: get an environment that more closely corresponds to the “real” Nix build. - - `nix-shell` now sets the shell prompt (PS1) to ensure that Nix + - `nix-shell` now sets the shell prompt (`PS1`) to ensure that Nix shells are distinguishable from your regular shells. - `nix-env` no longer requires a `*` argument to match all packages, diff --git a/doc/manual/src/release-notes/rl-1.8.md b/doc/manual/src/release-notes/rl-1.8.md index 10a82d52a..59af363e8 100644 --- a/doc/manual/src/release-notes/rl-1.8.md +++ b/doc/manual/src/release-notes/rl-1.8.md @@ -76,7 +76,7 @@ them anyway. - Various commands now automatically pipe their output into the pager - as specified by the PAGER environment variable. + as specified by the `PAGER` environment variable. - Several improvements to reduce memory consumption in the evaluator. diff --git a/doc/manual/src/release-notes/rl-1.9.md b/doc/manual/src/release-notes/rl-1.9.md index 01b067aab..92c6af90b 100644 --- a/doc/manual/src/release-notes/rl-1.9.md +++ b/doc/manual/src/release-notes/rl-1.9.md @@ -39,8 +39,8 @@ features: This builds GNU Hello from the latest revision of the Nixpkgs master branch. - - In the Nix search path (as specified via NIX\_PATH or `-I`). For - example, to start a shell containing the Pan package from a + - In the Nix search path (as specified via `NIX_PATH` or `-I`). + For example, to start a shell containing the Pan package from a specific version of Nixpkgs: $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz @@ -124,8 +124,8 @@ features: - `nix-env` now only creates a new “generation” symlink in `/nix/var/nix/profiles` if something actually changed. - - The environment variable NIX\_PAGER can now be set to override - PAGER. You can set it to `cat` to disable paging for Nix commands + - The environment variable `NIX_PAGER` can now be set to override + `PAGER`. You can set it to `cat` to disable paging for Nix commands only. - Failing `<...>` lookups now show position information. diff --git a/doc/manual/src/release-notes/rl-2.0.md b/doc/manual/src/release-notes/rl-2.0.md index 0ce985b2f..170275f89 100644 --- a/doc/manual/src/release-notes/rl-2.0.md +++ b/doc/manual/src/release-notes/rl-2.0.md @@ -18,7 +18,7 @@ The following incompatible changes have been made: - `bspatch` - The “copy from other stores” substituter mechanism - (`copy-from-other-stores` and the NIX\_OTHER\_STORES environment + (`copy-from-other-stores` and the `NIX_OTHER_STORES` environment variable) has been removed. It was primarily used by the NixOS installer to copy available paths from the installation medium. The replacement is to use a chroot store as a substituter (e.g. @@ -233,7 +233,7 @@ This release has the following new features: store, the latter via the Nix daemon. You can use `auto` or the empty string to auto-select a local or daemon store depending on whether you have write permission to the Nix store. It is no - longer necessary to set the NIX\_REMOTE environment variable to + longer necessary to set the `NIX_REMOTE` environment variable to use the Nix daemon. As noted above, `LocalStore` now supports chroot builds, @@ -296,7 +296,7 @@ This release has the following new features: [now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b) use `/build` instead of `/tmp` as the temporary build directory. This fixes potential security problems when a build accidentally - stores its TMPDIR in some security-sensitive place, such as an + stores its `TMPDIR` in some security-sensitive place, such as an RPATH. - *Pure evaluation mode*. With the `--pure-eval` flag, Nix enables a @@ -334,8 +334,8 @@ This release has the following new features: using the Nix daemon, you can now just specify a remote build machine on the command line, e.g. `--option builders 'ssh://my-mac x86_64-darwin'`. The environment variable - NIX\_BUILD\_HOOK has been removed and is no longer needed. The - environment variable NIX\_REMOTE\_SYSTEMS is still supported for + `NIX_BUILD_HOOK` has been removed and is no longer needed. The + environment variable `NIX_REMOTE_SYSTEMS` is still supported for compatibility, but it is also possible to specify builders in `nix.conf` by setting the option `builders = @path`. @@ -353,7 +353,7 @@ This release has the following new features: Nixpkgs provides `lib.inNixShell` to check this variable during evaluation. - - NIX\_PATH is now lazy, so URIs in the path are only downloaded if + - `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 @@ -406,7 +406,7 @@ This release has the following new features: non-standard base-32. - `nix-shell` now uses `bashInteractive` from Nixpkgs, rather than the - `bash` command that happens to be in the caller’s PATH. This is + `bash` command that happens to be in the caller’s `PATH`. This is especially important on macOS where the `bash` provided by the system is seriously outdated and cannot execute `stdenv`’s setup script. @@ -433,7 +433,7 @@ The Nix language has the following new features: configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}"; - will cause the configureFlags environment variable to contain the + will cause the `configureFlags` environment variable to contain the actual store paths corresponding to the `out` and `dev` outputs. The following builtin functions are new or extended: @@ -481,23 +481,23 @@ The Nix build environment has the following changes: be passed to builders in a non-lossy way. If the special attribute `__structuredAttrs` is set to `true`, the other derivation attributes are serialised in JSON format and made available to the - builder via the file .attrs.json in the builder’s temporary + builder via the file `.attrs.json` in the builder’s temporary directory. This obviates the need for `passAsFile` since JSON files have no size restrictions, unlike process environments. [As a convenience to Bash builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699), - Nix writes a script named .attrs.sh to the builder’s directory that - initialises shell variables corresponding to all attributes that are - representable in Bash. This includes non-nested (associative) - arrays. For example, the attribute `hardening.format = + Nix writes a script named `.attrs.sh` to the builder’s directory + that initialises shell variables corresponding to all attributes + that are representable in Bash. This includes non-nested + (associative) arrays. For example, the attribute `hardening.format = true` ends up as the Bash associative array element `${hardening[format]}`. - Builders can [now](https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3) communicate what build phase they are in by writing messages to the - file descriptor specified in NIX\_LOG\_FD. The current phase is + file descriptor specified in `NIX_LOG_FD`. The current phase is shown by the `nix` progress indicator. - In Linux sandbox builds, we diff --git a/doc/manual/src/release-notes/rl-2.2.md b/doc/manual/src/release-notes/rl-2.2.md index 3667a48dc..b67d65db7 100644 --- a/doc/manual/src/release-notes/rl-2.2.md +++ b/doc/manual/src/release-notes/rl-2.2.md @@ -69,7 +69,7 @@ This is primarily a bug fix release. It also has the following changes: - Integers are now 64 bits on all platforms. - The evaluator now prints profiling statistics (enabled via the - NIX\_SHOW\_STATS and NIX\_COUNT\_CALLS environment variables) in + `NIX_SHOW_STATS` and `NIX_COUNT_CALLS` environment variables) in JSON format. - The option `--xml` in `nix-store diff --git a/doc/manual/src/release-notes/rl-2.3.md b/doc/manual/src/release-notes/rl-2.3.md index a4bb6ebb0..d1f4e3734 100644 --- a/doc/manual/src/release-notes/rl-2.3.md +++ b/doc/manual/src/release-notes/rl-2.3.md @@ -25,7 +25,7 @@ It also has the following changes: line in the progress bar. To distinguish between concurrent builds, log lines are prefixed by the name of the package. - - Builds are now executed in a pseudo-terminal, and the TERM + - Builds are now executed in a pseudo-terminal, and the `TERM` environment variable is set to `xterm-256color`. This allows many programs (e.g. `gcc`, `clang`, `cmake`) to print colorized log output. |