diff options
| -rw-r--r-- | doc/manual/command-ref/nix-instantiate.xml | 2 | ||||
| -rw-r--r-- | doc/manual/command-ref/opt-common.xml | 2 | ||||
| -rw-r--r-- | doc/manual/expressions/build-script.xml | 11 | ||||
| -rw-r--r-- | doc/manual/expressions/derivations.xml | 19 | ||||
| -rw-r--r-- | doc/manual/expressions/generic-builder.xml | 6 | ||||
| -rw-r--r-- | doc/manual/expressions/language-constructs.xml | 7 | ||||
| -rw-r--r-- | doc/manual/expressions/language-values.xml | 11 | ||||
| -rw-r--r-- | doc/manual/expressions/simple-expression.xml | 7 | ||||
| -rw-r--r-- | doc/manual/packages/profiles.xml | 13 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-instantiate.md | 9 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/opt-common.md | 6 | ||||
| -rw-r--r-- | doc/manual/src/expressions/build-script.md | 10 | ||||
| -rw-r--r-- | doc/manual/src/expressions/derivations.md | 17 | ||||
| -rw-r--r-- | doc/manual/src/expressions/generic-builder.md | 15 | ||||
| -rw-r--r-- | doc/manual/src/expressions/language-constructs.md | 7 | ||||
| -rw-r--r-- | doc/manual/src/expressions/language-values.md | 21 | ||||
| -rw-r--r-- | doc/manual/src/expressions/simple-expression.md | 10 | ||||
| -rw-r--r-- | doc/manual/src/package-management/profiles.md | 16 |
18 files changed, 79 insertions, 110 deletions
diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml index d67be4924..dc055fa51 100644 --- a/doc/manual/command-ref/nix-instantiate.xml +++ b/doc/manual/command-ref/nix-instantiate.xml @@ -106,7 +106,7 @@ input.</para> <varlistentry><term><option>--find-file</option></term> <listitem><para>Look up the given files in Nix’s search path (as - specified by the <envar linkend="env-NIX_PATH">NIX_PATH</literal> + specified by the <literal linkend="env-NIX_PATH">NIX_PATH</literal> environment variable). If found, print the corresponding absolute paths on standard output. For instance, if <literal>NIX_PATH</literal> is diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml index 67950e94b..a095039b9 100644 --- a/doc/manual/command-ref/opt-common.xml +++ b/doc/manual/command-ref/opt-common.xml @@ -369,7 +369,7 @@ <varlistentry xml:id="opt-I"><term><option>-I</option> <emphasis>path</emphasis></term> <listitem><para>Add a path to the Nix expression search path. This - option may be given multiple times. See the <envar + option may be given multiple times. See the <literal linkend="env-NIX_PATH">NIX_PATH</literal> environment variable for information on the semantics of the Nix search path. Paths added through <option>-I</option> take precedence over diff --git a/doc/manual/expressions/build-script.xml b/doc/manual/expressions/build-script.xml index c9af198f2..5c55954fc 100644 --- a/doc/manual/expressions/build-script.xml +++ b/doc/manual/expressions/build-script.xml @@ -33,13 +33,10 @@ steps:</para> <para>When Nix runs a builder, it initially completely clears the environment (except for the attributes declared in the - derivation). For instance, the <literal>PATH</literal> variable is - empty<footnote><para>Actually, it's initialised to - <filename>/path-not-set</filename> to prevent Bash from setting it - to a default value.</para></footnote>. This is done to prevent - undeclared inputs from being used in the build process. If for - example the <literal>PATH</literal> contained - <filename>/usr/bin</filename>, then you might accidentally use + derivation). This is done to prevent undeclared inputs from being + used in the build process. If for example the + <literal>PATH</literal> contained <filename>/usr/bin</filename>, + then you might accidentally use <filename>/usr/bin/gcc</filename>.</para> <para>So the first step is to set up the environment. This is diff --git a/doc/manual/expressions/derivations.xml b/doc/manual/expressions/derivations.xml index a11de0088..0625bcdfe 100644 --- a/doc/manual/expressions/derivations.xml +++ b/doc/manual/expressions/derivations.xml @@ -13,16 +13,15 @@ of which specify the inputs of the build.</para> <itemizedlist> - <listitem xml:id="attr-system"><para>There must be an attribute named - <varname>system</varname> whose value must be a string specifying a - Nix platform identifier, such as <literal>"i686-linux"</literal> or - <literal>"x86_64-darwin"</literal><footnote><para>To figure out - your platform identifier, look at the line <quote>Checking for the - canonical Nix system name</quote> in the output of Nix's - <filename>configure</filename> script.</para></footnote> The build - can only be performed on a machine and operating system matching the - platform identifier. (Nix can automatically forward builds for - other platforms by forwarding them to other machines; see <xref + <listitem xml:id="attr-system"><para>There must be an attribute + named <varname>system</varname> whose value must be a string + specifying a Nix system type, such as + <literal>"i686-linux"</literal> or + <literal>"x86_64-darwin"</literal>. (To figure out your system type, + run <literal>nix -vv --version</literal>.) 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 <xref linkend='chap-distributed-builds' />.)</para></listitem> <listitem><para>There must be an attribute named diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml index f6e67813d..a6f258abc 100644 --- a/doc/manual/expressions/generic-builder.xml +++ b/doc/manual/expressions/generic-builder.xml @@ -42,14 +42,14 @@ genericBuild ③</programlisting> <filename>bin</filename> subdirectory, it's added to <literal>PATH</literal>; if it has a <filename>include</filename> subdirectory, it's added to GCC's header search path; and so - on.<footnote><para>How does it work? <filename>setup</filename> - tries to source the file + on. (This is implemented in a modular way: + <filename>setup</filename> tries to source the file <filename><emphasis>pkg</emphasis>/nix-support/setup-hook</filename> of all dependencies. These “setup hooks” can then set up whatever environment variables they want; for instance, the setup hook for Perl sets the <literal>PERL5LIB</literal> environment variable to contain the <filename>lib/site_perl</filename> directories of all - inputs.</para></footnote> + inputs.) </para> </listitem> diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml index 86c25d723..e1c589f61 100644 --- a/doc/manual/expressions/language-constructs.xml +++ b/doc/manual/expressions/language-constructs.xml @@ -26,7 +26,7 @@ is, in a normal (non-recursive) set, attributes are not added to the lexical scope; in a recursive set, they are.</para> <para>Recursive sets of course introduce the danger of infinite -recursion. For example, +recursion. For example, the expression <programlisting> rec { @@ -34,9 +34,8 @@ rec { y = x; }.x</programlisting> -does not terminate<footnote><para>Actually, Nix detects infinite -recursion in this case and aborts (<quote>infinite recursion -encountered</quote>).</para></footnote>.</para> +will crash with an <literal>infinite recursion encountered</literal> +error message.</para> </section> diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml index cebafb1f5..5520a4938 100644 --- a/doc/manual/expressions/language-values.xml +++ b/doc/manual/expressions/language-values.xml @@ -154,11 +154,10 @@ stdenv.mkDerivation { <listitem><para><emphasis>Paths</emphasis>, e.g., <filename>/bin/sh</filename> or <filename>./builder.sh</filename>. - A path must contain at least one slash to be recognised as such; for - instance, <filename>builder.sh</filename> is not a - path<footnote><para>It's parsed as an expression that selects the - attribute <varname>sh</varname> from the variable - <varname>builder</varname>.</para></footnote>. If the file name is + A path must contain at least one slash to be recognised as such. For + instance, <filename>builder.sh</filename> is not a path: it's parsed + as an expression that selects the attribute <varname>sh</varname> + from the variable <varname>builder</varname>. If the file name is relative, i.e., if it does not begin with a slash, it is made absolute at parse time relative to the directory of the Nix expression that contained it. For instance, if a Nix expression in @@ -176,7 +175,7 @@ stdenv.mkDerivation { <para>Paths can also be specified between angle brackets, e.g. <literal><nixpkgs></literal>. This means that the directories listed in the environment variable - <envar linkend="env-NIX_PATH">NIX_PATH</literal> will be searched + <literal linkend="env-NIX_PATH">NIX_PATH</literal> will be searched for the given file or directory name. </para> diff --git a/doc/manual/expressions/simple-expression.xml b/doc/manual/expressions/simple-expression.xml index 29fd872ee..ad97220a8 100644 --- a/doc/manual/expressions/simple-expression.xml +++ b/doc/manual/expressions/simple-expression.xml @@ -21,10 +21,9 @@ need to do three things: such as dependencies, sources, and so on.</para></listitem> <listitem><para>Write a <emphasis>builder</emphasis>. This is a - shell script<footnote><para>In fact, it can be written in any - language, but typically it's a <command>bash</command> shell - script.</para></footnote> that actually builds the package from - the inputs.</para></listitem> + shell script that builds the package from the inputs. (In fact, it + can be written in any language, but typically it's a + <command>bash</command> shell script.)</para></listitem> <listitem><para>Add the package to the file <filename>pkgs/top-level/all-packages.nix</filename>. The Nix diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml index d7529d56c..3b8c5e293 100644 --- a/doc/manual/packages/profiles.xml +++ b/doc/manual/packages/profiles.xml @@ -18,13 +18,12 @@ of the Subversion package might be stored in a directory while another version might be stored in <filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>. The long strings prefixed to the directory names are cryptographic -hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in -a base-32 notation, to be precise.</para></footnote> of -<emphasis>all</emphasis> inputs involved in building the package — -sources, dependencies, compiler flags, and so on. So if two packages -differ in any way, they end up in different locations in the file -system, so they don’t interfere with each other. Here is what a part -of a typical Nix store looks like:</para> +hashes (to be precise, 160-bit truncations of SHA-256 hashes encoded +in a base-32 notation) of <emphasis>all</emphasis> inputs involved in +building the package — sources, dependencies, compiler flags, and so +on. So if two packages differ in any way, they end up in different +locations in the file system, so they don’t interfere with each other. +Here is what a part of a typical Nix store looks like:</para> <mediaobject> <imageobject> diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index 179fbf5ba..6c9f2d3e1 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -82,11 +82,10 @@ See also [???](#sec-common-options) for a list of common options. - `--find-file` Look up the given files in Nix’s search path (as specified by the - NIX\_PATH\</literal\> environment variable). If found, print the - corresponding absolute paths on standard output. For instance, if - `NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate - --find-file nixpkgs/default.nix` will print - `/home/alice/nixpkgs/default.nix`. + `NIX_PATH` environment variable). If found, print the corresponding + absolute paths on standard output. For instance, if `NIX_PATH` is + `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file + nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`. - `--strict` When used with `--eval`, recursively evaluate list elements and diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md index dce95773a..b9c65c81d 100644 --- a/doc/manual/src/command-ref/opt-common.md +++ b/doc/manual/src/command-ref/opt-common.md @@ -206,9 +206,9 @@ Most Nix commands accept the following command-line options: - `-I` *path* Add a path to the Nix expression search path. This option may be - given multiple times. See the NIX\_PATH\</literal\> environment - variable for information on the semantics of the Nix search path. - Paths added through `-I` take precedence over `NIX_PATH`. + given multiple times. See the `NIX_PATH` environment variable for + information on the semantics of the Nix search path. Paths added + through `-I` take precedence over `NIX_PATH`. - `--option` *name* *value* Set the Nix configuration option *name* to *value*. This overrides diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md index f922182c2..57222de85 100644 --- a/doc/manual/src/expressions/build-script.md +++ b/doc/manual/src/expressions/build-script.md @@ -19,10 +19,9 @@ steps to elucidate what a builder does. It performs the following steps: 1. 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`. + 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 @@ -67,6 +66,3 @@ 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. diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md index a4df20baa..4cb233e2e 100644 --- a/doc/manual/src/expressions/derivations.md +++ b/doc/manual/src/expressions/derivations.md @@ -5,11 +5,12 @@ describe a single derivation (a build action). It takes as input a set, the attributes of which specify the inputs of the build. - There must be an attribute named `system` whose value must be a - string specifying a Nix platform identifier, such as `"i686-linux"` - or `"x86_64-darwin"`\[1\] The build can only be performed on a - machine and operating system matching the platform identifier. (Nix - can automatically forward builds for other platforms by forwarding - them to other machines; see [???](#chap-distributed-builds).) + string specifying a Nix system type, such as `"i686-linux"` or + `"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).) - There must be an attribute named `name` whose value must be a string. This is used as a symbolic name for the package by @@ -146,9 +147,3 @@ The builder is executed as follows: supported by Nix. This is because the Nix archives used in deployment have no concept of ownership information, and because it makes the build result dependent on the user performing the build. - -<!-- end list --> - -1. To figure out your platform identifier, look at the line “Checking - for the canonical Nix system name” in the output of Nix's - `configure` script. diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index 90bdc556b..6942abe70 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -27,8 +27,12 @@ Here is what each line means: 1. The `buildInputs` variable tells `setup` to use the indicated packages as “inputs”. This means that if a package provides a `bin` subdirectory, it's added to `PATH`; if it has a `include` - subdirectory, it's added to GCC's header search path; and so - on.\[1\] + subdirectory, it's added to GCC's header search path; and so on. + (This is implemented in a modular way: `setup` tries to source the + file `pkg/nix-support/setup-hook` of all dependencies. These “setup + hooks” can then set up whatever environment variables they want; for + instance, the setup hook for Perl sets the `PERL5LIB` environment + variable to contain the `lib/site_perl` directories of all inputs.) 2. The function `genericBuild` is defined in the file `$stdenv/setup`. @@ -55,10 +59,3 @@ shorter: In fact, `mkDerivation` provides a default builder that looks exactly like that, so it is actually possible to omit the builder for Hello entirely. - -1. How does it work? `setup` tries to source the file - `pkg/nix-support/setup-hook` of all dependencies. These “setup - hooks” can then set up whatever environment variables they want; - for instance, the setup hook for Perl sets the `PERL5LIB` - environment variable to contain the `lib/site_perl` directories of - all inputs. diff --git a/doc/manual/src/expressions/language-constructs.md b/doc/manual/src/expressions/language-constructs.md index 2699d675f..8e267a799 100644 --- a/doc/manual/src/expressions/language-constructs.md +++ b/doc/manual/src/expressions/language-constructs.md @@ -17,14 +17,14 @@ would be invalid if no such variable exists. That is, in a normal recursive set, they are. Recursive sets of course introduce the danger of infinite recursion. For -example, +example, the expression rec { x = y; y = x; }.x -does not terminate\[1\]. +will crash with an `infinite recursion encountered` error message. ## Let-expressions @@ -304,6 +304,3 @@ establishes the same scope as Comments can be single-line, started with a `#` character, or inline/multi-line, enclosed within `/* ... */`. - -1. Actually, Nix detects infinite recursion in this case and aborts - (“infinite recursion encountered”). diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index 8ffe2f0f9..eca2cab51 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -108,12 +108,14 @@ Nix has the following basic data types: floating point number will have a floating point number as a result. - *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at - least one slash to be recognised as such; for instance, `builder.sh` - is not a path\[1\]. If the file name is relative, i.e., if it does - not begin with a slash, it is made absolute at parse time relative - to the directory of the Nix expression that contained it. For - instance, if a Nix expression in `/foo/bar/bla.nix` refers to - `../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`. + least one slash to be recognised as such. For instance, `builder.sh` + is not a path: it's parsed as an expression that selects the + attribute `sh` from the variable `builder`. If the file name is + relative, i.e., if it does not begin with a slash, it is made + absolute at parse time relative to the directory of the Nix + expression that contained it. For instance, if a Nix expression in + `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path + is `/foo/xyzzy/fnord.nix`. If the first component of a path is a `~`, it is interpreted as if the rest of the path were relative to the user's home directory. @@ -122,8 +124,8 @@ Nix has the following basic data types: Paths can also be specified between angle brackets, e.g. `<nixpkgs>`. This means that the directories listed in the - environment variable NIX\_PATH\</literal\> will be searched for the - given file or directory name. + environment variable `NIX_PATH` will be searched for the given file + or directory name. - *Booleans* with values `true` and `false`. @@ -210,6 +212,3 @@ passed in first , e.g., evaluates to `2`. This can be used to attach metadata to a function without the caller needing to treat it specially, or to implement a form of object-oriented programming, for example. - -1. It's parsed as an expression that selects the attribute `sh` from - the variable `builder`. diff --git a/doc/manual/src/expressions/simple-expression.md b/doc/manual/src/expressions/simple-expression.md index 9023f97a4..857f71b9b 100644 --- a/doc/manual/src/expressions/simple-expression.md +++ b/doc/manual/src/expressions/simple-expression.md @@ -12,16 +12,12 @@ do three things: describes all the inputs involved in building the package, such as dependencies, sources, and so on. -2. Write a *builder*. This is a shell script\[1\] that actually builds - the package from the inputs. +2. Write a *builder*. This is a shell script that builds the package + from the inputs. (In fact, it can be written in any language, but + typically it's a `bash` shell script.) 3. Add the package to the file `pkgs/top-level/all-packages.nix`. The Nix expression written in the first step is a *function*; it requires other packages in order to build it. In this step you put it all together, i.e., you call the function with the right arguments to build the actual package. - -<!-- end list --> - -1. In fact, it can be written in any language, but typically it's a - `bash` shell script. diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md index 9076033d7..1950c3121 100644 --- a/doc/manual/src/package-management/profiles.md +++ b/doc/manual/src/package-management/profiles.md @@ -10,12 +10,13 @@ in a directory `/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while another version might be stored in `/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long -strings prefixed to the directory names are cryptographic hashes\[1\] of -*all* inputs involved in building the package — sources, dependencies, -compiler flags, and so on. So if two packages differ in any way, they -end up in different locations in the file system, so they don’t -interfere with each other. Here is what a part of a typical Nix store -looks like: +strings prefixed to the directory names are cryptographic hashes (to be +precise, 160-bit truncations of SHA-256 hashes encoded in a base-32 +notation) of *all* inputs involved in building the package — sources, +dependencies, compiler flags, and so on. So if two packages differ in +any way, they end up in different locations in the file system, so they +don’t interfere with each other. Here is what a part of a typical Nix +store looks like:  @@ -113,6 +114,3 @@ All `nix-env` operations work on the profile pointed to by $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion This will *not* change the `~/.nix-profile` symlink. - -1. 160-bit truncations of SHA-256 hashes encoded in a base-32 notation, - to be precise. |