Document multiple output support
This commit is contained in:
Eelco Dolstra
parent
b215b23e9e
commit
24d5875514
2 changed files with 108 additions and 56 deletions
|
|
@ -96,7 +96,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
|
|||
<variablelist>
|
||||
|
||||
<varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
|
||||
|
||||
|
||||
<listitem><para>Add a symlink named
|
||||
<replaceable>drvlink</replaceable> to the store derivation
|
||||
produced by <command>nix-instantiate</command>. The derivation is
|
||||
|
|
@ -108,14 +108,14 @@ also <xref linkend="sec-common-options" />.</phrase></para>
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry><term><option>--add-drv-link</option></term>
|
||||
|
||||
|
||||
<listitem><para>Shorthand for <option>--drv-link</option>
|
||||
<filename>./derivation</filename>.</para></listitem>
|
||||
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><option>--no-out-link</option></term>
|
||||
|
||||
|
||||
<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
|
||||
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> /
|
||||
<option>-o</option> <replaceable>outlink</replaceable></term>
|
||||
|
||||
|
||||
<listitem><para>Change the name of the symlink to the output path
|
||||
created from <filename>result</filename> to
|
||||
<replaceable>outlink</replaceable>.</para></listitem>
|
||||
|
|
@ -143,7 +143,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
|
|||
<variablelist>
|
||||
|
||||
<varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
|
||||
|
||||
|
||||
<listitem><para>In the environment of the derivation, executeq the
|
||||
command <replaceable>cmd</replaceable> instead of the default
|
||||
interactive shell.</para></listitem>
|
||||
|
|
@ -151,7 +151,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>
|
||||
|
||||
|
||||
<listitem><para>Do not build any dependencies whose store path
|
||||
matches the regular expression <replaceable>regexp</replaceable>.
|
||||
This option may be specified multiple times.</para></listitem>
|
||||
|
|
@ -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 '<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 '<nixpkgs>' -A openssl.man
|
||||
</screen>
|
||||
This will create a symlink <literal>result-man</literal>.</para>
|
||||
|
||||
</refsection>
|
||||
|
||||
|
|
@ -201,6 +220,6 @@ $ ./pan/gui/pan
|
|||
</variablelist>
|
||||
|
||||
</refsection>
|
||||
|
||||
|
||||
|
||||
</refentry>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue