lix-project/lix
18
39
Fork 15
Code Issues 288 Code Review (Gerrit) Projects 1 Releases Wiki Activity

Fix some dangling references

Browse source
This commit is contained in:
Eelco Dolstra 2020-07-24 14:31:33 +02:00
parent 4a79b3598f
commit da3d776cb9
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
23 changed files with 139 additions and 235 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
doc/manual/src/advanced-topics/cores-vs-jobs.md
View file

@ -1,33 +1,32 @@
# Tuning Cores and Jobs
Nix has two relevant settings with regards to how your CPU cores will be
utilized: [???](#conf-cores) and [???](#conf-max-jobs). This chapter
will talk about what they are, how they interact, and their
configuration trade-offs.
Nix has two relevant settings with regards to how your CPU cores will
be utilized: `cores` and `max-jobs`. This chapter will talk about what
they are, how they interact, and their configuration trade-offs.
- [???](#conf-max-jobs)
- `max-jobs`
Dictates how many separate derivations will be built at the same
time. If you set this to zero, the local machine will do no builds.
Nix will still substitute from binary caches, and build remotely if
remote builders are configured.
time. If you set this to zero, the local machine will do no
builds. Nix will still substitute from binary caches, and build
remotely if remote builders are configured.
- [???](#conf-cores)
Suggests how many cores each derivation should use. Similar to `make
-j`.
- `cores`
Suggests how many cores each derivation should use. Similar to
`make -j`.
The [???](#conf-cores) setting determines the value of
`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to [???](#conf-cores),
unless [???](#conf-cores) equals `0`, in which case `NIX_BUILD_CORES`
will be the total number of cores in the system.
The `cores` setting determines the value of
`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to `cores`, unless
`cores` equals `0`, in which case `NIX_BUILD_CORES` will be the total
number of cores in the system.
The maximum number of consumed cores is a simple multiplication,
[???](#conf-max-jobs) \* `NIX_BUILD_CORES`.
`max-jobs` \* `NIX_BUILD_CORES`.
The balance on how to set these two independent variables depends upon
each builder's workload and hardware. Here are a few example scenarios
on a machine with 24 cores:
| [???](#conf-max-jobs) | [???](#conf-cores) | `NIX_BUILD_CORES` | Maximum Processes | Result |
| `max-jobs` | `cores` | `NIX_BUILD_CORES` | Maximum Processes | Result |
| --------------------- | ------------------ | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | 24 | 24 | 24 | One derivation will be built at a time, each one can use 24 cores. Undersold if a job can’t use 24 cores. |
| 4 | 6 | 6 | 24 | Four derivations will be built at once, each given access to six cores. |
@ -35,8 +34,6 @@ on a machine with 24 cores:
| 24 | 1 | 1 | 24 | 24 derivations can build at the same time, each using a single core. Never oversold, but derivations which require many cores will be very slow to compile. |
| 24 | 0 | 24 | 576 | 24 derivations can build at the same time, each using all the available cores of the machine. Very likely to be oversold, and very likely to suffer context switches. |
Balancing 24 Build Cores
It is up to the derivations' build script to respect host's requested
cores-per-build by following the value of the `NIX_BUILD_CORES`
environment variable.

20
doc/manual/src/advanced-topics/diff-hook.md
View file

@ -1,9 +1,8 @@
# Verifying Build Reproducibility
Specify a program with Nix's [???](#conf-diff-hook) to compare build
results when two builds produce different results. Note: this hook is
only executed if the results are not the same, this hook is not used for
determining if the results are the same.
You can use Nix's `diff-hook` setting to compare build results. Note
that this hook is only executed if the results differ; it is not used
for determining if the results are the same.
For purposes of demonstration, we'll use the following Nix file,
`deterministic.nix` for testing:
@ -93,7 +92,7 @@ has copied the build results to that directory where you can examine it.
> path will be deleted on the next garbage collection.
>
> The path is guaranteed to be alive for the duration of
> [???](#conf-diff-hook)'s execution, but may be deleted any time after.
> the `diff-hook`'s execution, but may be deleted any time after.
>
> If the comparison is performed as part of automated tooling, please
> use the diff-hook or author your tooling to handle the case where the
@ -112,9 +111,8 @@ Run the build without `--check`, and then try with `--check` again.
Automatically verify every build at build time by executing the build
multiple times.
Setting [???](#conf-repeat) and [???](#conf-enforce-determinism) in your
`nix.conf` permits the automated verification of every build Nix
performs.
Setting `repeat` and `enforce-determinism` in your `nix.conf` permits
the automated verification of every build Nix performs.
The following configuration will run each build three times, and will
require the build to be deterministic:
@ -122,9 +120,9 @@ require the build to be deterministic:
enforce-determinism = true
repeat = 2
Setting [???](#conf-enforce-determinism) to false as in the following
configuration will run the build multiple times, execute the build hook,
but will allow the build to succeed even if it does not build
Setting `enforce-determinism` to false as in the following
configuration will run the build multiple times, execute the build
hook, but will allow the build to succeed even if it does not build
reproducibly:
enforce-determinism = false

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

@ -17,9 +17,8 @@ the build loop.
# Prerequisites
This tutorial assumes you have configured an S3-compatible binary cache
according to the instructions at
[???](#ssec-s3-substituter-authenticated-writes), and that the `root`
This tutorial assumes you have [configured an S3-compatible binary
cache](../package-management/s3-substituter.md), and that the `root`
user's default AWS profile can upload to the bucket.
# Set up a Signing Key
@ -33,7 +32,7 @@ distribute the public key for verifying the authenticity of the paths.
example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
Then, add the public key and the cache URL to your `nix.conf`'s
[???](#conf-trusted-public-keys) and [???](#conf-substituters) like:
`trusted-public-keys` and `substituters` options:
substituters = https://cache.nixos.org/ s3://example-nix-cache
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=

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

@ -77,8 +77,7 @@ The following settings are currently available:
--optimise` to get rid of duplicate files.
- `builders`
A list of machines on which to perform builds. See
[???](#chap-distributed-builds) for details.
A list of machines on which to perform builds.
- `builders-use-substitutes`
If set to `true`, Nix will instruct remote build machines to use
@ -140,8 +139,6 @@ The following settings are currently available:
`-jN` flag to GNU Make. It can be overridden using the `--cores`
command line switch and defaults to `1`. The value `0` means that
the builder should use all available CPU cores in the system.
See also [???](#chap-tuning-cores-and-jobs).
- `diff-hook`
Absolute path to an executable capable of diffing build results. The
@ -298,8 +295,6 @@ The following settings are currently available:
`preferLocalBuild` derivation attribute which executes locally
regardless). It can be overridden using the `--max-jobs` (`-j`)
command line switch.
See also [???](#chap-tuning-cores-and-jobs).
- `max-silent-time`
This option defines the maximum number of seconds that a builder can
@ -429,12 +424,10 @@ The following settings are currently available:
Example:
`/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev
/nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
/nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
/nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
/nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23`.
See [???](#chap-post-build-hook) for an example implementation.
/nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
/nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
/nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
/nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23`.
- `repeat`
How many times to repeat builds to check whether they are
@ -459,8 +452,7 @@ The following settings are currently available:
`allowed-uri`. The default is `false`.
- `run-diff-hook`
If true, enable the execution of
[varlistentry\_title](#conf-diff-hook).
If true, enable the execution of the `diff-hook` program.
When using the Nix daemon, `run-diff-hook` must be set in the
`nix.conf` configuration file, and cannot be passed at the command
@ -595,15 +587,11 @@ The following settings are currently available:
Nix will print a log message at the "vomit" level for every function
entrance and function exit.
<div class="informalexample">
function-trace entered undefined position at 1565795816999559622
function-trace exited undefined position at 1565795816999581277
function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
</div>
The `undefined position` means the function call is a builtin.
Use the `contrib/stack-collapse.py` script distributed with the Nix

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

@ -46,7 +46,7 @@ expression to a low-level store derivation) and [`nix-store
All options not listed here are passed to `nix-store
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
`nix-instantiate`. See also [???](#sec-common-options).
`nix-instantiate`.
- `--no-out-link`
Do not create a symlink to the output path. Note that as a result

1
doc/manual/src/command-ref/nix-channel.md
View file

@ -13,7 +13,6 @@ Title: nix-channel
A Nix channel is a mechanism that allows you to automatically stay
up-to-date with a set of pre-built Nix expressions. A Nix channel is
just a URL that points to a place containing a set of Nix expressions.
See also [???](#sec-channels).
To see the list of official NixOS channels, visit
<https://nixos.org/channels>.

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

@ -66,7 +66,7 @@ match. Here are some examples:
This section lists the options that are common to all operations. These
options are allowed for every subcommand, though they may not always
have an effect. See also [???](#sec-common-options).
have an effect.
- `--file` / `-f` *path*
Specifies the Nix expression (designated below as the *active Nix

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

@ -30,8 +30,6 @@ the resulting store derivations are printed on standard output.
If *files* is the character `-`, then a Nix expression will be read from
standard input.
See also [???](#sec-common-options) for a list of common options.
# Options
- `--add-root` *path*; `--indirect`

2
doc/manual/src/command-ref/nix-shell.md
View file

@ -50,7 +50,7 @@ will cause `nix-shell` to print `Hello shell`.
All options not listed here are passed to `nix-store
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
`nix-instantiate`. See also [???](#sec-common-options).
`nix-instantiate`.
- `--command` *cmd*
In the environment of the derivation, run the shell command *cmd*.

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

@ -23,16 +23,15 @@ subcommand to be performed. These are documented below.
This section lists the options that are common to all operations. These
options are allowed for every subcommand, though they may not always
have an effect. See also [???](#sec-common-options) for a list of common
options.
have an effect.
- `--add-root` *path*
Causes the result of a realisation (`--realise` and
`--force-realise`) to be registered as a root of the garbage
collector(see [???](#ssec-gc-roots)). The root is stored in *path*,
which must be inside a directory that is scanned for roots by the
garbage collector (i.e., typically in a subdirectory of
`/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used.
collector. The root is stored in *path*, which must be inside a
directory that is scanned for roots by the garbage collector
(i.e., typically in a subdirectory of `/nix/var/nix/gcroots/`)
*unless* the `--indirect` flag is used.
If there are multiple results, then multiple symlinks will be
created by sequentially numbering symlinks beyond the first one
@ -209,8 +208,7 @@ The following suboperations may be specified:
- `--print-roots`
This operation prints on standard output the set of roots used by
the garbage collector. What constitutes a root is described in
[???](#ssec-gc-roots).
the garbage collector.
- `--print-live`
This operation prints on standard output the set of “live” store

22
doc/manual/src/expressions/arguments-variables.md
View file

@ -1,11 +1,12 @@
# Arguments and Variables
The Nix expression in [???](#ex-hello-nix) is a function; it is missing
some arguments that have to be filled in somewhere. In the Nix Packages
collection this is done in the file `pkgs/top-level/all-packages.nix`,
where all Nix expressions for packages are imported and called with the
appropriate arguments. Here are some fragments of `all-packages.nix`,
with annotations of what they mean:
The [Nix expression for GNU Hello](expression-syntax.md) is a
function; it is missing some arguments that have to be filled in
somewhere. In the Nix Packages collection this is done in the file
`pkgs/top-level/all-packages.nix`, where all Nix expressions for
packages are imported and called with the appropriate arguments. Here
are some fragments of `all-packages.nix`, with annotations of what
they mean:
...
@ -35,9 +36,10 @@ with annotations of what they mean:
2. Here we *import* the Nix expression for GNU Hello. The import
operation just loads and returns the specified Nix expression. In
fact, we could just have put the contents of [???](#ex-hello-nix) in
`all-packages.nix` at this point. That would be completely
equivalent, but it would make the file rather bulky.
fact, we could just have put the contents of the Nix expression
for GNU Hello in `all-packages.nix` at this point. That would be
completely equivalent, but it would make `all-packages.nix` rather
bulky.
Note that we refer to `../applications/misc/hello/ex-1`, not
`../applications/misc/hello/ex-1/default.nix`. When you try to
@ -54,7 +56,7 @@ with annotations of what they mean:
The result of this function call is an actual derivation that can be
built by Nix (since when we fill in the arguments of the function,
what we get is its body, which is the call to `stdenv.mkDerivation`
in [???](#ex-hello-nix)).
in the [Nix expression for GNU Hello](expression-syntax.md)).
> **Note**
>

8
doc/manual/src/expressions/build-script.md
View file

@ -25,10 +25,10 @@ steps to elucidate what a builder does. It performs the following steps:
So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The
environment variable `stdenv` points to the location of the standard
environment being used. (It wasn't specified explicitly as an
attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
automatically.)
environment variable `stdenv` points to the location of the
standard environment being used. (It wasn't specified explicitly
as an attribute in Hello's Nix expression, but `mkDerivation` adds
it automatically.)
2. Since Hello needs Perl, we have to make sure that Perl is in the
`PATH`. The `perl` environment variable points to the location of

72
doc/manual/src/expressions/builder-syntax.md
View file

@ -1,72 +0,0 @@
# Builder Syntax
source $stdenv/setup
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
[example\_title](#ex-hello-builder) shows the builder referenced from
Hello's Nix expression (stored in
`pkgs/applications/misc/hello/ex-1/builder.sh`). The builder can
actually be made a lot shorter by using the *generic builder* functions
provided by `stdenv`, but here we write out the build steps to elucidate
what a builder does. It performs the following steps:
- When Nix runs a builder, it initially completely clears the
environment (except for the attributes declared in the derivation).
For instance, the `PATH` variable is empty\[1\]. This is done to
prevent undeclared inputs from being used in the build process. If
for example the `PATH` contained `/usr/bin`, then you might
accidentally use `/usr/bin/gcc`.
So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The
environment variable `stdenv` points to the location of the standard
environment being used. (It wasn't specified explicitly as an
attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
automatically.)
- Since Hello needs Perl, we have to make sure that Perl is in the
`PATH`. The `perl` environment variable points to the location of
the Perl package (since it was passed in as an attribute to the
derivation), so `$perl/bin` is the directory containing the Perl
interpreter.
- Now we have to unpack the sources. The `src` attribute was bound to
the result of fetching the Hello source tarball from the network, so
the `src` environment variable points to the location in the Nix
store to which the tarball was downloaded. After unpacking, we `cd`
to the resulting source directory.
The whole build is performed in a temporary directory created in
`/tmp`, by the way. This directory is removed after the builder
finishes, so there is no need to clean up the sources afterwards.
Also, the temporary directory is always newly created, so you don't
have to worry about files from previous builds interfering with the
current build.
- GNU Hello is a typical Autoconf-based package, so we first have to
run its `configure` script. In Nix every package is stored in a
separate location in the Nix store, for instance
`/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
computes this path by cryptographically hashing all attributes of
the derivation. The path is passed to the builder through the `out`
environment variable. So here we give `configure` the parameter
`--prefix=$out` to cause Hello to be installed in the expected
location.
- Finally we build Hello (`make`) and install it into the location
specified by `out` (`make install`).
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
script is evaluated with Bash's `-e` option, which causes the script to
be aborted if any command fails without an error check.
1. Actually, it's initialised to `/path-not-set` to prevent Bash from
setting it to a default value.

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

@ -83,7 +83,7 @@ For instance, `derivation` is also available as `builtins.derivation`.
its elements or attributes are also evaluated recursively.
- `derivation` *attrs*; `builtins.derivation` *attrs*
`derivation` is described in [???](#ssec-derivation).
`derivation` is described in [its own section](derivations.md).
- `dirOf` *s*; `builtins.dirOf` *s*
Return the directory part of the string *s*, that is, everything
@ -233,8 +233,8 @@ For instance, `derivation` is also available as `builtins.derivation`.
> **Note**
>
> Nix will refetch the branch in accordance to
> [???](#conf-tarball-ttl).
> Nix will refetch the branch in accordance with
> the option `tarball-ttl`.
> **Note**
>
@ -351,19 +351,18 @@ For instance, `derivation` is also available as `builtins.derivation`.
- `import` *path*; `builtins.import` *path*
Load, parse and return the Nix expression in the file *path*. If
*path* is a directory, the file ` default.nix
` in that directory is loaded. Evaluation aborts if the file
doesn’t exist or contains an incorrect Nix expression. `import`
implements Nix’s module system: you can put any Nix expression (such
as a set or a function) in a separate file, and use it from Nix
expressions in other files.
*path* is a directory, the file ` default.nix ` in that directory
is loaded. Evaluation aborts if the file doesn’t exist or contains
an incorrect Nix expression. `import` implements Nix’s module
system: you can put any Nix expression (such as a set or a
function) in a separate file, and use it from Nix expressions in
other files.
> **Note**
>
> Unlike some languages, `import` is a regular function in Nix.
> Paths using the angle bracket syntax (e.g., `
> > > > > import` *\<foo\>*) are normal path values (see
> [???](#ssec-values)).
> Paths using the angle bracket syntax (e.g., `import` *\<foo\>*)
> are [normal path values](language-values.md).
A Nix expression loaded by `import` must not contain any *free
variables* (identifiers that are not defined in the Nix expression
@ -643,11 +642,12 @@ For instance, `derivation` is also available as `builtins.derivation`.
(which is not the case for `abort`).
- `builtins.toFile` *name* *s*
Store the string *s* in a file in the Nix store and return its path.
The file has suffix *name*. This file can be used as an input to
derivations. One application is to write builders “inline”. For
instance, the following Nix expression combines [???](#ex-hello-nix)
and [???](#ex-hello-builder) into one file:
Store the string *s* in a file in the Nix store and return its
path. The file has suffix *name*. This file can be used as an
input to derivations. One application is to write builders
“inline”. For instance, the following Nix expression combines the
[Nix expression for GNU Hello](expression-syntax.md) and its
[build script](build-script.md) into one file:
{ stdenv, fetchurl, perl }:
@ -688,8 +688,9 @@ For instance, `derivation` is also available as `builtins.derivation`.
";
```
Note that `${configFile}` is an antiquotation (see
[???](#ssec-values)), so the result of the expression `configFile`
Note that `${configFile}` is an
[antiquotation](language-values.md), so the result of the
expression `configFile`
(i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be
spliced into the resulting string.
@ -786,17 +787,17 @@ For instance, `derivation` is also available as `builtins.derivation`.
container contains a number of servlets (`*.war` files) each
exported under a specific URI prefix. So the servlet configuration
is a list of sets containing the `path` and `war` of the servlet
([???](#ex-toxml-co-servlets)). This kind of information is
difficult to communicate with the normal method of passing
information through an environment variable, which just concatenates
everything together into a string (which might just work in this
case, but wouldn’t work if fields are optional or contain lists
themselves). Instead the Nix expression is converted to an XML
representation with `toXML`, which is unambiguous and can easily be
processed with the appropriate tools. For instance, in the example
an XSLT stylesheet (at point ②) is applied to it (at point ①) to
generate the XML configuration file for the Jetty server. The XML
representation produced at point ③ by `toXML` is as follows:
(①). This kind of information is difficult to communicate with the
normal method of passing information through an environment
variable, which just concatenates everything together into a
string (which might just work in this case, but wouldn’t work if
fields are optional or contain lists themselves). Instead the Nix
expression is converted to an XML representation with `toXML`,
which is unambiguous and can easily be processed with the
appropriate tools. For instance, in the example an XSLT stylesheet
(at point ②) is applied to it (at point ①) to generate the XML
configuration file for the Jetty server. The XML representation
produced at point ③ by `toXML` is as follows:
<?xml version='1.0' encoding='utf-8'?>
<expr>
@ -820,10 +821,10 @@ For instance, `derivation` is also available as `builtins.derivation`.
</list>
</expr>
Note that [???](#ex-toxml) uses the `toFile` built-in to write the
builder and the stylesheet “inline” in the Nix expression. The path
of the stylesheet is spliced into the builder using the syntax
`xsltproc ${stylesheet}`.
Note that we used the `toFile` built-in to write the builder and
the stylesheet “inline” in the Nix expression. The path of the
stylesheet is spliced into the builder using the syntax `xsltproc
${stylesheet}`.
- `builtins.trace` *e1* *e2*
Evaluate *e1* and print its abstract syntax representation on

5
doc/manual/src/expressions/derivations.md
View file

@ -9,8 +9,9 @@ the attributes of which specify the inputs of the build.
`"x86_64-darwin"`. (To figure out your system type, run `nix -vv
--version`.) The build can only be performed on a machine and
operating system matching the system type. (Nix can automatically
forward builds for other platforms by forwarding them to other
machines; see [???](#chap-distributed-builds).)
[forward builds for other
platforms](../advanced-topics/distributed-builds.md) by forwarding
them to other machines.)
- There must be an attribute named `name` whose value must be a
string. This is used as a symbolic name for the package by

7
doc/manual/src/expressions/expression-syntax.md
View file

@ -61,9 +61,10 @@ elements (referenced from the figure by number):
sometimes be omitted, in which case `mkDerivation` will fill in a
default builder (which does a `configure; make; make install`, in
essence). Hello is sufficiently simple that the default builder
would suffice, but in this case, we will show an actual builder for
educational purposes. The value `./builder.sh` refers to the shell
script shown in [???](#ex-hello-builder), discussed below.
would suffice, but in this case, we will show an actual builder
for educational purposes. The value `./builder.sh` refers to the
shell script shown in the [next section](build-script.md),
discussed below.
5. The builder has to know what the sources of the package are. Here,
the attribute `src` is bound to the result of a call to the

13
doc/manual/src/expressions/generic-builder.md
View file

@ -1,7 +1,7 @@
# Generic Builder Syntax
Recall from [???](#ex-hello-builder) that the builder looked something
like this:
Recall that the [build script for GNU Hello](build-script.md) looked
something like this:
PATH=$perl/bin:$PATH
tar xvfz $src
@ -37,11 +37,10 @@ Here is what each line means:
2. The function `genericBuild` is defined in the file `$stdenv/setup`.
3. The final step calls the shell function `genericBuild`, which
performs the steps that were done explicitly in
[???](#ex-hello-builder). The generic builder is smart enough to
figure out whether to unpack the sources using `gzip`, `bzip2`, etc.
It can be customised in many ways; see the Nixpkgs manual for
details.
performs the steps that were done explicitly in the previous build
script. The generic builder is smart enough to figure out whether
to unpack the sources using `gzip`, `bzip2`, etc. It can be
customised in many ways; see the Nixpkgs manual for details.
Discerning readers will note that the `buildInputs` could just as well
have been set in the Nix expression, like this:

7
doc/manual/src/expressions/language-operators.md
View file

@ -1,8 +1,7 @@
# Operators
[table\_title](#table-operators) lists the operators in the Nix
expression language, in order of precedence (from strongest to weakest
binding).
The table below lists the operators in the Nix expression language, in
order of precedence (from strongest to weakest binding).
| Name | Syntax | Associativity | Description | Precedence |
| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
@ -28,5 +27,3 @@ binding).
| Logical OR | *e1* `\|\|` *e2* | left | Logical OR. | 13 |
| Logical Implication | *e1* `->` *e2* | none | Logical implication (equivalent to `!e1 \|\|
e2`). | 14 |
Operators

38
doc/manual/src/glossary.md
View file

@ -3,7 +3,7 @@
- derivation
A description of a build action. The result of a derivation is a
store object. Derivations are typically specified in Nix expressions
using the [`derivation` primitive](#ssec-derivation). These are
using the [`derivation` primitive](expressions/derivations.md). These are
translated into low-level *store derivations* (implicitly by
`nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
@ -53,20 +53,19 @@
paths.
- reachable
A store path `Q` is reachable from another store path `P` if `Q` is
in the [closure](#gloss-closure) of the
[references](#gloss-reference) relation.
A store path `Q` is reachable from another store path `P` if `Q`
is in the *closure* of the *references* relation.
- closure
The closure of a store path is the set of store paths that are
directly or indirectly “reachable” from that store path; that is,
it’s the closure of the path under the
[references](#gloss-reference) relation. For a package, the closure
of its derivation is equivalent to the build-time dependencies,
while the closure of its output path is equivalent to its runtime
dependencies. For correct deployment it is necessary to deploy whole
closures, since otherwise at runtime files could be missing. The
command `nix-store -qR` prints out closures of store paths.
it’s the closure of the path under the *references* relation. For
a package, the closure of its derivation is equivalent to the
build-time dependencies, while the closure of its output path is
equivalent to its runtime dependencies. For correct deployment it
is necessary to deploy whole closures, since otherwise at runtime
files could be missing. The command `nix-store -qR` prints out
closures of store paths.
As an example, if the store object at path `P` contains a reference
to path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
@ -76,7 +75,7 @@
A store path produced by a derivation.
- deriver
The deriver of an [output path](#gloss-output-path) is the store
The deriver of an *output path* is the store
derivation that built it.
- validity
@ -87,16 +86,15 @@
- user environment
An automatically generated store object that consists of a set of
symlinks to “active” applications, i.e., other store paths. These
are generated automatically by [`nix-env`](#sec-nix-env). See
[???](#sec-profiles).
are generated automatically by
[`nix-env`](command-ref/nix-env.md). See *profiles*.
- profile
A symlink to the current [user environment](#gloss-user-env) of a
user, e.g., `/nix/var/nix/profiles/default`.
A symlink to the current *user environment* of a user, e.g.,
`/nix/var/nix/profiles/default`.
- NAR
A *N*ix *AR*chive. This is a serialisation of a path in the Nix
store. It can contain regular files, directories and symbolic links.
NARs are generated and unpacked using `nix-store --dump` and
`nix-store
--restore`.
store. It can contain regular files, directories and symbolic
links. NARs are generated and unpacked using `nix-store --dump`
and `nix-store --restore`.

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

@ -24,11 +24,11 @@ or completely new ones.)
You can manually download the latest version of Nixpkgs from
<http://nixos.org/nixpkgs/download.html>. However, it’s much more
convenient to use the Nixpkgs *channel*, since it makes it easy to stay
up to date with new versions of Nixpkgs. (Channels are described in more
detail in [???](#sec-channels).) Nixpkgs is automatically added to your
list of “subscribed” channels when you install Nix. If this is not the
case for some reason, you can add it as follows:
convenient to use the Nixpkgs [*channel*](channels.md), since it makes
it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is
automatically added to your list of “subscribed” channels when you
install Nix. If this is not the case for some reason, you can add it
as follows:
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update

2
doc/manual/src/package-management/copy-closure.md
View file

@ -8,7 +8,7 @@ dependencies:
$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)
See [???](#sec-nix-copy-closure) for details.
See the [manpage for `nix-copy-closure`](../command-ref/nix-copy-closure.md) for details.
With `nix-store
--export` and `nix-store --import` you can write the closure of a store

9
doc/manual/src/package-management/package-management.md
View file

@ -1,4 +1,5 @@
This chapter discusses how to do package management with Nix, i.e., how
to obtain, install, upgrade, and erase packages. This is the “user’s”
perspective of the Nix system — people who want to *create* packages
should consult [???](#chap-writing-nix-expressions).
This chapter discusses how to do package management with Nix, i.e.,
how to obtain, install, upgrade, and erase packages. This is the
“user’s” perspective of the Nix system — people who want to *create*
packages should consult the [chapter on writing Nix
expressions](../expressions/writing-nix-expressions.md).

3
doc/manual/src/package-management/profiles.md
View file

@ -104,8 +104,7 @@ These commands switch to the `my-profile` and default profile,
respectively. If the profile doesn’t exist, it will be created
automatically. You should be careful about storing a profile in another
location than the `profiles` directory, since otherwise it might not be
used as a root of the garbage collector (see
[???](#sec-garbage-collection)).
used as a root of the [garbage collector](garbage-collection.md).
All `nix-env` operations work on the profile pointed to by
`~/.nix-profile`, but you can override this using the `--profile` option