Reconvert

This commit is contained in:
Eelco Dolstra 2020-07-23 10:44:54 +02:00
parent c20c082383
commit f390303566
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
29 changed files with 433 additions and 95 deletions

View file

@ -45,6 +45,8 @@
- [Verifying Build Reproducibility](advanced-topics/diff-hook.md) - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
- [Using the `post-build-hook`](advanced-topics/post-build-hook.md) - [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
- [Command Reference](command-ref/command-ref.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) - [Utilities](command-ref/utilities.md)
- [nix-copy-closure](command-ref/nix-copy-closure.md) - [nix-copy-closure](command-ref/nix-copy-closure.md)
- [Glossary](glossary.md) - [Glossary](glossary.md)

View file

@ -16,18 +16,18 @@ configuration trade-offs.
-j`. -j`.
The [???](#conf-cores) setting determines the value of The [???](#conf-cores) setting determines the value of
NIX\_BUILD\_CORES. NIX\_BUILD\_CORES is equal to [???](#conf-cores), `NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to [???](#conf-cores),
unless [???](#conf-cores) equals `0`, in which case NIX\_BUILD\_CORES unless [???](#conf-cores) equals `0`, in which case `NIX_BUILD_CORES`
will be the total number of cores in the system. will be the total number of cores in the system.
The maximum number of consumed cores is a simple multiplication, 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 The balance on how to set these two independent variables depends upon
each builder's workload and hardware. Here are a few example scenarios each builder's workload and hardware. Here are a few example scenarios
on a machine with 24 cores: 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 cant use 24 cores. | | 1 | 24 | 24 | 24 | One derivation will be built at a time, each one can use 24 cores. Undersold if a job cant use 24 cores. |
| 4 | 6 | 6 | 24 | Four derivations will be built at once, each given access to six 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 Balancing 24 Build Cores
It is up to the derivations' build script to respect host's requested 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. environment variable.

View file

@ -27,7 +27,7 @@ If you get the error
bash: nix-store: command not found bash: nix-store: command not found
error: cannot connect to 'mac' 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. contains Nix.
> **Warning** > **Warning**

View file

@ -1,2 +1,4 @@
# Command Reference
This section lists commands and options that you can use when you This section lists commands and options that you can use when you
work with Nix. work with Nix.

View file

@ -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 youre not going to do that, you
can set `NIX_IGNORE_SYMLINK_STORE` to `1`.
Note that if youre symlinking the Nix store so that you can put it
on another file system than the root file system, on Linux youre
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.

View file

@ -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`.

View file

@ -87,7 +87,7 @@ Derivations can declare some infrequently used optional attributes.
impureEnvVars = [ "http_proxy" "https_proxy" ... ]; impureEnvVars = [ "http_proxy" "https_proxy" ... ];
to make it use the proxy server configuration specified by the user 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 This attribute is only allowed in [fixed-output
derivations](#fixed-output-drvs), where impurities such as these are 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 contain the absolute path to a temporary file containing `a very
long long
string`. That is, for any attribute x listed in `passAsFile`, Nix string`. That is, for any attribute x listed in `passAsFile`, Nix
will pass an environment variable xPath holding the path of the file will pass an environment variable `xPath` holding the path of the
containing the value of attribute x. This is useful when you need to file containing the value of attribute x. This is useful when you
pass large strings to a builder, since most operating systems impose need to pass large strings to a builder, since most operating
a limit on the size of the environment (typically, a few hundred systems impose a limit on the size of the environment (typically, a
kilobyte). few hundred kilobyte).
- `preferLocalBuild` - `preferLocalBuild`
If this attribute is set to `true` and [distributed building is If this attribute is set to `true` and [distributed building is

View file

@ -19,29 +19,29 @@ what a builder does. It performs the following steps:
- When Nix runs a builder, it initially completely clears the - When Nix runs a builder, it initially completely clears the
environment (except for the attributes declared in the derivation). 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 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`. accidentally use `/usr/bin/gcc`.
So the first step is to set up the environment. This is done by So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The 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 environment being used. (It wasn't specified explicitly as an
attribute in [???](#ex-hello-nix), but `mkDerivation` adds it attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
automatically.) automatically.)
- Since Hello needs Perl, we have to make sure that Perl is in the - 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 `PATH`. The `perl` environment variable points to the location of
Perl package (since it was passed in as an attribute to the the Perl package (since it was passed in as an attribute to the
derivation), so `$perl/bin` is the directory containing the Perl derivation), so `$perl/bin` is the directory containing the Perl
interpreter. interpreter.
- Now we have to unpack the sources. The `src` attribute was bound to - 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 result of fetching the Hello source tarball from the network, so
the src environment variable points to the location in the Nix store the `src` environment variable points to the location in the Nix
to which the tarball was downloaded. After unpacking, we `cd` to the store to which the tarball was downloaded. After unpacking, we `cd`
resulting source directory. to the resulting source directory.
The whole build is performed in a temporary directory created in The whole build is performed in a temporary directory created in
`/tmp`, by the way. This directory is removed after the builder `/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 separate location in the Nix store, for instance
`/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
computes this path by cryptographically hashing all attributes of 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 environment variable. So here we give `configure` the parameter
`--prefix=$out` to cause Hello to be installed in the expected `--prefix=$out` to cause Hello to be installed in the expected
location. location.
- Finally we build Hello (`make`) and install it into the 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 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 of various commands called in the builder: this is because the shell

View file

@ -19,29 +19,29 @@ what a builder does. It performs the following steps:
- When Nix runs a builder, it initially completely clears the - When Nix runs a builder, it initially completely clears the
environment (except for the attributes declared in the derivation). 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 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`. accidentally use `/usr/bin/gcc`.
So the first step is to set up the environment. This is done by So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The 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 environment being used. (It wasn't specified explicitly as an
attribute in [???](#ex-hello-nix), but `mkDerivation` adds it attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
automatically.) automatically.)
- Since Hello needs Perl, we have to make sure that Perl is in the - 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 `PATH`. The `perl` environment variable points to the location of
Perl package (since it was passed in as an attribute to the the Perl package (since it was passed in as an attribute to the
derivation), so `$perl/bin` is the directory containing the Perl derivation), so `$perl/bin` is the directory containing the Perl
interpreter. interpreter.
- Now we have to unpack the sources. The `src` attribute was bound to - 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 result of fetching the Hello source tarball from the network, so
the src environment variable points to the location in the Nix store the `src` environment variable points to the location in the Nix
to which the tarball was downloaded. After unpacking, we `cd` to the store to which the tarball was downloaded. After unpacking, we `cd`
resulting source directory. to the resulting source directory.
The whole build is performed in a temporary directory created in The whole build is performed in a temporary directory created in
`/tmp`, by the way. This directory is removed after the builder `/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 separate location in the Nix store, for instance
`/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
computes this path by cryptographically hashing all attributes of 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 environment variable. So here we give `configure` the parameter
`--prefix=$out` to cause Hello to be installed in the expected `--prefix=$out` to cause Hello to be installed in the expected
location. location.
- Finally we build Hello (`make`) and install it into the 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 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 of various commands called in the builder: this is because the shell

View file

@ -83,32 +83,32 @@ as a command-line argument. See the Nixpkgs manual for details.
The builder is executed as follows: The builder is executed as follows:
- A temporary directory is created under the directory specified by - A temporary directory is created under the directory specified by
TMPDIR (default `/tmp`) where the build will take place. The current `TMPDIR` (default `/tmp`) where the build will take place. The
directory is changed to this directory. current directory is changed to this directory.
- The environment is cleared and set to the derivation attributes, as - The environment is cleared and set to the derivation attributes, as
specified above. specified above.
- In addition, the following variables are set: - 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. 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 temporary directory. This is to prevent the builder from
accidentally writing temporary files anywhere else. Doing so accidentally writing temporary files anywhere else. Doing so
might cause interference by other processes. 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. 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 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 set, it is used as the location of the home directory, even if
it points to a non-existent path. 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`). directory (typically, `/nix/store`).
- For each output declared in `outputs`, the corresponding - For each output declared in `outputs`, the corresponding

View file

@ -22,9 +22,9 @@ build facilities in shown in [example\_title](#ex-hello-builder2).
genericBuild genericBuild
- The buildInputs variable tells `setup` to use the indicated packages - The `buildInputs` variable tells `setup` to use the indicated
as “inputs”. This means that if a package provides a `bin` 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 `PATH`; if it has a `include`
subdirectory, it's added to GCC's header search path; and so subdirectory, it's added to GCC's header search path; and so
on.\[1\] 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 It can be customised in many ways; see the Nixpkgs manual for
details. 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: 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 1. How does it work? `setup` tries to source the file
`pkg/nix-support/setup-hook` of all dependencies. These “setup `pkg/nix-support/setup-hook` of all dependencies. These “setup
hooks” can then set up whatever environment variables they want; hooks” can then set up whatever environment variables they want;
for instance, the setup hook for Perl sets the PERL5LIB environment for instance, the setup hook for Perl sets the `PERL5LIB`
variable to contain the `lib/site_perl` directories of all inputs. environment variable to contain the `lib/site_perl` directories of
all inputs.

View file

@ -120,8 +120,8 @@ Nix has the following basic data types:
Paths can also be specified between angle brackets, e.g. Paths can also be specified between angle brackets, e.g.
`<nixpkgs>`. This means that the directories listed in the `<nixpkgs>`. This means that the directories listed in the
environment variable NIX\_PATH will be searched for the given file environment variable NIX\_PATH\</literal\> will be searched for the
or directory name. given file or directory name.
- *Booleans* with values `true` and `false`. - *Booleans* with values `true` and `false`.

View file

@ -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 Nix has transactional semantics. Once a build finishes successfully, Nix
makes a note of this in its database: it registers that the path denoted 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 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 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 or the builder are killed, or because the machine crashes, then the

View file

@ -1,7 +1,7 @@
# Environment Variables # Environment Variables
To use Nix, some environment variables should be set. In particular, 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 `~/.nix-profile/bin`. The first directory contains the Nix tools
themselves, while `~/.nix-profile` is a symbolic link to the current themselves, while `~/.nix-profile` is a symbolic link to the current
*user environment* (an automatically generated package consisting of *user environment* (an automatically generated package consisting of
@ -12,13 +12,13 @@ this:
source prefix/etc/profile.d/nix.sh 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 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 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. and use its own certificate bundle.
Set the environment variable and install Nix 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 > You must not add the export and then do the install, as the Nix
> installer will detect the presense of Nix configuration, and abort. > 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 On macOS you must specify the environment variable for the Nix daemon
service, then restart it: service, then restart it:

View file

@ -34,8 +34,8 @@ manually create `/nix` first as root, e.g.:
The install script will modify the first writable file from amongst The install script will modify the first writable file from amongst
`.bash_profile`, `.bash_login` and `.profile` to source `.bash_profile`, `.bash_login` and `.profile` to source
`~/.nix-profile/etc/profile.d/nix.sh`. You can set the `~/.nix-profile/etc/profile.d/nix.sh`. You can set the
NIX\_INSTALLER\_NO\_MODIFY\_PROFILE environment variable before `NIX_INSTALLER_NO_MODIFY_PROFILE` environment variable before executing
executing the install script to disable this behaviour. the install script to disable this behaviour.
You can uninstall Nix simply by running: You can uninstall Nix simply by running:

View file

@ -43,7 +43,7 @@ The [Nix daemon](#sec-nix-daemon) should be started as follows (as
Youll want to put that line somewhere in your systems boot scripts. Youll want to put that line somewhere in your systems boot scripts.
To let unprivileged users use the daemon, they should set the 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 should put a line like
export NIX_REMOTE=daemon export NIX_REMOTE=daemon

View file

@ -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 installed applications. That is, there might be lots of applications
present on the system (possibly in many different versions), but users present on the system (possibly in many different versions), but users
can have a specific selection of those active — where “active” just can have a specific selection of those active — where “active” just
means that it appears in a directory in the users PATH. Such a view on means that it appears in a directory in the users `PATH`. Such a view
the set of installed applications is called a *user environment*, which on the set of installed applications is called a *user environment*,
is just a directory tree consisting of symlinks to the files of the which is just a directory tree consisting of symlinks to the files of
active applications. the active applications.
Components are installed from a set of *Nix expressions* that tell Nix Components are installed from a set of *Nix expressions* that tell Nix
how to build those packages, including, if necessary, their how to build those packages, including, if necessary, their

View file

@ -24,9 +24,9 @@ Of course, you wouldnt want to type
$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn $ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn
every time you want to run Subversion. Of course we could set up the 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 package we want to use, but this is not very convenient since changing
PATH doesnt take effect for already existing processes. The solution `PATH` doesnt take effect for already existing processes. The solution
Nix uses is to create directory trees of symlinks to *activated* Nix uses is to create directory trees of symlinks to *activated*
packages. These are called *user environments* and they are packages packages. These are called *user environments* and they are packages
themselves (though automatically generated by `nix-env`), so they too themselves (though automatically generated by `nix-env`), so they too
@ -89,9 +89,9 @@ also see all available generations:
$ nix-env --list-generations $ nix-env --list-generations
You generally wouldnt have `/nix/var/nix/profiles/some-profile/bin` in You generally wouldnt 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 your current profile. This means that you should put
`~/.nix-profile/bin` in your PATH (and indeed, thats what the `~/.nix-profile/bin` in your `PATH` (and indeed, thats what the
initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it 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 easier to switch to a different profile. You can do that using the
command `nix-env --switch-profile`: command `nix-env --switch-profile`:

View file

@ -124,8 +124,8 @@
URL` allows a package to be installed directly from the given URL. URL` allows a package to be installed directly from the given URL.
- Nix now works behind an HTTP proxy server; just set the standard - Nix now works behind an HTTP proxy server; just set the standard
environment variables http\_proxy, https\_proxy, ftp\_proxy or environment variables `http_proxy`, `https_proxy`, `ftp_proxy` or
all\_proxy appropriately. Functions such as `fetchurl` in Nixpkgs `all_proxy` appropriately. Functions such as `fetchurl` in Nixpkgs
also respect these variables. also respect these variables.
- `nix-build -o - `nix-build -o

View file

@ -33,7 +33,7 @@
(remote) Nix stores mounted somewhere in the filesystem. For (remote) Nix stores mounted somewhere in the filesystem. For
instance, you can speed up an installation by mounting some remote instance, you can speed up an installation by mounting some remote
Nix store that already has the packages in question via NFS or 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`. locations of the remote Nix directories, e.g. `/mnt/remote-fs/nix`.
- New `nix-store` operations `--dump-db` and `--load-db` to dump and - New `nix-store` operations `--dump-db` and `--load-db` to dump and
@ -111,7 +111,7 @@
(integer multiplication), `builtins.div` (integer division). (integer multiplication), `builtins.div` (integer division).
- `nix-prefetch-url` now supports `mirror://` URLs, provided that the - `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`. - Removed the commands `nix-pack-closure` and `nix-unpack-closure`.
You can do almost the same thing but much more efficiently by doing You can do almost the same thing but much more efficiently by doing

View file

@ -14,7 +14,7 @@ This release has the following improvements:
performed in parallel was not configurable. Nix now has an option performed in parallel was not configurable. Nix now has an option
`--cores `--cores
N` as well as a configuration setting `build-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 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 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 N`. In Nixpkgs, this can be enabled on a per-package basis by

View file

@ -14,7 +14,7 @@ release. Here are the most significant:
significant speedup. significant speedup.
- Nix now has an search path for expressions. The search path is set - 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 option. In Nix expressions, paths between angle brackets are used to
specify files that must be looked up in the search path. For specify files that must be looked up in the search path. For
instance, the expression `<nixpkgs/default.nix>` looks for a file instance, the expression `<nixpkgs/default.nix>` looks for a file

View file

@ -77,7 +77,7 @@ This release has the following improvements and changes:
about twice as fast. about twice as fast.
- Basic Nix expression evaluation profiling: setting the environment - 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. times each primop or function was executed.
- New primops: `concatLists`, `elem`, `elemAt` and `filter`. - New primops: `concatLists`, `elem`, `elemAt` and `filter`.

View file

@ -13,7 +13,7 @@ features:
get an environment that more closely corresponds to the “real” Nix get an environment that more closely corresponds to the “real” Nix
build. 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. shells are distinguishable from your regular shells.
- `nix-env` no longer requires a `*` argument to match all packages, - `nix-env` no longer requires a `*` argument to match all packages,

View file

@ -76,7 +76,7 @@
them anyway. them anyway.
- Various commands now automatically pipe their output into the pager - 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. - Several improvements to reduce memory consumption in the evaluator.

View file

@ -39,8 +39,8 @@ features:
This builds GNU Hello from the latest revision of the Nixpkgs This builds GNU Hello from the latest revision of the Nixpkgs
master branch. master branch.
- In the Nix search path (as specified via NIX\_PATH or `-I`). For - In the Nix search path (as specified via `NIX_PATH` or `-I`).
example, to start a shell containing the Pan package from a For example, to start a shell containing the Pan package from a
specific version of Nixpkgs: specific version of Nixpkgs:
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz $ 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-env` now only creates a new “generation” symlink in
`/nix/var/nix/profiles` if something actually changed. `/nix/var/nix/profiles` if something actually changed.
- The environment variable NIX\_PAGER can now be set to override - The environment variable `NIX_PAGER` can now be set to override
PAGER. You can set it to `cat` to disable paging for Nix commands `PAGER`. You can set it to `cat` to disable paging for Nix commands
only. only.
- Failing `<...>` lookups now show position information. - Failing `<...>` lookups now show position information.

View file

@ -18,7 +18,7 @@ The following incompatible changes have been made:
- `bspatch` - `bspatch`
- The “copy from other stores” substituter mechanism - 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 variable) has been removed. It was primarily used by the NixOS
installer to copy available paths from the installation medium. The installer to copy available paths from the installation medium. The
replacement is to use a chroot store as a substituter (e.g. 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 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 empty string to auto-select a local or daemon store depending on
whether you have write permission to the Nix store. It is no 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. use the Nix daemon.
As noted above, `LocalStore` now supports chroot builds, 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) [now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b)
use `/build` instead of `/tmp` as the temporary build directory. use `/build` instead of `/tmp` as the temporary build directory.
This fixes potential security problems when a build accidentally 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. RPATH.
- *Pure evaluation mode*. With the `--pure-eval` flag, Nix enables a - *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 using the Nix daemon, you can now just specify a remote build
machine on the command line, e.g. `--option builders machine on the command line, e.g. `--option builders
'ssh://my-mac x86_64-darwin'`. The environment variable 'ssh://my-mac x86_64-darwin'`. The environment variable
NIX\_BUILD\_HOOK has been removed and is no longer needed. The `NIX_BUILD_HOOK` has been removed and is no longer needed. The
environment variable NIX\_REMOTE\_SYSTEMS is still supported for environment variable `NIX_REMOTE_SYSTEMS` is still supported for
compatibility, but it is also possible to specify builders in compatibility, but it is also possible to specify builders in
`nix.conf` by setting the option `builders = `nix.conf` by setting the option `builders =
@path`. @path`.
@ -353,7 +353,7 @@ This release has the following new features:
Nixpkgs provides `lib.inNixShell` to check this variable during Nixpkgs provides `lib.inNixShell` to check this variable during
evaluation. 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. 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
@ -406,7 +406,7 @@ This release has the following new features:
non-standard base-32. non-standard base-32.
- `nix-shell` now uses `bashInteractive` from Nixpkgs, rather than the - `nix-shell` now uses `bashInteractive` from Nixpkgs, rather than the
`bash` command that happens to be in the callers PATH. This is `bash` command that happens to be in the callers `PATH`. This is
especially important on macOS where the `bash` provided by the especially important on macOS where the `bash` provided by the
system is seriously outdated and cannot execute `stdenv`s setup system is seriously outdated and cannot execute `stdenv`s setup
script. script.
@ -433,7 +433,7 @@ The Nix language has the following new features:
configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}"; 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. actual store paths corresponding to the `out` and `dev` outputs.
The following builtin functions are new or extended: 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 be passed to builders in a non-lossy way. If the special attribute
`__structuredAttrs` is set to `true`, the other derivation `__structuredAttrs` is set to `true`, the other derivation
attributes are serialised in JSON format and made available to the attributes are serialised in JSON format and made available to the
builder via the file .attrs.json in the builders temporary builder via the file `.attrs.json` in the builders temporary
directory. This obviates the need for `passAsFile` since JSON files directory. This obviates the need for `passAsFile` since JSON files
have no size restrictions, unlike process environments. have no size restrictions, unlike process environments.
[As a convenience to Bash [As a convenience to Bash
builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699), builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699),
Nix writes a script named .attrs.sh to the builders directory that Nix writes a script named `.attrs.sh` to the builders directory
initialises shell variables corresponding to all attributes that are that initialises shell variables corresponding to all attributes
representable in Bash. This includes non-nested (associative) that are representable in Bash. This includes non-nested
arrays. For example, the attribute `hardening.format = (associative) arrays. For example, the attribute `hardening.format =
true` ends up as the Bash associative array element true` ends up as the Bash associative array element
`${hardening[format]}`. `${hardening[format]}`.
- Builders can - Builders can
[now](https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3) [now](https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3)
communicate what build phase they are in by writing messages to the 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. shown by the `nix` progress indicator.
- In Linux sandbox builds, we - In Linux sandbox builds, we

View file

@ -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. - Integers are now 64 bits on all platforms.
- The evaluator now prints profiling statistics (enabled via the - 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. JSON format.
- The option `--xml` in `nix-store - The option `--xml` in `nix-store

View file

@ -25,7 +25,7 @@ It also has the following changes:
line in the progress bar. To distinguish between concurrent builds, line in the progress bar. To distinguish between concurrent builds,
log lines are prefixed by the name of the package. 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 environment variable is set to `xterm-256color`. This allows many
programs (e.g. `gcc`, `clang`, `cmake`) to print colorized log programs (e.g. `gcc`, `clang`, `cmake`) to print colorized log
output. output.