diff --git a/doc/manual/build-farm.xml b/doc/manual/build-farm.xml index dc27d1cff..4745d205c 100644 --- a/doc/manual/build-farm.xml +++ b/doc/manual/build-farm.xml @@ -14,10 +14,10 @@ build farm, since: instance, if you perform a build for a powerpc-darwin on an i686-linux machine, Nix can automatically forward - to build to a powerpc-darwin machine, if + the build to a powerpc-darwin machine, if available. - The Nix expression language is ideal for providing + The Nix expression language is ideal for describing build jobs, plus all their dependencies. For instance, if your package has some dependency, you don't have to manually install it on all the machines in the build farm; they will be built @@ -26,9 +26,9 @@ build farm, since: Proper release management requires that builds (if deployed) are traceable: it should be possible to figure out from exactly what sources they were built, in what configuration, etc.; - and it should be possible to reproduce the build, if necessary. - Nix's hashing scheme uniquely identifies builds, and Nix expressions - are self-contained. + and it should be possible to reproduce the build, if necessary. Nix + makes this possible since Nix's hashing scheme uniquely identifies + builds, and Nix expressions are self-contained. Nix will only rebuild things that have actually changed. For instance, if the sources of a component haven't diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index d29f76f19..dae7d9073 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -83,9 +83,7 @@ the single Nix expression in that directory would expect in a basic Unix environment: a C/C++ compiler (GCC, to be precise), the Bash shell, fundamental Unix tools such as cp, grep, - tar, etc. (See - pkgs/stdenv/nix/path.nix to see what's in - stdenv.) fetchurl is a + tar, etc. fetchurl is a function that downloads files. perl is the Perl interpreter. @@ -109,12 +107,12 @@ the single Nix expression in that directory mkDerivation is a function provided by stdenv that builds a component from a set of attributes. An attribute set is just a list - of key/value pairs where the value is an arbitrary Nix expression. - They take the general form + of key/value pairs where each value is an arbitrary Nix + expression. They take the general form {name1 = expr1; ... - name1 = - expr1;. + nameN = + exprN;}. @@ -148,11 +146,11 @@ the single Nix expression in that directory The builder has to know what the sources of the component are. Here, the attribute src is bound to the result of a call to the fetchurl function. - Given a URL and a MD5 hash of the expected contents of the file at - that URL, this function actually builds a derivation that - downloads the file and checks its hash. So the sources are a - dependency that like all other dependencies is built before Hello - itself is built. + Given a URL and an MD5 hash of the expected contents of the file + at that URL, this function builds a derivation that downloads the + file and checks its hash. So the sources are a dependency that + like all other dependencies is built before Hello itself is + built. Instead of src any other name could have been used, and in fact there can be any number of sources (bound @@ -172,7 +170,7 @@ the single Nix expression in that directory perl = perl; - will do the trink: it binds an attribute perl + will do the trick: it binds an attribute perl to the function argument which also happens to be called perl. However, it looks a bit silly, so there is a shorter syntax. The inherit keyword @@ -218,7 +216,8 @@ steps: When Nix runs a builder, it initially completely clears the - environment. For instance, the PATH variable is + environment (except for the attributes declared in the + derivation). For instance, the PATH variable is emptyActually, it's initialised to /path-not-set to prevent Bash from setting it to a default value.. This is done to prevent @@ -596,13 +595,11 @@ language. Purity means that operations in the language don't have side-effects (for instance, there is no variable assignment). Laziness means that arguments to functions are evaluated only when they are needed. Functional means that functions are -normal values that can be passed around and -manipulated in interesting ways. - -The language is not a full-featured, general purpose language. -It's main job is to describe components, compositions of components, -and the variability within components. For this a functional language -is perfectly suited. +normal values that can be passed around and manipulated +in interesting ways. The language is not a full-featured, general +purpose language. It's main job is to describe components, +compositions of components, and the variability within +components. This section presents the various features of the language. @@ -773,7 +770,7 @@ and evaluates to "foobar". Inheriting attributes -When defining an attribute set itt is often convenient to copy +When defining an attribute set it is often convenient to copy variables from the surrounding lexical scope (e.g., when you want to propagate attributes). This can be shortened using the inherit keyword. For instance, @@ -849,7 +846,7 @@ let { It is also possible to define a function that takes a single -argument and that does need to be called with an attribute set as +argument and that does not need to be called with an attribute set as argument. The syntax is @@ -959,10 +956,10 @@ used in the Nix expression for Subversion. This assertion says that in order for Subversion to have SSL support (so that it can access https URLs), an - OpenSSL library must be passed. Additionally, it says + OpenSSL library must be passed. Additionally, it says that if Apache support is enabled, then Apache's - OpenSSL should much Subversion's. (Note that if Apache support is - not enabled, we don't care about Apache's OpenSSL.) + OpenSSL should match Subversion's. (Note that if Apache support + is not enabled, we don't care about Apache's OpenSSL.) @@ -1241,14 +1238,14 @@ command-line argument. See /nix/var/log/nix. The builder is executed with the arguments specified - by the attribute args. If it exit with exit code - 0, it is considered to have succeeded. + by the attribute args. If it exits with exit + code 0, it is considered to have succeeded. The temporary directory is removed (unless the option was specified). - If the build was succesful, Nix scans the output for - references to the paths of the inputs. These so-called + If the build was successful, Nix scans the output + for references to the paths of the inputs. These so-called retained dependencies could be used when the output of the derivation is used (e.g., when it's executed or used as input to another derivation), so if we deploy the derivation, we @@ -1406,7 +1403,7 @@ variable. The phases are: - unpackPhase: unpacks the source files + unpackPhase unpacks the source files listed in the src environment variable to the current directory. It supports tar files, optionally compressed with gzip or @@ -1415,7 +1412,7 @@ variable. The phases are: environment; you should add it as a build input yourself); and unpacked source trees (i.e., directories; they are copied verbatim). You can add support for other file types by setting - the findUnpacker hook. This hook should set an + the findUnpacker hook. This hook should set the variable unpackCmd to contain the command to be executed to unpack the file. @@ -1441,7 +1438,7 @@ variable. The phases are: configurePhase runs the script called configure in the current directory with a set to the output path. You can add - additional flag through the configureFlags + additional flags through the configureFlags variable. If configure does not exist, nothing happens.