Document multiple output support

doc/manual/nix-build.xml

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

doc/manual/writing-nix-expressions.xml

@@ -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 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
 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
+      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>
 
       <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
+    <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 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
+  <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
   timestamp on all files in the build result to 1 (00:00:01 1/1/1970