diff options
Diffstat (limited to 'doc/manual/src/expressions')
| -rw-r--r-- | doc/manual/src/expressions/advanced-attributes.md | 14 | ||||
| -rw-r--r-- | doc/manual/src/expressions/build-script.md | 20 | ||||
| -rw-r--r-- | doc/manual/src/expressions/builder-syntax.md | 20 | ||||
| -rw-r--r-- | doc/manual/src/expressions/derivations.md | 16 | ||||
| -rw-r--r-- | doc/manual/src/expressions/generic-builder.md | 13 | ||||
| -rw-r--r-- | doc/manual/src/expressions/language-values.md | 4 | ||||
| -rw-r--r-- | doc/manual/src/expressions/simple-building-testing.md | 2 |
7 files changed, 45 insertions, 44 deletions
diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md index 683b504a7..01e18513d 100644 --- a/doc/manual/src/expressions/advanced-attributes.md +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -87,7 +87,7 @@ Derivations can declare some infrequently used optional attributes. impureEnvVars = [ "http_proxy" "https_proxy" ... ]; to make it use the proxy server configuration specified by the user - in the environment variables http\_proxy and friends. + in the environment variables `http_proxy` and friends. This attribute is only allowed in [fixed-output derivations](#fixed-output-drvs), where impurities such as these are @@ -201,15 +201,15 @@ Derivations can declare some infrequently used optional attributes. ``` - then when the builder runs, the environment variable bigPath will + then when the builder runs, the environment variable `bigPath` will contain the absolute path to a temporary file containing `a very long string`. That is, for any attribute x listed in `passAsFile`, Nix - will pass an environment variable xPath holding the path of the file - containing the value of attribute x. This is useful when you need to - pass large strings to a builder, since most operating systems impose - a limit on the size of the environment (typically, a few hundred - kilobyte). + will pass an environment variable `xPath` holding the path of the + file containing the value of attribute x. This is useful when you + need to pass large strings to a builder, since most operating + systems impose a limit on the size of the environment (typically, a + few hundred kilobyte). - `preferLocalBuild` If this attribute is set to `true` and [distributed building is diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md index 256a5cd44..a359ebc46 100644 --- a/doc/manual/src/expressions/build-script.md +++ b/doc/manual/src/expressions/build-script.md @@ -19,29 +19,29 @@ 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 + 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 + 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 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 + `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 `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 @@ -55,13 +55,13 @@ what a builder does. It performs the following steps: 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 + 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`). + 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 diff --git a/doc/manual/src/expressions/builder-syntax.md b/doc/manual/src/expressions/builder-syntax.md index c92acf106..916159d40 100644 --- a/doc/manual/src/expressions/builder-syntax.md +++ b/doc/manual/src/expressions/builder-syntax.md @@ -19,29 +19,29 @@ 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 + 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 + 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 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 + `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 `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 @@ -55,13 +55,13 @@ what a builder does. It performs the following steps: 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 + 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`). + 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 diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md index 7ffc6fabe..a4df20baa 100644 --- a/doc/manual/src/expressions/derivations.md +++ b/doc/manual/src/expressions/derivations.md @@ -83,32 +83,32 @@ as a command-line argument. See the Nixpkgs manual for details. The builder is executed as follows: - A temporary directory is created under the directory specified by - TMPDIR (default `/tmp`) where the build will take place. The current - directory is changed to this directory. + `TMPDIR` (default `/tmp`) where the build will take place. The + current directory is changed to this directory. - The environment is cleared and set to the derivation attributes, as specified above. - In addition, the following variables are set: - - NIX\_BUILD\_TOP contains the path of the temporary directory for + - `NIX_BUILD_TOP` contains the path of the temporary directory for this build. - - Also, TMPDIR, TEMPDIR, TMP, TEMP are set to point to the + - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the temporary directory. This is to prevent the builder from accidentally writing temporary files anywhere else. Doing so might cause interference by other processes. - - PATH is set to `/path-not-set` to prevent shells from + - `PATH` is set to `/path-not-set` to prevent shells from initialising it to their built-in default value. - - HOME is set to `/homeless-shelter` to prevent programs from + - `HOME` is set to `/homeless-shelter` to prevent programs from using `/etc/passwd` or the like to find the user's home - directory, which could cause impurity. Usually, when HOME is + directory, which could cause impurity. Usually, when `HOME` is set, it is used as the location of the home directory, even if it points to a non-existent path. - - NIX\_STORE is set to the path of the top-level Nix store + - `NIX_STORE` is set to the path of the top-level Nix store directory (typically, `/nix/store`). - For each output declared in `outputs`, the corresponding diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index cbc484199..a00b08b55 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -22,9 +22,9 @@ build facilities in shown in [example\_title](#ex-hello-builder2). genericBuild - - 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` + - 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\] @@ -37,7 +37,7 @@ build facilities in shown in [example\_title](#ex-hello-builder2). It can be customised in many ways; see the Nixpkgs manual for details. -Discerning readers will note that the buildInputs could just as well +Discerning readers will note that the `buildInputs` could just as well have been set in the Nix expression, like this: ``` @@ -57,5 +57,6 @@ 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. + 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-values.md b/doc/manual/src/expressions/language-values.md index 98ad97c97..fac0be47e 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -120,8 +120,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 will be searched for the given file - or directory name. + environment variable NIX\_PATH\</literal\> will be searched for the + given file or directory name. - *Booleans* with values `true` and `false`. diff --git a/doc/manual/src/expressions/simple-building-testing.md b/doc/manual/src/expressions/simple-building-testing.md index bc064c733..c3e8d7f82 100644 --- a/doc/manual/src/expressions/simple-building-testing.md +++ b/doc/manual/src/expressions/simple-building-testing.md @@ -32,7 +32,7 @@ of the build will be safely kept on your system. You can use Nix has transactional semantics. Once a build finishes successfully, Nix makes a note of this in its database: it registers that the path denoted -by out is now “valid”. If you try to build the derivation again, Nix +by `out` is now “valid”. If you try to build the derivation again, Nix will see that the path is already valid and finish immediately. If a build fails, either because it returns a non-zero exit code, because Nix or the builder are killed, or because the machine crashes, then the |