Document multiple output support

This commit is contained in:
Eelco Dolstra 2012-12-04 16:03:56 +01:00
parent b215b23e9e
commit 24d5875514
2 changed files with 108 additions and 56 deletions

View file

@ -96,7 +96,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
<variablelist> <variablelist>
<varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term> <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
<listitem><para>Add a symlink named <listitem><para>Add a symlink named
<replaceable>drvlink</replaceable> to the store derivation <replaceable>drvlink</replaceable> to the store derivation
produced by <command>nix-instantiate</command>. The derivation is produced by <command>nix-instantiate</command>. The derivation is
@ -108,14 +108,14 @@ also <xref linkend="sec-common-options" />.</phrase></para>
</varlistentry> </varlistentry>
<varlistentry><term><option>--add-drv-link</option></term> <varlistentry><term><option>--add-drv-link</option></term>
<listitem><para>Shorthand for <option>--drv-link</option> <listitem><para>Shorthand for <option>--drv-link</option>
<filename>./derivation</filename>.</para></listitem> <filename>./derivation</filename>.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry><term><option>--no-out-link</option></term> <varlistentry><term><option>--no-out-link</option></term>
<listitem><para>Do not create a symlink to the output path. Note <listitem><para>Do not create a symlink to the output path. Note
that as a result the output does not become a root of the garbage that as a result the output does not become a root of the garbage
collector, and so might be deleted by <command>nix-store collector, and so might be deleted by <command>nix-store
@ -125,7 +125,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
<varlistentry xml:id='opt-out-link'><term><option>--out-link</option> / <varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
<option>-o</option> <replaceable>outlink</replaceable></term> <option>-o</option> <replaceable>outlink</replaceable></term>
<listitem><para>Change the name of the symlink to the output path <listitem><para>Change the name of the symlink to the output path
created from <filename>result</filename> to created from <filename>result</filename> to
<replaceable>outlink</replaceable>.</para></listitem> <replaceable>outlink</replaceable>.</para></listitem>
@ -143,7 +143,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
<variablelist> <variablelist>
<varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
<listitem><para>In the environment of the derivation, executeq the <listitem><para>In the environment of the derivation, executeq the
command <replaceable>cmd</replaceable> instead of the default command <replaceable>cmd</replaceable> instead of the default
interactive shell.</para></listitem> interactive shell.</para></listitem>
@ -151,7 +151,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
</varlistentry> </varlistentry>
<varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term> <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>
<listitem><para>Do not build any dependencies whose store path <listitem><para>Do not build any dependencies whose store path
matches the regular expression <replaceable>regexp</replaceable>. matches the regular expression <replaceable>regexp</replaceable>.
This option may be specified multiple times.</para></listitem> This option may be specified multiple times.</para></listitem>
@ -190,6 +190,25 @@ $ ./pan/gui/pan
</para> </para>
<para>If a derivation has multiple outputs,
<command>nix-build</command> will build the default (first) output.
You can also build all outputs:
<screen>
$ nix-build '&lt;nixpkgs>' -A openssl.all
</screen>
This will create a symlink for each output named
<filename>result-<replaceable>outputname</replaceable></filename>.
The suffix is omitted if the output name is <literal>out</literal>.
So if <literal>openssl</literal> has outputs <literal>out</literal>,
<literal>bin</literal> and <literal>man</literal>,
<command>nix-build</command> will create symlinks
<literal>result</literal>, <literal>result-bin</literal> and
<literal>result-man</literal>. Its also possible to build a specific
output:
<screen>
$ nix-build '&lt;nixpkgs>' -A openssl.man
</screen>
This will create a symlink <literal>result-man</literal>.</para>
</refsection> </refsection>
@ -201,6 +220,6 @@ $ ./pan/gui/pan
</variablelist> </variablelist>
</refsection> </refsection>
</refentry> </refentry>

View file

@ -106,7 +106,7 @@ the single Nix expression in that directory
here, the entire remainder of the file is the body of the here, the entire remainder of the file is the body of the
function; when given the required arguments, the body should function; when given the required arguments, the body should
describe how to build an instance of the Hello package.</para> describe how to build an instance of the Hello package.</para>
</callout> </callout>
<callout arearefs='ex-hello-nix-co-2'> <callout arearefs='ex-hello-nix-co-2'>
@ -190,7 +190,7 @@ perl = perl;</programlisting>
with the same name happen to be in scope.</para> with the same name happen to be in scope.</para>
</callout> </callout>
</calloutlist> </calloutlist>
</para> </para>
@ -301,7 +301,7 @@ steps:</para>
(<literal>make install</literal>).</para> (<literal>make install</literal>).</para>
</callout> </callout>
</calloutlist> </calloutlist>
<para>If you are wondering about the absence of error checking on the <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' /> 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' /> 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; inherit fetchurl stdenv perl;
}; };
@ -330,10 +330,10 @@ rec { <co xml:id='ex-hello-composition-co-1' />
inherit fetchurl stdenv; inherit fetchurl stdenv;
}; };
fetchurl = import ../build-support/fetchurl { fetchurl = import ../build-support/fetchurl {
inherit stdenv; ... inherit stdenv; ...
}; };
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 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 build fails, either because it returns a non-zero exit code, because
Nix or the builder are killed, or because the machine crashes, then 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 output paths will not be registered as valid. If you try to build
the derivation again, Nix will remove the output path if it exists the derivation again, Nix will remove the output paths if they exist
(e.g., because the builder died half-way through <literal>make (e.g., because the builder died half-way through <literal>make
install</literal>) and try again. Note that there is no install</literal>) and try again. Note that there is no
<quote>negative caching</quote>: Nix doesn't remember that a build <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> <calloutlist>
<callout arearefs='ex-hello-builder2-co-1'> <callout arearefs='ex-hello-builder2-co-1'>
<para>The <envar>buildInputs</envar> variable tells <para>The <envar>buildInputs</envar> variable tells
<filename>setup</filename> to use the indicated packages as <filename>setup</filename> to use the indicated packages as
<quote>inputs</quote>. This means that if a package provides a <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> the file <literal>$stdenv/setup</literal>.</para>
</callout> </callout>
<callout arearefs='ex-hello-builder2-co-3'> <callout arearefs='ex-hello-builder2-co-3'>
<para>The final step calls the shell function <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> see <xref linkend='sec-standard-environment' />.</para>
</callout> </callout>
</calloutlist> </calloutlist>
<para>Discerning readers will note that the <para>Discerning readers will note that the
@ -704,7 +704,7 @@ configureFlags = "
the third line is indented three spaces. Thus, two spaces are the third line is indented three spaces. Thus, two spaces are
stripped from each line, so the resulting string is 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> "This is the first line.\nThis is the second line.\n This is the third line.\n"</programlisting>
</para> </para>
@ -726,7 +726,7 @@ configureFlags = "
linefeed, carriage-return and tab characters can be writted as linefeed, carriage-return and tab characters can be writted as
<literal>''\n</literal>, <literal>''\r</literal>, <literal>''\n</literal>, <literal>''\r</literal>,
<literal>''\t</literal>.</para> <literal>''\t</literal>.</para>
<para>Indented strings are primarily useful in that they allow <para>Indented strings are primarily useful in that they allow
multi-line string literals to follow the indentation of the multi-line string literals to follow the indentation of the
enclosing Nix expression, and that less escaping is typically enclosing Nix expression, and that less escaping is typically
@ -745,7 +745,7 @@ stdenv.mkDerivation {
${if enableBar then "cp bar $out/bin" else ""} ${if enableBar then "cp bar $out/bin" else ""}
''; '';
<replaceable>...</replaceable> <replaceable>...</replaceable>
} }
</programlisting> </programlisting>
</para> </para>
@ -781,7 +781,7 @@ stdenv.mkDerivation {
<listitem><para><emphasis>Booleans</emphasis> with values <listitem><para><emphasis>Booleans</emphasis> with values
<literal>true</literal> and <literal>true</literal> and
<literal>false</literal>.</para></listitem> <literal>false</literal>.</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -931,7 +931,7 @@ propagate attributes). This can be shortened using the
<literal>inherit</literal> keyword. For instance, <literal>inherit</literal> keyword. For instance,
<programlisting> <programlisting>
let x = 123; in let x = 123; in
{ inherit x; { inherit x;
y = 456; y = 456;
}</programlisting> }</programlisting>
@ -982,7 +982,7 @@ argument. There are three kinds of patterns:</para>
<itemizedlist> <itemizedlist>
<listitem><para>If a pattern is a single identifier, then the <listitem><para>If a pattern is a single identifier, then the
function matches any argument. Example: function matches any argument. Example:
@ -1002,7 +1002,7 @@ map (concat "foo") [ "bar" "bla" "abc" ]</programlisting>
evaluates to <literal>[ "foobar" "foobla" evaluates to <literal>[ "foobar" "foobla"
"fooabc" ]</literal>.</para></listitem> "fooabc" ]</literal>.</para></listitem>
<listitem><para>An <emphasis>attribute set pattern</emphasis> of the <listitem><para>An <emphasis>attribute set pattern</emphasis> of the
form <literal>{ name1, name2, …, nameN }</literal> form <literal>{ name1, name2, …, nameN }</literal>
matches an attribute set containing the listed attributes, and binds 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>x</varname>, <varname>y</varname> and
<varname>z</varname>. No other attributes are allowed. If you want <varname>z</varname>. No other attributes are allowed. If you want
to allow additional arguments, you can use an ellipsis to allow additional arguments, you can use an ellipsis
(<literal>...</literal>): (<literal>...</literal>):
<programlisting> <programlisting>
{ x, y, z, ... }: z + y + x</programlisting> { x, y, z, ... }: z + y + x</programlisting>
@ -1164,7 +1164,7 @@ used in the Nix expression for Subversion.</para>
</calloutlist> </calloutlist>
</simplesect> </simplesect>
<simplesect><title>With-expressions</title> <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 <listitem><para>There must be an attribute named
<varname>name</varname> whose value must be a string. This is used <varname>name</varname> whose value must be a string. This is used
as a symbolic name for the package by <command>nix-env</command>, 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> derivation.</para></listitem>
<listitem><para>There must be an attribute named <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> <itemizedlist>
<listitem><para>Strings, URIs, and integers are just passed <listitem><para>Strings and integers are just passed
verbatim.</para></listitem> verbatim.</para></listitem>
<listitem><para>A <emphasis>path</emphasis> (e.g., <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> should reside in the Nix store.</para></listitem>
<listitem><para>A <emphasis>derivation</emphasis> causes that <listitem><para>A <emphasis>derivation</emphasis> causes that
derivation to be built prior to the present derivation; the derivation to be built prior to the present derivation; its
output path is put in the environment default output path is put in the environment
variable.</para></listitem> variable.</para></listitem>
<listitem><para>Lists of the previous types are also allowed. <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 specifies command-line arguments to be passed to the builder. It
should be a list.</para></listitem> 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 doesnt
need the header files and documentation at runtime, and it doesnt
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> </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 environment is a wrapper around <function>derivation</function> that
adds a default value for <varname>system</varname> and always uses adds a default value for <varname>system</varname> and always uses
Bash as the builder, to which the supplied builder is passed as a Bash as the builder, to which the supplied builder is passed as a
command-line argument. See <xref linkend='sec-standard-environment' command-line argument. See <xref linkend='sec-standard-environment'
/>.)</para> />.</para>
<para>The builder is executed as follows: <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, top-level Nix store directory (typically,
<filename>/nix/store</filename>).</para></listitem> <filename>/nix/store</filename>).</para></listitem>
<listitem><para><envar>out</envar> is set to point to the output <listitem><para>For each output declared in
path of the derivation, which is a subdirectory of the Nix store. <varname>outputs</varname>, the corresponding environment variable
The output path is a concatenation of the cryptographic hash of is set to point to the intended path in the Nix store for that
all build inputs, and the <varname>name</varname> output. Each output path is a concatenation of the cryptographic
attribute.</para></listitem> hash of all build inputs, the <varname>name</varname> attribute
and the output name. (The output name is omitted if its
<literal>out</literal>.)</para></listitem>
</itemizedlist> </itemizedlist>
</para></listitem> </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 Also, locks are acquired to prevent multiple Nix instances from
performing the same build at the same time.</para></listitem> 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 <listitem><para>The temporary directory is removed (unless the
<option>-K</option> option was specified).</para></listitem> <option>-K</option> option was specified).</para></listitem>
<listitem><para>If the build was successful, Nix scans the output <listitem><para>If the build was successful, Nix scans each output
for references to the paths of the inputs. These so-called path for references to input paths by looking for the hash parts of
<emphasis>retained dependencies</emphasis> could be used when the the input paths. Since these are potential runtime dependencies,
output of the derivation is used (e.g., when it's executed or used Nix registers them as dependencies of the output
as input to another derivation), so if we deploy the derivation, we paths.</para></listitem>
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>After the build, Nix sets the last-modified <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 timestamp on all files in the build result to 1 (00:00:01 1/1/1970
@ -1497,7 +1530,7 @@ attributes.</para>
<variablelist> <variablelist>
<varlistentry><term><varname>allowedReferences</varname></term> <varlistentry><term><varname>allowedReferences</varname></term>
<listitem><para>The optional attribute <listitem><para>The optional attribute
<varname>allowedReferences</varname> specifies a list of legal <varname>allowedReferences</varname> specifies a list of legal
references (dependencies) of the output of the builder. For references (dependencies) of the output of the builder. For
@ -1515,7 +1548,7 @@ allowedReferences = [];
</varlistentry> </varlistentry>
<varlistentry><term><varname>exportReferencesGraph</varname></term> <varlistentry><term><varname>exportReferencesGraph</varname></term>
<listitem><para>This attribute allows builders access to the <listitem><para>This attribute allows builders access to the
@ -1626,7 +1659,7 @@ stdenv.mkDerivation {
outputHashMode = "flat"; outputHashMode = "flat";
outputHashAlgo = "md5"; outputHashAlgo = "md5";
outputHash = md5; outputHash = md5;
inherit url; inherit url;
} }
</programlisting> </programlisting>
@ -1655,7 +1688,7 @@ stdenv.mkDerivation {
<para>This is the default.</para></listitem> <para>This is the default.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry><term><literal>"recursive"</literal></term> <varlistentry><term><literal>"recursive"</literal></term>
<listitem><para>The hash is computed over the NAR archive dump <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> linkend="sec-nix-hash"><command>nix-hash</command> command</link>
for information about converting to and from base-32 for information about converting to and from base-32
notation.)</para></listitem> notation.)</para></listitem>
</varlistentry> </varlistentry>
<varlistentry><term><varname>impureEnvVars</varname></term> <varlistentry><term><varname>impureEnvVars</varname></term>
<listitem><para>This attribute allows you to specify a list of <listitem><para>This attribute allows you to specify a list of
@ -1706,7 +1739,7 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
</varlistentry> </varlistentry>
<varlistentry><term><varname>preferLocalBuild</varname></term> <varlistentry><term><varname>preferLocalBuild</varname></term>
<listitem><para>If this attribute is set to <listitem><para>If this attribute is set to