picnoir/Nix
1
0
Fork 0
Code Issues Pull requests 1 Releases Wiki Activity

Fix internal links

Browse source
This commit is contained in:
Eelco Dolstra 2020-07-24 15:46:16 +02:00
parent da3d776cb9
commit 05a282295f
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
21 changed files with 245 additions and 262 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/manual/src/advanced-topics/distributed-builds.md
View file

@ -134,8 +134,7 @@ causes the list of machines in `/etc/nix/machines` to be included. (This
is the default.)
If you want the builders to use caches, you likely want to set the
option [`builders-use-substitutes`](#conf-builders-use-substitutes) in
your local `nix.conf`.
option `builders-use-substitutes` in your local `nix.conf`.
To build only on remote builders and disable building on the local
machine, you can use the option `--max-jobs 0`.

3
doc/manual/src/advanced-topics/post-build-hook.md
View file

@ -108,5 +108,4 @@ We now have a Nix installation configured to automatically sign and
upload every local build to a remote binary cache.
Before deploying this to production, be sure to consider the
implementation caveats in [Implementation
Caveats](#chap-post-build-hook-caveats).
[implementation caveats](#implementation-caveats).

99
doc/manual/src/command-ref/conf-file.md
View file

@ -141,10 +141,10 @@ The following settings are currently available:
the builder should use all available CPU cores in the system.
- `diff-hook`
Absolute path to an executable capable of diffing build results. The
hook executes if [varlistentry\_title](#conf-run-diff-hook) is true,
and the output of a build is known to not be the same. This program
is not executed to determine if two results are the same.
Absolute path to an executable capable of diffing build
results. The hook is executed if `run-diff-hook` is true, and the
output of a build is known to not be the same. This program is not
executed to determine if two results are the same.
The diff hook is executed by the same user and group who ran the
build. However, the diff hook does not have write access to the
@ -169,7 +169,7 @@ The following settings are currently available:
configuration file, and cannot be passed at the command line.
- `enforce-determinism`
See [varlistentry\_title](#conf-repeat).
See `repeat`.
- `extra-sandbox-paths`
A list of additional paths appended to `sandbox-paths`. Useful if
@ -343,7 +343,7 @@ The following settings are currently available:
password my-password
For the exact syntax, see [the `curl`
documentation.](https://ec.haxx.se/usingcurl-netrc.html)
documentation](https://ec.haxx.se/usingcurl-netrc.html).
> **Note**
>
@ -434,9 +434,9 @@ The following settings are currently available:
deterministic. The default value is 0. If the value is non-zero,
every build is repeated the specified number of times. If the
contents of any of the runs differs from the previous ones and
[varlistentry\_title](#conf-enforce-determinism) is true, the build
is rejected and the resulting store paths are not registered as
“valid” in Nix’s database.
`enforce-determinism` is true, the build is rejected and the
resulting store paths are not registered as “valid” in Nix’s
database.
- `require-sigs`
If set to `true` (the default), any non-content-addressed path added
@ -461,20 +461,21 @@ The following settings are currently available:
- `sandbox`
If set to `true`, builds will be performed in a *sandboxed
environment*, i.e., they’re isolated from the normal file system
hierarchy and will only see their dependencies in the Nix store, the
temporary build directory, private versions of `/proc`, `/dev`,
`/dev/shm` and `/dev/pts` (on Linux), and the paths configured with
the [`sandbox-paths` option](#conf-sandbox-paths). This is useful to
hierarchy and will only see their dependencies in the Nix store,
the temporary build directory, private versions of `/proc`,
`/dev`, `/dev/shm` and `/dev/pts` (on Linux), and the paths
configured with the `sandbox-paths` option. This is useful to
prevent undeclared dependencies on files in directories such as
`/usr/bin`. In addition, on Linux, builds run in private PID, mount,
network, IPC and UTS namespaces to isolate them from other processes
in the system (except that fixed-output derivations do not run in
private network namespace to ensure they can access the network).
`/usr/bin`. In addition, on Linux, builds run in private PID,
mount, network, IPC and UTS namespaces to isolate them from other
processes in the system (except that fixed-output derivations do
not run in private network namespace to ensure they can access the
network).
Currently, sandboxing only work on Linux and macOS. The use of a
sandbox requires that Nix is run as root (so you should use the
[“build users” feature](#conf-build-users-group) to perform the
actual builds under different users than root).
“build users” feature to perform the actual builds under different
users than root).
If this option is set to `relaxed`, then fixed-output derivations
and derivations that have the `__noChroot` attribute set to `true`
@ -631,81 +632,61 @@ The following settings are currently available:
## Deprecated Settings
- `binary-caches`
*Deprecated:* `binary-caches` is now an alias to
[varlistentry\_title](#conf-substituters).
*Deprecated:* `binary-caches` is now an alias to `substituters`.
- `binary-cache-public-keys`
*Deprecated:* `binary-cache-public-keys` is now an alias to
[varlistentry\_title](#conf-trusted-public-keys).
*Deprecated:* `binary-cache-public-keys` is now an alias `trusted-public-keys`.
- `build-compress-log`
*Deprecated:* `build-compress-log` is now an alias to
[varlistentry\_title](#conf-compress-build-log).
*Deprecated:* `build-compress-log` is now an alias to `compress-build-log`.
- `build-cores`
*Deprecated:* `build-cores` is now an alias to
[varlistentry\_title](#conf-cores).
*Deprecated:* `build-cores` is now an alias to `cores`.
- `build-extra-chroot-dirs`
*Deprecated:* `build-extra-chroot-dirs` is now an alias to
[varlistentry\_title](#conf-extra-sandbox-paths).
*Deprecated:* `build-extra-chroot-dirs` is now an alias to `extra-sandbox-paths`.
- `build-extra-sandbox-paths`
*Deprecated:* `build-extra-sandbox-paths` is now an alias to
[varlistentry\_title](#conf-extra-sandbox-paths).
*Deprecated:* `build-extra-sandbox-paths` is now an alias to `extra-sandbox-paths`.
- `build-fallback`
*Deprecated:* `build-fallback` is now an alias to
[varlistentry\_title](#conf-fallback).
*Deprecated:* `build-fallback` is now an alias to `fallback`.
- `build-max-jobs`
*Deprecated:* `build-max-jobs` is now an alias to
[varlistentry\_title](#conf-max-jobs).
*Deprecated:* `build-max-jobs` is now an alias to `max-jobs`.
- `build-max-log-size`
*Deprecated:* `build-max-log-size` is now an alias to
[varlistentry\_title](#conf-max-build-log-size).
*Deprecated:* `build-max-log-size` is now an alias to `max-build-log-size`.
- `build-max-silent-time`
*Deprecated:* `build-max-silent-time` is now an alias to
[varlistentry\_title](#conf-max-silent-time).
*Deprecated:* `build-max-silent-time` is now an alias to `max-silent-time`.
- `build-repeat`
*Deprecated:* `build-repeat` is now an alias to
[varlistentry\_title](#conf-repeat).
*Deprecated:* `build-repeat` is now an alias to `repeat`.
- `build-timeout`
*Deprecated:* `build-timeout` is now an alias to
[varlistentry\_title](#conf-timeout).
*Deprecated:* `build-timeout` is now an alias to `timeout`.
- `build-use-chroot`
*Deprecated:* `build-use-chroot` is now an alias to
[varlistentry\_title](#conf-sandbox).
*Deprecated:* `build-use-chroot` is now an alias to `sandbox`.
- `build-use-sandbox`
*Deprecated:* `build-use-sandbox` is now an alias to
[varlistentry\_title](#conf-sandbox).
*Deprecated:* `build-use-sandbox` is now an alias to `sandbox`.
- `build-use-substitutes`
*Deprecated:* `build-use-substitutes` is now an alias to
[varlistentry\_title](#conf-substitute).
*Deprecated:* `build-use-substitutes` is now an alias to `substitute`.
- `gc-keep-derivations`
*Deprecated:* `gc-keep-derivations` is now an alias to
[varlistentry\_title](#conf-keep-derivations).
*Deprecated:* `gc-keep-derivations` is now an alias to `keep-derivations`.
- `gc-keep-outputs`
*Deprecated:* `gc-keep-outputs` is now an alias to
[varlistentry\_title](#conf-keep-outputs).
*Deprecated:* `gc-keep-outputs` is now an alias to `keep-outputs`.
- `env-keep-derivations`
*Deprecated:* `env-keep-derivations` is now an alias to
[varlistentry\_title](#conf-keep-env-derivations).
*Deprecated:* `env-keep-derivations` is now an alias to `keep-env-derivations`.
- `extra-binary-caches`
*Deprecated:* `extra-binary-caches` is now an alias to
[varlistentry\_title](#conf-extra-substituters).
*Deprecated:* `extra-binary-caches` is now an alias to `extra-substituters`.
- `trusted-binary-caches`
*Deprecated:* `trusted-binary-caches` is now an alias to
[varlistentry\_title](#conf-trusted-substituters).
*Deprecated:* `trusted-binary-caches` is now an alias to `trusted-substituters`.

7
doc/manual/src/command-ref/env-common.md
View file

@ -92,9 +92,10 @@ Most Nix commands interpret the following environment variables:
- `NIX_REMOTE`
This variable should be set to `daemon` if you want to use the Nix
daemon to execute Nix operations. This is necessary in [multi-user
Nix installations](#ssec-multi-user). If the Nix daemon's Unix
socket is at some non-standard path, this variable should be set to
`unix://path/to/socket`. Otherwise, it should be left unset.
Nix installations](../installation/multi-user.md). If the Nix
daemon's Unix socket is at some non-standard path, this variable
should be set to `unix://path/to/socket`. Otherwise, it should be
left unset.
- `NIX_SHOW_STATS`
If set to `1`, Nix will print some evaluation statistics, such as

5
doc/manual/src/command-ref/nix-build.md
View file

@ -32,9 +32,10 @@ to a temporary location. The tarball must include a single top-level
directory containing at least a file named `default.nix`.
`nix-build` is essentially a wrapper around
[`nix-instantiate`](#sec-nix-instantiate) (to translate a high-level Nix
[`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix
expression to a low-level store derivation) and [`nix-store
--realise`](#rsec-nix-store-realise) (to build the store derivation).
--realise`](nix-store.md#operation---realise) (to build the store
derivation).
> **Warning**
>

20
doc/manual/src/command-ref/nix-collect-garbage.md
View file

@ -11,16 +11,16 @@ Title: nix-collect-garbage
# Description
The command `nix-collect-garbage` is mostly an alias of [`nix-store
--gc`](#rsec-nix-store-gc), that is, it deletes all unreachable paths in
the Nix store to clean up your system. However, it provides two
additional options: `-d` (`--delete-old`), which deletes all old
generations of all profiles in `/nix/var/nix/profiles` by invoking
`nix-env --delete-generations old` on all profiles (of course, this
makes rollbacks to previous configurations impossible); and
`--delete-older-than` *period*, where period is a value such as `30d`,
which deletes all generations older than the specified number of days in
all profiles in `/nix/var/nix/profiles` (except for the generations that
were active at that point in time).
--gc`](nix-store.md#operation---gc), that is, it deletes all
unreachable paths in the Nix store to clean up your system. However,
it provides two additional options: `-d` (`--delete-old`), which
deletes all old generations of all profiles in `/nix/var/nix/profiles`
by invoking `nix-env --delete-generations old` on all profiles (of
course, this makes rollbacks to previous configurations impossible);
and `--delete-older-than` *period*, where period is a value such as
`30d`, which deletes all generations older than the specified number
of days in all profiles in `/nix/var/nix/profiles` (except for the
generations that were active at that point in time).
# Example

37
doc/manual/src/command-ref/nix-env.md
View file

@ -92,7 +92,7 @@ have an effect.
done if this flag had not been specified, without actually doing it.
`--dry-run` also prints out which paths will be
[substituted](#gloss-substitute) (i.e., downloaded) and which paths
[substituted](../glossary.md) (i.e., downloaded) and which paths
will be built from source (because no substitute is available).
- `--system-filter` *system*
@ -186,11 +186,11 @@ a number of possible ways:
gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
probably cause a user environment conflict\!).
- If [`--attr`](#opt-attr) (`-A`) is specified, the arguments are
*attribute paths* that select attributes from the top-level Nix
- If `--attr` (`-A`) is specified, the arguments are *attribute
paths* that select attributes from the top-level Nix
expression. This is faster than using derivation names and
unambiguous. To find out the attribute paths of available packages,
use `nix-env -qaP`.
unambiguous. To find out the attribute paths of available
packages, use `nix-env -qaP`.
- If `--from-profile` *path* is given, *args* is a set of names
denoting installed store paths in the profile *path*. This is an
@ -198,18 +198,19 @@ a number of possible ways:
another.
- If `--from-expression` is given, *args* are Nix
[functions](#ss-functions) that are called with the active Nix
expression as their single argument. The derivations returned by
those function calls are installed. This allows derivations to be
specified in an unambiguous way, which is necessary if there are
multiple derivations with the same name.
[functions](../expressions/language-constructs.md#functions)
that are called with the active Nix expression as their single
argument. The derivations returned by those function calls are
installed. This allows derivations to be specified in an
unambiguous way, which is necessary if there are multiple
derivations with the same name.
- If *args* are store derivations, then these are
[realised](#rsec-nix-store-realise), and the resulting output paths
[realised](nix-store.md#operation---realise), and the resulting output paths
are installed.
- If *args* are store paths that are not store derivations, then these
are [realised](#rsec-nix-store-realise) and installed.
are [realised](nix-store.md#operation---realise) and installed.
- By default all outputs are installed for each derivation. That can
be reduced by setting `meta.outputsToInstall`.
@ -319,9 +320,9 @@ left untouched; this is not an error. It is also not an error if an
element of *args* matches no installed derivations.
For a description of how *args* is mapped to a set of store paths, see
[`--install`](#rsec-nix-env-install). If *args* describes multiple store
paths with the same symbolic name, only the one with the highest version
is installed.
[`--install`](#operation---install). If *args* describes multiple
store paths with the same symbolic name, only the one with the highest
version is installed.
## Flags
@ -584,9 +585,9 @@ derivation is shown unless `--no-name` is specified.
- `--attr-path`; `-P`
Print the *attribute path* of the derivation, which can be used to
unambiguously select it using the [`--attr` option](#opt-attr)
available in commands that install derivations like `nix-env
--install`. This option only works together with `--available`
unambiguously select it using the `--attr` option available in
commands that install derivations like `nix-env --install`. This
option only works together with `--available`
- `--no-name`
Suppress printing of the `name` attribute of each derivation.

14
doc/manual/src/command-ref/nix-hash.md
View file

@ -21,13 +21,13 @@ is printed in hexadecimal. To generate the same hash as
`nix-prefetch-url` you have to specify multiple arguments, see below for
an example.
The hash is computed over a *serialisation* of each path: a dump of the
file system tree rooted at the path. This allows directories and
symlinks to be hashed as well as regular files. The dump is in the *NAR
format* produced by [`nix-store` `--dump`](#refsec-nix-store-dump).
Thus, `nix-hash
path` yields the same cryptographic hash as `nix-store --dump
path | md5sum`.
The hash is computed over a *serialisation* of each path: a dump of
the file system tree rooted at the path. This allows directories and
symlinks to be hashed as well as regular files. The dump is in the
*NAR format* produced by [`nix-store
--dump`](nix-store.md#operation---dump). Thus, `nix-hash path`
yields the same cryptographic hash as `nix-store --dump path |
md5sum`.
# Options

10
doc/manual/src/command-ref/nix-instantiate.md
View file

@ -21,11 +21,11 @@ Title: nix-instantiate
# Description
The command `nix-instantiate` generates [store
derivations](#gloss-derivation) from (high-level) Nix expressions. It
derivations](../glossary.md) from (high-level) Nix expressions. It
evaluates the Nix expressions in each of *files* (which defaults to
*./default.nix*). Each top-level expression should evaluate to a
derivation, a list of derivations, or a set of derivations. The paths of
the resulting store derivations are printed on standard output.
derivation, a list of derivations, or a set of derivations. The paths
of the resulting store derivations are printed on standard output.
If *files* is the character `-`, then a Nix expression will be read from
standard input.
@ -33,7 +33,7 @@ standard input.
# Options
- `--add-root` *path*; `--indirect`
See the [corresponding options](#opt-add-root) in `nix-store`.
See the [corresponding options](nix-store.md) in `nix-store`.
- `--parse`
Just parse the input files, and print their abstract syntax trees on
@ -69,7 +69,7 @@ standard input.
When used with `--eval`, print the resulting value as an XML
representation of the abstract syntax tree rather than as an ATerm.
The schema is the same as that used by the [`toXML`
built-in](#builtin-toXML).
built-in](../expressions/builtins.md).
- `--read-write-mode`
When used with `--eval`, perform evaluation in read/write mode so

50
doc/manual/src/command-ref/nix-store.md
View file

@ -79,13 +79,14 @@ The operation `--realise` essentially “builds” the specified store
paths. Realisation is a somewhat overloaded term:
- If the store path is a *derivation*, realisation ensures that the
output paths of the derivation are [valid](#gloss-validity) (i.e.,
the output path and its closure exist in the file system). This can
be done in several ways. First, it is possible that the outputs are
already valid, in which case we are done immediately. Otherwise,
there may be [substitutes](#gloss-substitute) that produce the
outputs (e.g., by downloading them). Finally, the outputs can be
produced by performing the build action described by the derivation.
output paths of the derivation are [valid](../glossary.md) (i.e.,
the output path and its closure exist in the file system). This
can be done in several ways. First, it is possible that the
outputs are already valid, in which case we are done
immediately. Otherwise, there may be [substitutes](../glossary.md)
that produce the outputs (e.g., by downloading them). Finally, the
outputs can be produced by performing the build action described
by the derivation.
- If the store path is not a derivation, realisation ensures that the
specified path is valid (i.e., it and its closure exist in the file
@ -129,11 +130,12 @@ Special exit codes:
- `101`
Build timeout, the build was aborted because it did not complete
within the specified [`timeout`](#conf-timeout).
within the specified `timeout`.
- `102`
Hash mismatch, the build output was rejected because it does not
match the specified [`outputHash`](#fixed-output-drvs).
match the [`outputHash` attribute of the
derivation](../expressions/advanced-attributes.md).
- `104`
Not deterministic, the build succeeded in check mode but the
@ -153,12 +155,12 @@ or.
## Examples
This operation is typically used to build store derivations produced by
[`nix-instantiate`](#sec-nix-instantiate):
[`nix-instantiate`](nix-instantiate.md):
$ nix-store -r $(nix-instantiate ./test.nix)
/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1
This is essentially what [`nix-build`](#sec-nix-build) does.
This is essentially what [`nix-build`](nix-build.md) does.
To test whether a previously-built derivation is deterministic:
@ -232,8 +234,7 @@ control what gets deleted and in what order:
or TiB units.
The behaviour of the collector is also influenced by the
[`keep-outputs`](#conf-keep-outputs) and
[`keep-derivations`](#conf-keep-derivations) variables in the Nix
`keep-outputs` and `keep-derivations` variables in the Nix
configuration file.
By default, the collector prints the total number of freed bytes when it
@ -307,17 +308,17 @@ symlink.
- `--force-realise`; `-f`
Realise each argument to the query first (see [`nix-store
--realise`](#rsec-nix-store-realise)).
--realise`](#operation---realise)).
## Queries
- `--outputs`
Prints out the [output paths](#gloss-output-path) of the store
Prints out the [output paths](../glossary.md) of the store
derivations *paths*. These are the paths that will be produced when
the derivation is built.
- `--requisites`; `-R`
Prints out the [closure](#gloss-closure) of the store path *paths*.
Prints out the [closure](../glossary.md) of the store path *paths*.
This query has one option:
@ -334,7 +335,7 @@ symlink.
derivation and specifying the option `--include-outputs`.
- `--references`
Prints the set of [references](#gloss-reference) of the store paths
Prints the set of [references](../glossary.md) of the store paths
*paths*, that is, their immediate dependencies. (For *all*
dependencies, use `--requisites`.)
@ -352,7 +353,7 @@ symlink.
in the Nix store that are dependent on *paths*.
- `--deriver`; `-d`
Prints the [deriver](#gloss-deriver) of the store paths *paths*. If
Prints the [deriver](../glossary.md) of the store paths *paths*. If
the path has no deriver (e.g., if it is a source file), or if the
deriver is not known (e.g., in the case of a binary-only
deployment), the string `unknown-deriver` is printed.
@ -605,13 +606,12 @@ anyway. Likewise, all permissions are left out except for the execute
bit, because all files in the Nix store have 444 or 555 permission.
Also, a NAR archive is *canonical*, meaning that “equal” paths always
produce the same NAR archive. For instance, directory entries are always
sorted so that the actual on-disk order doesn’t influence the result.
This means that the cryptographic hash of a NAR dump of a path is usable
as a fingerprint of the contents of the path. Indeed, the hashes of
store paths stored in Nix’s database (see [`nix-store -q
--hash`](#refsec-nix-store-query)) are SHA-256 hashes of the NAR dump of
each store path.
produce the same NAR archive. For instance, directory entries are
always sorted so that the actual on-disk order doesn’t influence the
result. This means that the cryptographic hash of a NAR dump of a
path is usable as a fingerprint of the contents of the path. Indeed,
the hashes of store paths stored in Nix’s database (see `nix-store -q
--hash`) are SHA-256 hashes of the NAR dump of each store path.
NAR archives support filenames of unlimited length and 64-bit file
sizes. They can contain regular files, directories, and symbolic links,

84
doc/manual/src/command-ref/opt-common.md
View file

@ -71,35 +71,34 @@ Most Nix commands accept the following command-line options:
- `--max-jobs` / `-j` *number*
Sets the maximum number of build jobs that Nix will perform in
parallel to the specified number. Specify `auto` to use the number
of CPUs in the system. The default is specified by the
[`max-jobs`](#conf-max-jobs) configuration setting, which itself
defaults to `1`. A higher value is useful on SMP systems or to
exploit I/O latency.
of CPUs in the system. The default is specified by the `max-jobs`
configuration setting, which itself defaults to `1`. A higher
value is useful on SMP systems or to exploit I/O latency.
Setting it to `0` disallows building on the local machine, which is
useful when you want builds to happen only on remote builders.
- `--cores`
Sets the value of the `NIX_BUILD_CORES` environment variable in the
invocation of builders. Builders can use this variable at their
discretion to control the maximum amount of parallelism. For
Sets the value of the `NIX_BUILD_CORES` environment variable in
the invocation of builders. Builders can use this variable at
their discretion to control the maximum amount of parallelism. For
instance, in Nixpkgs, if the derivation attribute
`enableParallelBuilding` is set to `true`, the builder passes the
`-jN` flag to GNU Make. It defaults to the value of the
[`cores`](#conf-cores) configuration setting, if set, or `1`
otherwise. The value `0` means that the builder should use all
available CPU cores in the system.
`-jN` flag to GNU Make. It defaults to the value of the `cores`
configuration setting, if set, or `1` otherwise. The value `0`
means that the builder should use all available CPU cores in the
system.
- `--max-silent-time`
Sets the maximum number of seconds that a builder can go without
producing any data on standard output or standard error. The default
is specified by the [`max-silent-time`](#conf-max-silent-time)
configuration setting. `0` means no time-out.
producing any data on standard output or standard error. The
default is specified by the `max-silent-time` configuration
setting. `0` means no time-out.
- `--timeout`
Sets the maximum number of seconds that a builder can run. The
default is specified by the [`timeout`](#conf-timeout) configuration
setting. `0` means no timeout.
default is specified by the `timeout` configuration setting. `0`
means no timeout.
- `--keep-going` / `-k`
Keep going in case of failed builds, to the greatest extent
@ -145,16 +144,17 @@ Most Nix commands accept the following command-line options:
operations will fail.
- `--arg` *name* *value*
This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell`
and `nix-build`. When evaluating Nix expressions, the expression
evaluator will automatically try to call functions that it
encounters. It can automatically call functions for which every
argument has a [default value](#ss-functions) (e.g., `{ argName ?
defaultValue }:
...`). With `--arg`, you can also call functions that have arguments
without a default value (or override a default value). That is, if
the evaluator encounters a function with an argument named *name*,
it will call it with value *value*.
This option is accepted by `nix-env`, `nix-instantiate`,
`nix-shell` and `nix-build`. When evaluating Nix expressions, the
expression evaluator will automatically try to call functions that
it encounters. It can automatically call functions for which every
argument has a [default
value](../expressions/language-constructs.md#functions) (e.g.,
`{ argName ? defaultValue }: ...`). With `--arg`, you can also
call functions that have arguments without a default value (or
override a default value). That is, if the evaluator encounters a
function with an argument named *name*, it will call it with value
*value*.
For instance, the top-level `default.nix` in Nixpkgs is actually a
function:
@ -165,28 +165,28 @@ Most Nix commands accept the following command-line options:
}: ...
So if you call this Nix expression (e.g., when you do `nix-env -i
pkgname`), the function will be called automatically using the value
[`builtins.currentSystem`](#builtin-currentSystem) for the `system`
argument. You can override this using `--arg`, e.g., `nix-env -i
pkgname --arg system
\"i686-freebsd\"`. (Note that since the argument is a Nix string
literal, you have to escape the quotes.)
pkgname`), the function will be called automatically using the
value [`builtins.currentSystem`](../expressions/builtins.md) for
the `system` argument. You can override this using `--arg`, e.g.,
`nix-env -i pkgname --arg system \"i686-freebsd\"`. (Note that
since the argument is a Nix string literal, you have to escape the
quotes.)
- `--argstr` *name* *value*
This option is like `--arg`, only the value is not a Nix expression
but a string. So instead of `--arg system \"i686-linux\"` (the outer
quotes are to keep the shell happy) you can say `--argstr system
i686-linux`.
This option is like `--arg`, only the value is not a Nix
expression but a string. So instead of `--arg system
\"i686-linux\"` (the outer quotes are to keep the shell happy) you
can say `--argstr system i686-linux`.
- `--attr` / `-A` *attrPath*
Select an attribute from the top-level Nix expression being
evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
`nix-shell` only.) The *attribute path* *attrPath* is a sequence of
attribute names separated by dots. For instance, given a top-level
Nix expression *e*, the attribute path `xorg.xorgserver` would cause
the expression `e.xorg.xorgserver` to be used. See [`nix-env
--install`](#refsec-nix-env-install-examples) for some concrete
examples.
`nix-shell` only.) The *attribute path* *attrPath* is a sequence
of attribute names separated by dots. For instance, given a
top-level Nix expression *e*, the attribute path `xorg.xorgserver`
would cause the expression `e.xorg.xorgserver` to be used. See
[`nix-env --install`](nix-env.md#operation---install) for some
concrete examples.
In addition to attribute names, you can also specify array indices.
For instance, the attribute path `foo.3.bar` selects the `bar`

30
doc/manual/src/expressions/advanced-attributes.md
View file

@ -89,10 +89,10 @@ Derivations can declare some infrequently used optional attributes.
to make it use the proxy server configuration specified by the user
in the environment variables `http_proxy` and friends.
This attribute is only allowed in [fixed-output
derivations](#fixed-output-drvs), where impurities such as these are
okay since (the hash of) the output is known in advance. It is
ignored for all other derivations.
This attribute is only allowed in *fixed-output derivations* (see
below), where impurities such as these are okay since (the hash
of) the output is known in advance. It is ignored for all other
derivations.
> **Warning**
>
@ -183,13 +183,14 @@ Derivations can declare some infrequently used optional attributes.
- `"recursive"`
The hash is computed over the NAR archive dump of the output
(i.e., the result of [`nix-store
--dump`](#refsec-nix-store-dump)). In this case, the output can
be anything, including a directory tree.
--dump`](../command-ref/nix-store.md#operation---dump)). In
this case, the output can be anything, including a directory
tree.
The `outputHash` attribute, finally, must be a string containing the
hash in either hexadecimal or base-32 notation. (See the [`nix-hash`
command](#sec-nix-hash) for information about converting to and from
base-32 notation.)
The `outputHash` attribute, finally, must be a string containing
the hash in either hexadecimal or base-32 notation. (See the
[`nix-hash` command](../command-ref/nix-hash.md) for information
about converting to and from base-32 notation.)
- `passAsFile`
A list of names of attributes that should be passed via files rather
@ -213,10 +214,11 @@ Derivations can declare some infrequently used optional attributes.
- `preferLocalBuild`
If this attribute is set to `true` and [distributed building is
enabled](#chap-distributed-builds), then, if possible, the derivaton
will be built locally instead of forwarded to a remote machine. This
is appropriate for trivial builders where the cost of doing a
download or remote build would exceed the cost of building locally.
enabled](../advanced-topics/distributed-builds.md), then, if
possible, the derivaton will be built locally instead of forwarded
to a remote machine. This is appropriate for trivial builders
where the cost of doing a download or remote build would exceed
the cost of building locally.
- `allowSubstitutes`
If this attribute is set to `false`, then Nix will always build this

39
doc/manual/src/expressions/builtins.md
View file

@ -57,19 +57,19 @@ For instance, `derivation` is also available as `builtins.derivation`.
installations that don’t have the desired built-in function.
- `builtins.compareVersions` *s1* *s2*
Compare two strings representing versions and return `-1` if version
*s1* is older than version *s2*, `0` if they are the same, and `1`
if *s1* is newer than *s2*. The version comparison algorithm is the
same as the one used by [`nix-env
-u`](#ssec-version-comparisons).
Compare two strings representing versions and return `-1` if
version *s1* is older than version *s2*, `0` if they are the same,
and `1` if *s1* is newer than *s2*. The version comparison
algorithm is the same as the one used by [`nix-env
-u`](../command-ref/nix-env.md#operation---upgrade).
- `builtins.concatLists` *lists*
Concatenate a list of lists into a single list.
- `builtins.concatStringsSep` *separator* *list*
Concatenate a list of strings with a separator between each element,
e.g. `concatStringsSep "/"
["usr" "local" "bin"] == "usr/local/bin"`
Concatenate a list of strings with a separator between each
element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] ==
"usr/local/bin"`
- `builtins.currentSystem`
The built-in value `currentSystem` evaluates to the Nix platform
@ -77,10 +77,9 @@ For instance, `derivation` is also available as `builtins.derivation`.
evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
- `builtins.deepSeq` *e1* *e2*
This is like `seq
e1
e2`, except that *e1* is evaluated *deeply*: if it’s a list or set,
its elements or attributes are also evaluated recursively.
This is like `seq e1 e2`, except that *e1* is evaluated *deeply*:
if it’s a list or set, its elements or attributes are also
evaluated recursively.
- `derivation` *attrs*; `builtins.derivation` *attrs*
`derivation` is described in [its own section](derivations.md).
@ -104,7 +103,7 @@ For instance, `derivation` is also available as `builtins.derivation`.
- `builtins.fetchurl` *url*
Download the specified URL and return the path of the downloaded
file. This function is not available if [restricted evaluation
mode](#conf-restrict-eval) is enabled.
mode](../command-ref/conf-file.md) is enabled.
- `fetchTarball` *url*; `builtins.fetchTarball` *url*
Download the specified URL, unpack it and return the path of the
@ -140,7 +139,7 @@ For instance, `derivation` is also available as `builtins.derivation`.
stdenv.mkDerivation { … }
This function is not available if [restricted evaluation
mode](#conf-restrict-eval) is enabled.
mode](../command-ref/conf-file.md) is enabled.
- `builtins.fetchGit` *args*
Fetch a path from git. *args* can be a URL, in which case the HEAD
@ -491,9 +490,8 @@ For instance, `derivation` is also available as `builtins.derivation`.
name is everything up to but not including the first dash followed
by a digit, and the version is everything following that dash. The
result is returned in a set `{ name, version }`. Thus,
`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name = "nix";
version = "0.12pre12876";
}`.
`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name =
"nix"; version = "0.12pre12876"; }`.
- `builtins.path` *args*
An enrichment of the built-in path type, based on the attributes
@ -508,9 +506,8 @@ For instance, `derivation` is also available as `builtins.derivation`.
like `@`.
- filter
A function of the type expected by
[builtins.filterSource](#builtin-filterSource), with the same
semantics.
A function of the type expected by `builtins.filterSource`,
with the same semantics.
- recursive
When `false`, when `path` is added to the store it is with a
@ -609,7 +606,7 @@ For instance, `derivation` is also available as `builtins.derivation`.
- `builtins.splitVersion` *s*
Split a string representing a version into its components, by the
same version splitting logic underlying the version comparison in
[`nix-env -u`](#ssec-version-comparisons).
[`nix-env -u`](../command-ref/nix-env.md#operation---upgrade).
- `builtins.stringLength` *e*
Return the length of the string *e*. If *e* is not a string,

10
doc/manual/src/expressions/simple-building-testing.md
View file

@ -19,11 +19,11 @@ yet. The best way to test the package is by using the command
$ ./result/bin/hello
Hello, world!
The [`-A`](#opt-attr) option selects the `hello` attribute. This is
faster than using the symbolic package name specified by the `name`
attribute (which also happens to be `hello`) and is unambiguous (there
can be multiple packages with the symbolic name `hello`, but there can
be only one attribute in a set named `hello`).
The `-A` option selects the `hello` attribute. This is faster than
using the symbolic package name specified by the `name` attribute
(which also happens to be `hello`) and is unambiguous (there can be
multiple packages with the symbolic name `hello`, but there can be
only one attribute in a set named `hello`).
`nix-build` registers the `./result` symlink as a garbage collection
root, so unless and until you delete the `./result` symlink, the output

4
doc/manual/src/installation/installing-binary.md
View file

@ -8,7 +8,7 @@ easiest way to install Nix is to run the following command:
```
If you're using macOS 10.15 (Catalina) or newer, consult [the macOS
installation instructions](#sect-macos-installation) before installing.
installation instructions](#macos-installation) before installing.
As of Nix 2.1.0, the Nix installer will always default to creating a
single-user installation, however opting in to the multi-user
@ -64,7 +64,7 @@ will invoke `sudo` as needed.
>
> If you need Nix to use a different group ID or user ID set, you will
> have to download the tarball manually and [edit the install
> script](#sect-nix-install-binary-tarball).
> script](#installing-from-a-binary-tarball).
The installer will modify `/etc/bashrc`, and `/etc/zshrc` if they exist.
The installer will first back up these files with a `.backup-before-nix`

8
doc/manual/src/installation/multi-user.md
View file

@ -39,16 +39,16 @@ expect to do many builds at the same time.
## Running the daemon
The [Nix daemon](#sec-nix-daemon) should be started as follows (as
`root`):
The [Nix daemon](../command-ref/nix-daemon.md) should be started as
follows (as `root`):
$ nix-daemon
You’ll want to put that line somewhere in your system’s boot scripts.
To let unprivileged users use the daemon, they should set the
[`NIX_REMOTE` environment variable](#envar-remote) to `daemon`. So you
should put a line like
[`NIX_REMOTE` environment variable](../command-ref/env-common.md) to
`daemon`. So you should put a line like
export NIX_REMOTE=daemon

7
doc/manual/src/package-management/basic-package-mgmt.md
View file

@ -1,8 +1,9 @@
# Basic Package Management
The main command for package management is [`nix-env`](#sec-nix-env).
You can use it to install, upgrade, and erase packages, and to query
what packages are installed or are available for installation.
The main command for package management is
[`nix-env`](../command-ref/nix-env.md). You can use it to install,
upgrade, and erase packages, and to query what packages are installed
or are available for installation.
In Nix, different users can have different “views” on the set of
installed applications. That is, there might be lots of applications

4
doc/manual/src/package-management/channels.md
View file

@ -7,8 +7,8 @@ better way: *Nix channels*.
A Nix channel is just a URL that points to a place that contains a set
of Nix expressions and a manifest. Using the command
[`nix-channel`](#sec-nix-channel) you can automatically stay up to date
with whatever is available at that URL.
[`nix-channel`](../command-ref/nix-channel.md) you can automatically
stay up to date with whatever is available at that URL.
To see the list of official NixOS channels, visit
<https://nixos.org/channels>.

10
doc/manual/src/package-management/s3-substituter.md
View file

@ -1,9 +1,9 @@
# Serving a Nix store via S3
Nix has built-in support for storing and fetching store paths from
Amazon S3 and S3-compatible services. This uses the same *binary* cache
mechanism that Nix usually uses to fetch prebuilt binaries from
[cache.nixos.org](cache.nixos.org).
Amazon S3 and S3-compatible services. This uses the same *binary*
cache mechanism that Nix usually uses to fetch prebuilt binaries from
[cache.nixos.org](https://cache.nixos.org/).
The following options can be specified as URL parameters to the S3 URL:
@ -85,8 +85,8 @@ caches.
Your bucket will need a bucket policy allowing the desired users to
perform the `s3:GetObject` and `s3:GetBucketLocation` action on all
objects in the bucket. The anonymous policy in [Anonymous Reads to your
S3-compatible binary cache](#ssec-s3-substituter-anonymous-reads) can be
objects in the bucket. The [anonymous policy given
above](#anonymous-reads-to-your-s3-compatible-binary-cache) can be
updated to have a restricted `Principal` to support this.
## Authenticated Writes to your S3-compatible binary cache

41
doc/manual/src/release-notes/rl-2.0.md
View file

@ -148,11 +148,11 @@ This release has the following new features:
`nix-store
--verify-path`.
- `nix log` shows the build log of a package or path. If the build
log is not available locally, it will try to obtain it from the
configured substituters (such as
[cache.nixos.org](cache.nixos.org), which now provides build
logs).
- `nix log` shows the build log of a package or path. If the
build log is not available locally, it will try to obtain it
from the configured substituters (such as
[cache.nixos.org](https://cache.nixos.org/), which now
provides build logs).
- `nix edit` opens the source code of a package in your editor.
@ -213,16 +213,17 @@ This release has the following new features:
current values.
- The store abstraction that Nix has had for a long time to support
store access via the Nix daemon has been extended significantly. In
particular, substituters (which used to be external programs such as
`download-from-binary-cache`) are now subclasses of the abstract
`Store` class. This allows many Nix commands to operate on such
store types. For example, `nix path-info` shows information about
paths in your local Nix store, while `nix path-info --store
https://cache.nixos.org/` shows information about paths in the
specified binary cache. Similarly, `nix-copy-closure`, `nix-push`
and substitution are all instances of the general notion of copying
paths between different kinds of Nix stores.
store access via the Nix daemon has been extended
significantly. In particular, substituters (which used to be
external programs such as `download-from-binary-cache`) are now
subclasses of the abstract `Store` class. This allows many Nix
commands to operate on such store types. For example, `nix
path-info` shows information about paths in your local Nix store,
while `nix path-info --store https://cache.nixos.org/` shows
information about paths in the specified binary cache. Similarly,
`nix-copy-closure`, `nix-push` and substitution are all instances
of the general notion of copying paths between different kinds of
Nix stores.
Stores are specified using an URI-like syntax, e.g.
<https://cache.nixos.org/> or <ssh://machine>. The following store
@ -241,7 +242,7 @@ This release has the following new features:
`/home/alice/nix/store`) to differ from its “logical” location
(typically `/nix/store`). This allows non-root users to use Nix
while still getting the benefits from prebuilt binaries from
[cache.nixos.org](cache.nixos.org).
[cache.nixos.org](https://cache.nixos.org/).
- `BinaryCacheStore` is the abstract superclass of all binary
cache stores. It supports writing build logs and NAR content
@ -356,11 +357,11 @@ This release has the following new features:
- `NIX_PATH` is now lazy, so URIs in the path are only downloaded if
they are needed for evaluation.
- You can now use <channel:> as a short-hand for
- You can now use `channel:` as a short-hand for
<https://nixos.org/channels//nixexprs.tar.xz>. For example,
`nix-build channel:nixos-15.09 -A hello` will build the GNU Hello
package from the `nixos-15.09` channel. In the future, this may use
Git to fetch updates more efficiently.
package from the `nixos-15.09` channel. In the future, this may
use Git to fetch updates more efficiently.
- When `--no-build-output` is given, the last 10 lines of the build
log will be shown if a build fails.
@ -382,7 +383,7 @@ This release has the following new features:
in all places where Nix allows URIs.
- Brotli compression is now supported. In particular,
[cache.nixos.org](cache.nixos.org) build logs are now compressed
[cache.nixos.org](https://cache.nixos.org/) build logs are now compressed
using Brotli.
- `nix-env`

22
doc/manual/src/release-notes/rl-2.1.md
View file

@ -4,18 +4,18 @@ This is primarily a bug fix release. It also reduces memory consumption
in certain situations. In addition, it has the following new features:
- The Nix installer will no longer default to the Multi-User
installation for macOS. You can still [instruct the installer to run
in multi-user mode](#sect-multi-user-installation).
installation for macOS. You can still instruct the installer to
run in multi-user mode.
- The Nix installer now supports performing a Multi-User installation
for Linux computers which are running systemd. You can [select a
Multi-User installation](#sect-multi-user-installation) by passing
the `--daemon` flag to the installer: `sh <(curl
https://nixos.org/nix/install) --daemon`.
The multi-user installer cannot handle systems with SELinux. If your
system has SELinux enabled, you can [force the installer to run in
single-user mode](#sect-single-user-installation).
- The Nix installer now supports performing a Multi-User
installation for Linux computers which are running systemd. You
can select a Multi-User installation by passing the `--daemon`
flag to the installer: `sh <(curl https://nixos.org/nix/install)
--daemon`.
The multi-user installer cannot handle systems with SELinux. If
your system has SELinux enabled, you can force the installer to
run in single-user mode.
- New builtin functions: `builtins.bitAnd`, `builtins.bitOr`,
`builtins.bitXor`, `builtins.fromTOML`, `builtins.concatMap`,