wroclaw-git-backups/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-07-07 01:51:47 +02:00
Code 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
Download patch file Download diff file Expand all files Collapse all files

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