diff options
Diffstat (limited to 'doc/manual/writing-nix-expressions.xml')
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 129 |
1 files changed, 81 insertions, 48 deletions
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 3c2d06eec42f..80e7fd03748a 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.</para> - + </callout> <callout arearefs='ex-hello-nix-co-2'> @@ -190,7 +190,7 @@ perl = perl;</programlisting> with the same name happen to be in scope.</para> </callout> - + </calloutlist> </para> @@ -301,7 +301,7 @@ steps:</para> (<literal>make install</literal>).</para> </callout> - + </calloutlist> <para>If you are wondering about the absence of error checking on the @@ -321,7 +321,7 @@ error check.</para> ... rec { <co xml:id='ex-hello-composition-co-1' /> - + hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' /> inherit fetchurl stdenv perl; }; @@ -330,10 +330,10 @@ rec { <co xml:id='ex-hello-composition-co-1' /> 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 <envar>out</envar> 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 <literal>make install</literal>) and try again. Note that there is no <quote>negative caching</quote>: Nix doesn't remember that a build @@ -543,7 +543,7 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> <calloutlist> <callout arearefs='ex-hello-builder2-co-1'> - + <para>The <envar>buildInputs</envar> variable tells <filename>setup</filename> to use the indicated packages as <quote>inputs</quote>. This means that if a package provides a @@ -568,7 +568,7 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> the file <literal>$stdenv/setup</literal>.</para> </callout> - + <callout arearefs='ex-hello-builder2-co-3'> <para>The final step calls the shell function @@ -580,7 +580,7 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> see <xref linkend='sec-standard-environment' />.</para> </callout> - + </calloutlist> <para>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 -<programlisting> +<programlisting> "This is the first line.\nThis is the second line.\n This is the third line.\n"</programlisting> </para> @@ -726,7 +726,7 @@ configureFlags = " linefeed, carriage-return and tab characters can be writted as <literal>''\n</literal>, <literal>''\r</literal>, <literal>''\t</literal>.</para> - + <para>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 ""} ''; <replaceable>...</replaceable> -} +} </programlisting> </para> @@ -781,7 +781,7 @@ stdenv.mkDerivation { <listitem><para><emphasis>Booleans</emphasis> with values <literal>true</literal> and <literal>false</literal>.</para></listitem> - + </itemizedlist> </para> @@ -931,7 +931,7 @@ propagate attributes). This can be shortened using the <literal>inherit</literal> keyword. For instance, <programlisting> -let x = 123; in +let x = 123; in { inherit x; y = 456; }</programlisting> @@ -982,7 +982,7 @@ argument. There are three kinds of patterns:</para> <itemizedlist> - + <listitem><para>If a pattern is a single identifier, then the function matches any argument. Example: @@ -1002,7 +1002,7 @@ map (concat "foo") [ "bar" "bla" "abc" ]</programlisting> evaluates to <literal>[ "foobar" "foobla" "fooabc" ]</literal>.</para></listitem> - + <listitem><para>An <emphasis>attribute set pattern</emphasis> of the form <literal>{ name1, name2, …, nameN }</literal> matches an attribute set containing the listed attributes, and binds @@ -1016,7 +1016,7 @@ map (concat "foo") [ "bar" "bla" "abc" ]</programlisting> <varname>x</varname>, <varname>y</varname> and <varname>z</varname>. No other attributes are allowed. If you want to allow additional arguments, you can use an ellipsis - (<literal>...</literal>): + (<literal>...</literal>): <programlisting> { x, y, z, ... }: z + y + x</programlisting> @@ -1164,7 +1164,7 @@ used in the Nix expression for Subversion.</para> </calloutlist> </simplesect> - + <simplesect><title>With-expressions</title> @@ -1343,7 +1343,7 @@ set, the attributes of which specify the inputs of the build.</para> <listitem><para>There must be an attribute named <varname>name</varname> whose value must be a string. This is used as a symbolic name for the package by <command>nix-env</command>, - and it is appended to the hash in the output path of the + and it is appended to the output paths of the derivation.</para></listitem> <listitem><para>There must be an attribute named @@ -1358,7 +1358,7 @@ set, the attributes of which specify the inputs of the build.</para> <itemizedlist> - <listitem><para>Strings, URIs, and integers are just passed + <listitem><para>Strings and integers are just passed verbatim.</para></listitem> <listitem><para>A <emphasis>path</emphasis> (e.g., @@ -1369,8 +1369,8 @@ set, the attributes of which specify the inputs of the build.</para> should reside in the Nix store.</para></listitem> <listitem><para>A <emphasis>derivation</emphasis> 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.</para></listitem> <listitem><para>Lists of the previous types are also allowed. @@ -1389,14 +1389,48 @@ set, the attributes of which specify the inputs of the build.</para> specifies command-line arguments to be passed to the builder. It should be a list.</para></listitem> + <listitem><para>The optional attribute <varname>outputs</varname> + specifies a list of symbolic outputs of the derivation. By default, + a derivation produces a single output path, denoted as + <literal>out</literal>. 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: +<programlisting> +outputs = [ "lib" "headers" "doc" ]; +</programlisting> + This will cause Nix to pass environment variables + <literal>lib</literal>, <literal>headers</literal> and + <literal>doc</literal> to the builder containing the intended store + paths of each output. The builder would typically do something like +<programlisting> +./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc +</programlisting> + for an Autoconf-style package. You can refer to each output of a + derivation by selecting it as an attribute, e.g. +<programlisting> +buildInputs = [ pkg.lib pkg.headers ]; +</programlisting> + The first element of <varname>output</varname> determines the + <emphasis>default output</emphasis>. Thus, you could also write +<programlisting> +buildInputs = [ pkg pkg.headers ]; +</programlisting> + since <literal>pkg</literal> is equivalent to + <literal>pkg.lib</literal>.</para></listitem> + </itemizedlist> -<para>(Note that <function>mkDerivation</function> in the standard +<para>The function <function>mkDerivation</function> in the standard environment is a wrapper around <function>derivation</function> that adds a default value for <varname>system</varname> and always uses Bash as the builder, to which the supplied builder is passed as a command-line argument. See <xref linkend='sec-standard-environment' -/>.)</para> +/>.</para> <para>The builder is executed as follows: @@ -1440,17 +1474,19 @@ command-line argument. See <xref linkend='sec-standard-environment' top-level Nix store directory (typically, <filename>/nix/store</filename>).</para></listitem> - <listitem><para><envar>out</envar> 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 <varname>name</varname> - attribute.</para></listitem> - + <listitem><para>For each output declared in + <varname>outputs</varname>, 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 <varname>name</varname> attribute + and the output name. (The output name is omitted if it’s + <literal>out</literal>.)</para></listitem> + </itemizedlist> </para></listitem> - <listitem><para>If the output path already exists, it is removed. + <listitem><para>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.</para></listitem> @@ -1464,14 +1500,11 @@ command-line argument. See <xref linkend='sec-standard-environment' <listitem><para>The temporary directory is removed (unless the <option>-K</option> option was specified).</para></listitem> - <listitem><para>If the build was successful, Nix scans the output - for references to the paths of the inputs. These so-called - <emphasis>retained dependencies</emphasis> 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.</para></listitem> + <listitem><para>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.</para></listitem> <listitem><para>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.</para> <variablelist> <varlistentry><term><varname>allowedReferences</varname></term> - + <listitem><para>The optional attribute <varname>allowedReferences</varname> specifies a list of legal references (dependencies) of the output of the builder. For @@ -1515,7 +1548,7 @@ allowedReferences = []; </varlistentry> - + <varlistentry><term><varname>exportReferencesGraph</varname></term> <listitem><para>This attribute allows builders access to the @@ -1626,7 +1659,7 @@ stdenv.mkDerivation { outputHashMode = "flat"; outputHashAlgo = "md5"; outputHash = md5; - + inherit url; } </programlisting> @@ -1655,7 +1688,7 @@ stdenv.mkDerivation { <para>This is the default.</para></listitem> </varlistentry> - + <varlistentry><term><literal>"recursive"</literal></term> <listitem><para>The hash is computed over the NAR archive dump @@ -1676,10 +1709,10 @@ stdenv.mkDerivation { linkend="sec-nix-hash"><command>nix-hash</command> command</link> for information about converting to and from base-32 notation.)</para></listitem> - + </varlistentry> - + <varlistentry><term><varname>impureEnvVars</varname></term> <listitem><para>This attribute allows you to specify a list of @@ -1706,7 +1739,7 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; </varlistentry> - + <varlistentry><term><varname>preferLocalBuild</varname></term> <listitem><para>If this attribute is set to |