mdebray/tvl-depot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document multiple output support

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

19
doc/manual/nix-build.xml
View file

@ -190,6 +190,25 @@ $ ./pan/gui/pan
</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>. It’s 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>

77
doc/manual/writing-nix-expressions.xml
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
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
@ -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