diff --git a/doc/manual/builtins.xml b/doc/manual/builtins.xml index 1ce40a607..b6c886199 100644 --- a/doc/manual/builtins.xml +++ b/doc/manual/builtins.xml @@ -17,7 +17,7 @@ functions and values. For instance, derivation is also available as builtins.derivation. - + abort s diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml index 46c540b87..727a3e4a6 100644 --- a/doc/manual/release-notes.xml +++ b/doc/manual/release-notes.xml @@ -38,9 +38,13 @@ paths. - TODO: allowedReferences for - checking the set of references in the output of a - derivation. + Derivations can specify the new special attribute + allowedReferences to enforce that the references + in the output of a derivation are a subset of a declared set of + paths. For example, if allowedReferences is an + empty list, then the output must not have any references. This is + used in NixOS to check that generated files such as initial ramdisks + for booting Linux don’t have any dependencies. TODO: semantic cleanups of string concatenation @@ -54,8 +58,11 @@ nix-store --register-validity. - TODO: magic exportReferencesGraph - attribute. + The new attribute + exportReferencesGraph allows builders access to + the references graph of their inputs. This is used in NixOS for + tasks such as generating ISO-9660 images that contain a Nix store + populated with the closure of certain paths. TODO: option , @@ -109,8 +116,10 @@ disambiguation (nix-env -qaA). - TODO: substitutes table is gone, registering - substitutes is now much faster. + The substitutes table has been removed from the + database. This makes operations such as nix-pull + and nix-channel --update + much faster. nix-prefetch-url now has a diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index c4bc35cc7..5fa9e423d 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -607,7 +607,7 @@ language. Simple values -Nix has the following basic datatypes: +Nix has the following basic data types: @@ -679,7 +679,7 @@ configureFlags = " instance, builder.sh is not a pathIt's parsed as an expression that selects the attribute sh from the variable - builder.. If the filename is + 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 @@ -701,7 +701,7 @@ configureFlags = " Lists Lists are formed by enclosing a whitespace-separated list of -values between square bracktes. For example, +values between square brackets. For example, [ 123 ./foo.nix "abc" (f {x=y;}) ] @@ -927,7 +927,7 @@ evaluates to ["foobar" "foobla" "fooabc"]. if e1 then e2 else e3 where e1 is an expression that should -evaluate to a boolean value (true or +evaluate to a Boolean value (true or false). @@ -942,7 +942,7 @@ on or between features and dependencies hold. They look like this: assert e1; e2 where e1 is an expression that should -evaluate to a boolean value. If it evaluates to +evaluate to a Boolean value. If it evaluates to true, e2 is returned; otherwise expression evaluation is aborted and a backtrace is printed. @@ -1234,7 +1234,7 @@ set, the attributes of which specify the inputs of the build. - The optional argument args + The optional attribute args specifies command-line arguments to be passed to the builder. It should be a list. @@ -1337,6 +1337,233 @@ command-line argument. See + +
Advanced attributes + +Derivations can declare some infrequently used optional +attributes. + + + + allowedReferences + + The optional attribute + allowedReferences specifies a list of legal + references (dependencies) of the output of the builder. For + example, + + +allowedReferences = []; + + + enforces that the output of a derivation cannot have any runtime + dependencies on its inputs. This is used in NixOS to check that + generated files such as initial ramdisks for booting Linux don’t + have accidental dependencies on other paths in the Nix + store. + + + + + exportReferencesGraph + + This attribute allows builders access to the + references graph of their inputs. The attribute is a list of + inputs in the Nix store whose references graph the builder needs + to know. The value of this attribute should be a list of pairs + [name1 + path1 name2 + path2 + ...]. The references graph + of each pathN will be stored in a text + file nameN in the temporary build + directory. The text files have the format used by + nix-store --register-validity (with the deriver + fields left empty). For example, when the following derivation is + built: + + +derivation { + ... + exportReferencesGraph = ["libfoo-graph" libfoo]; +}; + + + the references graph of libfoo is placed in the + file libfoo-graph in the temporary build + directory. + + exportReferencesGraph is useful for + builders that want to do something with the closure of a store + path. Examples include the builders in NixOS that generate the + initial ramdisk for booting Linux (a cpio + archive containing the closure of the boot script) and the + ISO-9660 image for the installation CD (which is populated with a + Nix store containing the closure of a bootable NixOS + configuration). + + + + + + outputHash + outputHashAlgo + outputHashMode + + These attributes declare that the derivation is a + so-called fixed-output derivation, which + means that a cryptographic hash of the output is already known in + advance. When the build of a fixed-output derivation finishes, + Nix computes the cryptographic hash of the output and compares it + to the hash declared with these attributes. If there is a + mismatch, the build fails. + + The rationale for fixed-output derivations is derivations + such as those produced by the fetchurl + function. This function downloads a file from a given URL. To + ensure that the downloaded file has not been modified, the caller + must also specify a cryptographic hash of the file. For example, + + +fetchurl { + url = http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; +} + + + It sometimes happens that the URL of the file changes, e.g., + because servers are reorganised or no longer available. We then + must update the call to fetchurl, e.g., + + +fetchurl { + url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; +} + + + If a fetchurl derivation was treated like a + normal derivation, the output paths of the derivation and + all derivations depending on it would change. + For instance, if we were to change the URL of the Glibc source + distribution in Nixpkgs (a package on which almost all other + packages depend) massive rebuilds would be needed. This is + unfortunate for a change which we know cannot have a real effect + as it propagates upwards through the dependency graph. + + For fixed-output derivations, on the other hand, the name of + the output path only depends on the outputHash* + and name attributes, while all other attributes + are ignored for the purpose of computing the output path. (The + name attribute is included because it is part + of the path.) + + As an example, here is the (simplified) Nix expression for + fetchurl: + + +{stdenv, curl}: # The curl program is used for downloading. + +{url, md5}: + +stdenv.mkDerivation { + name = baseNameOf (toString url); + builder = ./builder.sh; + buildInputs = [curl]; + + # This is a fixed-output derivation; the output must be a regular + # file with MD5 hash md5. + outputHashMode = "flat"; + outputHashAlgo = "md5"; + outputHash = md5; + + inherit url; +} + + + + + The outputHashAlgo attribute specifies + the hash algorithm used to compute the hash. It can currently be + "md5", "sha1" or + "sha256". + + The outputHashMode attribute determines + how the hash is computed. It must be one of the following two + values: + + + + "flat" + + The output must be a non-executable regular + file. If it isn’t, the build fails. The hash is simply + computed over the contents of that file (so it’s equal to what + Unix commands like md5sum or + sha1sum produce). + + This is the default. + + + + "recursive" + + The hash is computed over the NAR archive dump + of the output (i.e., the result of nix-store + --dump). In this case, the output can be + anything, including a directory tree. + + + + + + + + The outputHash attribute, finally, must + be a string containing the hash in either hexadecimal or base-32 + notation. (See the nix-hash command + for information about converting to and from base-32 + notation.) + + + + + impureEnvVars + + This attribute allows you to specify a list of + environment variables that should be passed from the environment + of the calling user to the builder. Usually, the environment is + cleared completely when the builder is executed, but with this + attribute you can allow specific environment variables to be + passed unmodified. For example, fetchurl in + Nixpkgs has the line + + +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. + + This attribute is only allowed in fixed-output derivations, where + impurities such as these are okay since (the hash of) the output + is known in advance. It is ignored for all other + derivations. + + + + + + + + +
+ +