diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index fe014ffef..f9530dc4b 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -96,7 +96,7 @@ also . drvlink - + Add a symlink named drvlink to the store derivation produced by nix-instantiate. The derivation is @@ -108,14 +108,14 @@ also . - + Shorthand for ./derivation. - + - + Do not create a symlink to the output path. Note that as a result the output does not become a root of the garbage collector, and so might be deleted by nix-store @@ -125,7 +125,7 @@ also . / outlink - + Change the name of the symlink to the output path created from result to outlink. @@ -143,7 +143,7 @@ also . cmd - + In the environment of the derivation, executeq the command cmd instead of the default interactive shell. @@ -151,7 +151,7 @@ also . regexp - + Do not build any dependencies whose store path matches the regular expression regexp. This option may be specified multiple times. @@ -190,6 +190,25 @@ $ ./pan/gui/pan +If a derivation has multiple outputs, +nix-build will build the default (first) output. +You can also build all outputs: + +$ nix-build '<nixpkgs>' -A openssl.all + +This will create a symlink for each output named +result-outputname. +The suffix is omitted if the output name is out. +So if openssl has outputs out, +bin and man, +nix-build will create symlinks +result, result-bin and +result-man. It’s also possible to build a specific +output: + +$ nix-build '<nixpkgs>' -A openssl.man + +This will create a symlink result-man. @@ -201,6 +220,6 @@ $ ./pan/gui/pan - + diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 3c2d06eec..80e7fd037 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -106,7 +106,7 @@ the single Nix expression in that directory here, the entire remainder of the file is the body of the function; when given the required arguments, the body should describe how to build an instance of the Hello package. - + @@ -190,7 +190,7 @@ perl = perl; with the same name happen to be in scope. - + @@ -301,7 +301,7 @@ steps: (make install). - + If you are wondering about the absence of error checking on the @@ -321,7 +321,7 @@ error check. ... rec { - + hello = import ../applications/misc/hello/ex-1 { inherit fetchurl stdenv perl; }; @@ -330,10 +330,10 @@ rec { inherit fetchurl stdenv; }; - fetchurl = import ../build-support/fetchurl { + fetchurl = import ../build-support/fetchurl { inherit stdenv; ... }; - + stdenv = ...; } @@ -476,8 +476,8 @@ that the path denoted by out is now 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 output path will not be registered as valid. If you try to build -the derivation again, Nix will remove the output path if it exists +the output paths will not be registered as valid. If you try to build +the derivation again, Nix will remove the output paths if they exist (e.g., because the builder died half-way through make install) and try again. Note that there is no negative caching: Nix doesn't remember that a build @@ -543,7 +543,7 @@ genericBuild - + The buildInputs variable tells setup to use the indicated packages as inputs. This means that if a package provides a @@ -568,7 +568,7 @@ genericBuild the file $stdenv/setup. - + The final step calls the shell function @@ -580,7 +580,7 @@ genericBuild see . - + Discerning readers will note that the @@ -704,7 +704,7 @@ configureFlags = " the third line is indented three spaces. Thus, two spaces are stripped from each line, so the resulting string is - + "This is the first line.\nThis is the second line.\n This is the third line.\n" @@ -726,7 +726,7 @@ configureFlags = " linefeed, carriage-return and tab characters can be writted as ''\n, ''\r, ''\t. - + Indented strings are primarily useful in that they allow multi-line string literals to follow the indentation of the enclosing Nix expression, and that less escaping is typically @@ -745,7 +745,7 @@ stdenv.mkDerivation { ${if enableBar then "cp bar $out/bin" else ""} ''; ... -} +} @@ -781,7 +781,7 @@ stdenv.mkDerivation { Booleans with values true and false. - + @@ -931,7 +931,7 @@ propagate attributes). This can be shortened using the inherit keyword. For instance, -let x = 123; in +let x = 123; in { inherit x; y = 456; } @@ -982,7 +982,7 @@ argument. There are three kinds of patterns: - + If a pattern is a single identifier, then the function matches any argument. Example: @@ -1002,7 +1002,7 @@ map (concat "foo") [ "bar" "bla" "abc" ] evaluates to [ "foobar" "foobla" "fooabc" ]. - + An attribute set pattern of the form { name1, name2, …, nameN } matches an attribute set containing the listed attributes, and binds @@ -1016,7 +1016,7 @@ map (concat "foo") [ "bar" "bla" "abc" ] x, y and z. No other attributes are allowed. If you want to allow additional arguments, you can use an ellipsis - (...): + (...): { x, y, z, ... }: z + y + x @@ -1164,7 +1164,7 @@ used in the Nix expression for Subversion. - + With-expressions @@ -1343,7 +1343,7 @@ set, the attributes of which specify the inputs of the build. There must be an attribute named name whose value must be a string. This is used as a symbolic name for the package by nix-env, - and it is appended to the hash in the output path of the + and it is appended to the output paths of the derivation. There must be an attribute named @@ -1358,7 +1358,7 @@ set, the attributes of which specify the inputs of the build. - Strings, URIs, and integers are just passed + Strings and integers are just passed verbatim. A path (e.g., @@ -1369,8 +1369,8 @@ set, the attributes of which specify the inputs of the build. 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 + derivation to be built prior to the present derivation; its + default output path is put in the environment variable. Lists of the previous types are also allowed. @@ -1389,14 +1389,48 @@ set, the attributes of which specify the inputs of the build. specifies command-line arguments to be passed to the builder. It should be a list. + The optional attribute outputs + specifies a list of symbolic outputs of the derivation. By default, + a derivation produces a single output path, denoted as + out. However, derivations can produce multiple + output paths. This is useful because it allows outputs to be + downloaded or garbage-collected separately. For instance, imagine a + library package that provides a dynamic library, header files, and + documentation. A program that links against the library doesn’t + need the header files and documentation at runtime, and it doesn’t + need the documentation at build time. Thus, the library package + could specify: + +outputs = [ "lib" "headers" "doc" ]; + + This will cause Nix to pass environment variables + lib, headers and + doc to the builder containing the intended store + paths of each output. The builder would typically do something like + +./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc + + for an Autoconf-style package. You can refer to each output of a + derivation by selecting it as an attribute, e.g. + +buildInputs = [ pkg.lib pkg.headers ]; + + The first element of output determines the + default output. Thus, you could also write + +buildInputs = [ pkg pkg.headers ]; + + since pkg is equivalent to + pkg.lib. + -(Note that mkDerivation in the standard +The function 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: @@ -1440,17 +1474,19 @@ command-line argument. See /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. - + For each output declared in + outputs, the corresponding environment variable + is set to point to the intended path in the Nix store for that + output. Each output path is a concatenation of the cryptographic + hash of all build inputs, the name attribute + and the output name. (The output name is omitted if it’s + out.) + - If the output path already exists, it is removed. + If an 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. @@ -1464,14 +1500,11 @@ command-line argument. See The temporary directory is removed (unless the option was specified). - 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 - should copy the retained dependencies as well. The scan is - performed by looking for the hash parts of file names of the - inputs. + If the build was successful, Nix scans each output + path for references to input paths by looking for the hash parts of + the input paths. Since these are potential runtime dependencies, + Nix registers them as dependencies of the output + paths. After the build, Nix sets the last-modified timestamp on all files in the build result to 1 (00:00:01 1/1/1970 @@ -1497,7 +1530,7 @@ attributes. allowedReferences - + The optional attribute allowedReferences specifies a list of legal references (dependencies) of the output of the builder. For @@ -1515,7 +1548,7 @@ allowedReferences = []; - + exportReferencesGraph This attribute allows builders access to the @@ -1626,7 +1659,7 @@ stdenv.mkDerivation { outputHashMode = "flat"; outputHashAlgo = "md5"; outputHash = md5; - + inherit url; } @@ -1655,7 +1688,7 @@ stdenv.mkDerivation { This is the default. - + "recursive" The hash is computed over the NAR archive dump @@ -1676,10 +1709,10 @@ stdenv.mkDerivation { linkend="sec-nix-hash">nix-hash command for information about converting to and from base-32 notation.) - + - + impureEnvVars This attribute allows you to specify a list of @@ -1706,7 +1739,7 @@ impureEnvVars = [ "http_proxy" "https_proxy" ... ]; - + preferLocalBuild If this attribute is set to