diff --git a/doc/manual/build-farm.xml b/doc/manual/build-farm.xml index b0d3fb8b6..dc27d1cff 100644 --- a/doc/manual/build-farm.xml +++ b/doc/manual/build-farm.xml @@ -56,7 +56,7 @@ url='https://svn.cs.uu.nl:12443/repos/trace/release/trunk' />. -
Setting up distributed builds +
Setting up distributed builds You can enable distributed builds by setting the environment variable NIX_BUILD_HOOK to point to a program that Nix diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index ac7b24c24..546c0efb3 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -822,9 +822,58 @@ set. Functions -TODO +Functions have the following form: -Higher-order functions; map + +{params}: body + +This defines a function that must be called with an attribute set +containing the attributes listed in params, +which is a comma-separated list of attribute names. Optionally, for +each parameter a default value may be specified +by writing param ? +e, where +e is an arbitrary expression. If a +parameter has a default, the corresponding attribute may be omitted in +function calls. + +Note that functions do not have names. If you want to give them +a name, you can bind them to an attribute, e.g., + + +let { + concat = {x, y}: x + y; + body = concat {x = "foo"; y = "bar";}; +} + + + +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. The syntax is + + +var: body + +where var is the name of the argument. It +is not possible to define a default. Example: + + +let { + negate = x: !x; + concat = x: y: x + y; + body = if negate true then concat "foo" "bar" else ""; +} + +Note that concat is a function that takes one +arguments and returns a function that takes another argument. This +allows partial parameterisation (i.e., only filling some of the +arguments of a function); e.g., + + + map (concat "foo") ["bar", "bla", "abc"] + +evaluates to ["foobar" "foobla" "fooabc"]. @@ -1059,7 +1108,157 @@ weakest binding). Derivations -TODO +The most important built-in function is +derivation, which is used to describe a +single derivation (a build action). It takes as input an attribute +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 + "powerpc-darwin"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. 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 .) + + There must be an attribute named + name whose value must be a string. This is used + as a symbolic name for the component by nix-env, + and it is appended to the hash in the output path of the + derivation. + + There must be an attribute named + builder that identifies the program that is + executed to perform the build. It can be either a derivation or a + source (a local file reference, e.g., + ./builder.sh). + + Every attribute is passed as an environment variable + to the builder. Attribute values are translated to environment + variables as follows: + + + + Strings, URIs, and integers are just passed + verbatim. + + A path (e.g., + ../foo/sources.tar) causes the referenced + file to be copied to the store; its location in the store is put + in the environment variable. The idea is that all sources + should reside in the Nix store, since all inputs to a derivation + should reside in the Nix store. + + A derivation causes that + derivation to be built prior to the present derivation; the + output path is put in the environment + variable. + + Lists of the previous types are also allowed. + They are simply concatenated, separated by + spaces. + + + + + + The optional argument args + specifies command-line arguments to be passed to the builder. It + should be a list. + + + +(Note that mkDerivation in the standard +environment is a wrapper around derivation that +adds a default value for system and always uses +Bash as the builder, to which the supplied builder is passed as a +command-line argument. See .) + +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. + + 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 this build. + + 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 + initialising it to their built-in default value. + + 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 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 directory (typically, + /nix/store). + + out is set to point to the output + path of the derivation, which is a subdirectory of the Nix store. + The output path is a concatenation of the cryptographic hash of + all build inputs, and the name + attribute. + + + + + + If the output path already exists, it is removed. + Also, locks are acquired to prevent multiple Nix instances from + performing the same build at the same time. + + A log of the combined standard output and error is + written to /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. + + 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 + 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 + should copy the retained dependencies as well. The scan is + performed by looking for the hash parts of file names of the + inputs. + + + +