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

@ -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>

View file

@ -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
@ -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