Merge commit '84d74ae9c9cbed73274b8e4e00be14688ffc93fe'

3 files changed, 155 insertions, 126 deletions

diff --git a/nixpkgs/doc/stdenv/meta.xml b/nixpkgs/doc/stdenv/meta.xml
index 45f7834eb2cc..9cef9360002c 100644
--- a/nixpkgs/doc/stdenv/meta.xml
+++ b/nixpkgs/doc/stdenv/meta.xml
@@ -155,17 +155,17 @@ hello-2.3  A program that produces a familiar, friendly greeting
       <itemizedlist>
        <listitem>
         <para>
-         Single license referenced by attribute (preferred) <literal>stdenv.lib.licenses.gpl3</literal>.
+         Single license referenced by attribute (preferred) <literal>stdenv.lib.licenses.gpl3Only</literal>.
         </para>
        </listitem>
        <listitem>
         <para>
-         Single license referenced by its attribute shortName (frowned upon) <literal>"gpl3"</literal>.
+         Single license referenced by its attribute shortName (frowned upon) <literal>"gpl3Only"</literal>.
         </para>
        </listitem>
        <listitem>
         <para>
-         Single license referenced by its attribute spdxId (frowned upon) <literal>"GPL-3.0"</literal>.
+         Single license referenced by its attribute spdxId (frowned upon) <literal>"GPL-3.0-only"</literal>.
         </para>
        </listitem>
        <listitem>
diff --git a/nixpkgs/doc/stdenv/multiple-output.xml b/nixpkgs/doc/stdenv/multiple-output.xml
index 51e1cc2e024a..20658918db72 100644
--- a/nixpkgs/doc/stdenv/multiple-output.xml
+++ b/nixpkgs/doc/stdenv/multiple-output.xml
@@ -22,39 +22,69 @@
     The reduction effects could be instead achieved by building the parts in completely separate derivations. That would often additionally reduce build-time closures, but it tends to be much harder to write such derivations, as build systems typically assume all parts are being built at once. This compromise approach of single source package producing multiple binary packages is also utilized often by rpm and deb.
    </para>
   </note>
+
+  <para>
+   A number of attributes can be used to work with a derivation with multiple outputs. The attribute <varname>outputs</varname> is a list of strings, which are the names of the outputs. For each of these names, an identically named attribute is created, corresponding to that output. The attribute <varname>meta.outputsToInstall</varname> is used to determine the default set of outputs to install when using the derivation name unqualified.
+  </para>
+
  </section>
  <section xml:id="sec-multiple-outputs-installing">
   <title>Installing a split package</title>
 
   <para>
-   When installing a package via <varname>systemPackages</varname> or <command>nix-env</command> you have several options:
+   When installing a package with multiple outputs, the package's <varname>meta.outputsToInstall</varname> attribute determines which outputs are actually installed. <varname>meta.outputsToInstall</varname> is a list whose <link xlink:href="https://github.com/NixOS/nixpkgs/blob/f1680774340d5443a1409c3421ced84ac1163ba9/pkgs/stdenv/generic/make-derivation.nix#L310-L320">default installs binaries and the associated man pages</link>. The following sections describe ways to install different outputs.
   </para>
 
-  <itemizedlist>
-   <listitem>
-    <para>
-     You can install particular outputs explicitly, as each is available in the Nix language as an attribute of the package. The <varname>outputs</varname> attribute contains a list of output names.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     You can let it use the default outputs. These are handled by <varname>meta.outputsToInstall</varname> attribute that contains a list of output names.
-    </para>
+  <section xml:id="sec-multiple-outputs-installing-nixos">
+   <title>Selecting outputs to install via NixOS</title>
+
+   <para>
+    NixOS provides two ways to select the outputs to install for packages listed in <varname>environment.systemPackages</varname>:
+   </para>
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      The configuration option <varname>environment.extraOutputsToInstall</varname> is appended to each package's <varname>meta.outputsToInstall</varname> attribute to determine the outputs to install. It can for example be used to install <literal>info</literal> documentation or debug symbols for all packages.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      The outputs can be listed as packages in <varname>environment.systemPackages</varname>. For example, the <literal>"out"</literal> and <literal>"info"</literal> outputs for the <varname>coreutils</varname> package can be installed by including <varname>coreutils</varname> and <varname>coreutils.info</varname> in <varname>environment.systemPackages</varname>.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </section>
+
+  <section xml:id="sec-multiple-outputs-installing-nix-env">
+   <title>Selecting outputs to install via <command>nix-env</command></title>
+
+   <para>
+    <command>nix-env</command> lacks an easy way to select the outputs to install. When installing a package, <command>nix-env</command> always installs the outputs listed in <varname>meta.outputsToInstall</varname>, even when the user explicitly selects an output.
+   </para>
+
+   <warning>
     <para>
-     TODO: more about tweaking the attribute, etc.
+     <command>nix-env</command> silenty disregards the outputs selected by the user, and instead installs the outputs from <varname>meta.outputsToInstall</varname>. For example,
     </para>
-   </listitem>
-   <listitem>
+<screen><prompt>$ </prompt>nix-env -iA nixpkgs.coreutils.info</screen>
     <para>
-     NixOS provides configuration option <varname>environment.extraOutputsToInstall</varname> that allows adding extra outputs of <varname>environment.systemPackages</varname> atop the default ones. It's mainly meant for documentation and debug symbols, and it's also modified by specific options.
+     installs the <literal>"out"</literal> output (<varname>coreutils.meta.outputsToInstall</varname> is <literal>[ "out" ]</literal>) instead of the requested <literal>"info"</literal>.
     </para>
-    <note>
-     <para>
-      At this moment there is no similar configurability for packages installed by <command>nix-env</command>. You can still use approach from <xref linkend="sec-modify-via-packageOverrides" /> to override <varname>meta.outputsToInstall</varname> attributes, but that's a rather inconvenient way.
-     </para>
-    </note>
-   </listitem>
-  </itemizedlist>
+   </warning>
+
+   <para>
+    The only recourse to select an output with <command>nix-env</command> is to override the package's <varname>meta.outputsToInstall</varname>, using the functions described in <xref linkend="chap-overrides" />. For example, the following overlay adds the <literal>"info"</literal> output for the <varname>coreutils</varname> package:
+   </para>
+
+<programlisting>self: super:
+{
+  coreutils = super.coreutils.overrideAttrs (oldAttrs: {
+    meta = oldAttrs.meta // { outputsToInstall = oldAttrs.meta.outputsToInstall or [ "out" ] ++ [ "info" ]; };
+  });
+}
+</programlisting>
+  </section>
  </section>
  <section xml:id="sec-multiple-outputs-using-split-packages">
   <title>Using a split package</title>
diff --git a/nixpkgs/doc/stdenv/stdenv.xml b/nixpkgs/doc/stdenv/stdenv.xml
index ee93f39318b8..42fae73e8816 100644
--- a/nixpkgs/doc/stdenv/stdenv.xml
+++ b/nixpkgs/doc/stdenv/stdenv.xml
@@ -254,7 +254,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Variables specifying dependencies</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildBuild">
     <term>
      <varname>depsBuildBuild</varname>
     </term>
@@ -267,7 +267,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-nativeBuildInputs">
     <term>
      <varname>nativeBuildInputs</varname>
     </term>
@@ -280,7 +280,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildTarget">
     <term>
      <varname>depsBuildTarget</varname>
     </term>
@@ -296,7 +296,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsHostHost">
     <term>
      <varname>depsHostHost</varname>
     </term>
@@ -306,7 +306,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-buildInputs">
     <term>
      <varname>buildInputs</varname>
     </term>
@@ -319,7 +319,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsTargetTarget">
     <term>
      <varname>depsTargetTarget</varname>
     </term>
@@ -329,7 +329,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildBuildPropagated">
     <term>
      <varname>depsBuildBuildPropagated</varname>
     </term>
@@ -339,7 +339,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-propagatedNativeBuildInputs">
     <term>
      <varname>propagatedNativeBuildInputs</varname>
     </term>
@@ -349,7 +349,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildTargetPropagated">
     <term>
      <varname>depsBuildTargetPropagated</varname>
     </term>
@@ -359,7 +359,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsHostHostPropagated">
     <term>
      <varname>depsHostHostPropagated</varname>
     </term>
@@ -369,7 +369,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-propagatedBuildInputs">
     <term>
      <varname>propagatedBuildInputs</varname>
     </term>
@@ -379,7 +379,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsTargetTargetPropagated">
     <term>
      <varname>depsTargetTargetPropagated</varname>
     </term>
@@ -396,7 +396,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Variables affecting <literal>stdenv</literal> initialisation</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-NIX_DEBUG">
     <term>
      <varname>NIX_DEBUG</varname>
     </term>
@@ -410,7 +410,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Attributes affecting build properties</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-enableParallelBuilding">
     <term>
      <varname>enableParallelBuilding</varname>
     </term>
@@ -427,7 +427,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Special variables</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-passthru">
     <term>
      <varname>passthru</varname>
     </term>
@@ -504,7 +504,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
     There are a number of variables that control what phases are executed and in what order:
     <variablelist>
      <title>Variables affecting phase control</title>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-phases">
       <term>
        <varname>phases</varname>
       </term>
@@ -517,7 +517,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-prePhases">
       <term>
        <varname>prePhases</varname>
       </term>
@@ -527,7 +527,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preConfigurePhases">
       <term>
        <varname>preConfigurePhases</varname>
       </term>
@@ -537,7 +537,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preBuildPhases">
       <term>
        <varname>preBuildPhases</varname>
       </term>
@@ -547,7 +547,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preInstallPhases">
       <term>
        <varname>preInstallPhases</varname>
       </term>
@@ -557,7 +557,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preFixupPhases">
       <term>
        <varname>preFixupPhases</varname>
       </term>
@@ -567,7 +567,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preDistPhases">
       <term>
        <varname>preDistPhases</varname>
       </term>
@@ -577,7 +577,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-postPhases">
       <term>
        <varname>postPhases</varname>
       </term>
@@ -635,7 +635,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the unpack phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-src">
      <term>
       <varname>srcs</varname> / <varname>src</varname>
      </term>
@@ -645,7 +645,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-sourceRoot">
      <term>
       <varname>sourceRoot</varname>
      </term>
@@ -655,7 +655,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-setSourceRoot">
      <term>
       <varname>setSourceRoot</varname>
      </term>
@@ -665,7 +665,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preUnpack">
      <term>
       <varname>preUnpack</varname>
      </term>
@@ -675,7 +675,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postUnpack">
      <term>
       <varname>postUnpack</varname>
      </term>
@@ -685,7 +685,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontUnpack">
      <term>
       <varname>dontUnpack</varname>
      </term>
@@ -695,7 +695,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontMakeSourcesWritable">
      <term>
       <varname>dontMakeSourcesWritable</varname>
      </term>
@@ -705,7 +705,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-unpackCmd">
      <term>
       <varname>unpackCmd</varname>
      </term>
@@ -727,7 +727,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the patch phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPatch">
      <term>
       <varname>dontPatch</varname>
      </term>
@@ -737,7 +737,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-patches">
      <term>
       <varname>patches</varname>
      </term>
@@ -747,7 +747,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-patchFlags">
      <term>
       <varname>patchFlags</varname>
      </term>
@@ -757,7 +757,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-prePatch">
      <term>
       <varname>prePatch</varname>
      </term>
@@ -767,7 +767,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postPatch">
      <term>
       <varname>postPatch</varname>
      </term>
@@ -789,7 +789,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the configure phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configureScript">
      <term>
       <varname>configureScript</varname>
      </term>
@@ -799,7 +799,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configureFlags">
      <term>
       <varname>configureFlags</varname>
      </term>
@@ -809,7 +809,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontConfigure">
      <term>
       <varname>dontConfigure</varname>
      </term>
@@ -819,7 +819,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configureFlagsArray">
      <term>
       <varname>configureFlagsArray</varname>
      </term>
@@ -829,7 +829,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontAddPrefix">
      <term>
       <varname>dontAddPrefix</varname>
      </term>
@@ -839,7 +839,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-prefix">
      <term>
       <varname>prefix</varname>
      </term>
@@ -849,7 +849,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-prefixKey">
      <term>
       <varname>prefixKey</varname>
      </term>
@@ -859,7 +859,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontAddDisableDepTrack">
      <term>
       <varname>dontAddDisableDepTrack</varname>
      </term>
@@ -869,7 +869,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontFixLibtool">
      <term>
       <varname>dontFixLibtool</varname>
      </term>
@@ -885,7 +885,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontDisableStatic">
      <term>
       <varname>dontDisableStatic</varname>
      </term>
@@ -898,7 +898,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configurePlatforms">
      <term>
       <varname>configurePlatforms</varname>
      </term>
@@ -913,7 +913,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preConfigure">
      <term>
       <varname>preConfigure</varname>
      </term>
@@ -923,7 +923,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postConfigure">
      <term>
       <varname>postConfigure</varname>
      </term>
@@ -945,7 +945,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the build phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontBuild">
      <term>
       <varname>dontBuild</varname>
      </term>
@@ -955,7 +955,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-makefile">
      <term>
       <varname>makefile</varname>
      </term>
@@ -965,7 +965,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-makeFlags">
      <term>
       <varname>makeFlags</varname>
      </term>
@@ -983,7 +983,7 @@ makeFlags = [ "PREFIX=$(out)" ];
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-makeFlagsArray">
      <term>
       <varname>makeFlagsArray</varname>
      </term>
@@ -999,7 +999,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-buildFlags">
      <term>
       <varname>buildFlags</varname> / <varname>buildFlagsArray</varname>
      </term>
@@ -1009,7 +1009,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preBuild">
      <term>
       <varname>preBuild</varname>
      </term>
@@ -1019,7 +1019,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postBuild">
      <term>
       <varname>postBuild</varname>
      </term>
@@ -1049,7 +1049,7 @@ preBuild = ''
 
    <variablelist>
     <title>Variables controlling the check phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-doCheck">
      <term>
       <varname>doCheck</varname>
      </term>
@@ -1067,11 +1067,11 @@ preBuild = ''
      </term>
      <listitem>
       <para>
-       See the build phase for details.
+       See the <link xlink:href="#var-stdenv-makeFlags">build phase</link> for details.
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-checkTarget">
      <term>
       <varname>checkTarget</varname>
      </term>
@@ -1081,7 +1081,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-checkFlags">
      <term>
       <varname>checkFlags</varname> / <varname>checkFlagsArray</varname>
      </term>
@@ -1091,7 +1091,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-checkInputs">
      <term>
       <varname>checkInputs</varname>
      </term>
@@ -1101,7 +1101,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preCheck">
      <term>
       <varname>preCheck</varname>
      </term>
@@ -1111,7 +1111,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postCheck">
      <term>
       <varname>postCheck</varname>
      </term>
@@ -1133,7 +1133,7 @@ preBuild = ''
 
    <variablelist>
     <title>Variables controlling the install phase</title>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-dontInstall">
      <term>
        <varname>dontInstall</varname>
      </term>
@@ -1149,11 +1149,11 @@ preBuild = ''
      </term>
      <listitem>
       <para>
-       See the build phase for details.
+       See the <link xlink:href="#var-stdenv-makeFlags">build phase</link> for details.
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installTargets">
      <term>
       <varname>installTargets</varname>
      </term>
@@ -1165,7 +1165,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installFlags">
      <term>
       <varname>installFlags</varname> / <varname>installFlagsArray</varname>
      </term>
@@ -1175,7 +1175,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preInstall">
      <term>
       <varname>preInstall</varname>
      </term>
@@ -1185,7 +1185,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postInstall">
      <term>
       <varname>postInstall</varname>
      </term>
@@ -1229,7 +1229,7 @@ installTargets = "install-bin install-doc";</programlisting>
 
    <variablelist>
     <title>Variables controlling the fixup phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontFixup">
      <term>
       <varname>dontFixup</varname>
      </term>
@@ -1239,7 +1239,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontStrip">
      <term>
       <varname>dontStrip</varname>
      </term>
@@ -1249,7 +1249,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontStripHost">
      <term>
       <varname>dontStripHost</varname>
      </term>
@@ -1259,7 +1259,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontStripTarget">
      <term>
       <varname>dontStripTarget</varname>
      </term>
@@ -1269,7 +1269,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontMoveSbin">
      <term>
       <varname>dontMoveSbin</varname>
      </term>
@@ -1279,7 +1279,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripAllList">
      <term>
       <varname>stripAllList</varname>
      </term>
@@ -1289,7 +1289,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripAllFlags">
      <term>
       <varname>stripAllFlags</varname>
      </term>
@@ -1299,7 +1299,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripDebugList">
      <term>
       <varname>stripDebugList</varname>
      </term>
@@ -1309,7 +1309,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripDebugFlags">
      <term>
       <varname>stripDebugFlags</varname>
      </term>
@@ -1319,7 +1319,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPatchELF">
      <term>
       <varname>dontPatchELF</varname>
      </term>
@@ -1329,7 +1329,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPatchShebangs">
      <term>
       <varname>dontPatchShebangs</varname>
      </term>
@@ -1339,7 +1339,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPruneLibtoolFiles">
      <term>
       <varname>dontPruneLibtoolFiles</varname>
      </term>
@@ -1349,7 +1349,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-forceShare">
      <term>
       <varname>forceShare</varname>
      </term>
@@ -1359,7 +1359,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-setupHook">
      <term>
       <varname>setupHook</varname>
      </term>
@@ -1370,7 +1370,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preFixup">
      <term>
       <varname>preFixup</varname>
      </term>
@@ -1380,7 +1380,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postFixup">
      <term>
       <varname>postFixup</varname>
      </term>
@@ -1419,7 +1419,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
 
    <variablelist>
     <title>Variables controlling the installCheck phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-doInstallCheck">
      <term>
       <varname>doInstallCheck</varname>
      </term>
@@ -1431,7 +1431,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installCheckTarget">
      <term>
       <varname>installCheckTarget</varname>
      </term>
@@ -1441,7 +1441,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installCheckFlags">
      <term>
       <varname>installCheckFlags</varname> / <varname>installCheckFlagsArray</varname>
      </term>
@@ -1451,7 +1451,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installCheckInputs">
      <term>
       <varname>installCheckInputs</varname>
      </term>
@@ -1461,7 +1461,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preInstallCheck">
      <term>
       <varname>preInstallCheck</varname>
      </term>
@@ -1471,7 +1471,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postInstallCheck">
      <term>
       <varname>postInstallCheck</varname>
      </term>
@@ -1493,7 +1493,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
 
    <variablelist>
     <title>Variables controlling the distribution phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-distTarget">
      <term>
       <varname>distTarget</varname>
      </term>
@@ -1503,7 +1503,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-distFlags">
      <term>
       <varname>distFlags</varname> / <varname>distFlagsArray</varname>
      </term>
@@ -1513,7 +1513,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-tarballs">
      <term>
       <varname>tarballs</varname>
      </term>
@@ -1523,7 +1523,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontCopyDist">
      <term>
       <varname>dontCopyDist</varname>
      </term>
@@ -1533,7 +1533,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preDist">
      <term>
       <varname>preDist</varname>
      </term>
@@ -1543,7 +1543,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postDist">
      <term>
       <varname>postDist</varname>
      </term>
@@ -1636,10 +1636,6 @@ substitute ./foo.in ./foo.out \
     --subst-var someVar
 </programlisting>
      </para>
-     <para>
-      <function>substitute</function> is implemented using the <command
-      xlink:href="http://replace.richardlloyd.org.uk/">replace</command> command. Unlike with the <command>sed</command> command, you don’t have to worry about escaping special characters. It supports performing substitutions on binary files (such as executables), though there you’ll probably want to make sure that the replacement string is as long as the replaced string.
-     </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id='fun-substituteInPlace'>
@@ -2019,6 +2015,9 @@ addEnvHooks "$hostOffset" myBashFunction
        In certain situations you may want to run the main command (<command>autoPatchelf</command>) of the setup hook on a file or a set of directories instead of unconditionally patching all outputs. This can be done by setting the <varname>dontAutoPatchelf</varname> environment variable to a non-empty value.
       </para>
       <para>
+       By default <command>autoPatchelf</command> will fail as soon as any ELF file requires a dependency which cannot be resolved via the given build inputs. In some situations you might prefer to just leave missing dependencies unpatched and continue to patch the rest. This can be achieved by setting the <envar>autoPatchelfIgnoreMissingDeps</envar> environment variable to a non-empty value.
+      </para>
+      <para>
        The <command>autoPatchelf</command> command also recognizes a <parameter class="command">--no-recurse</parameter> command line flag, which prevents it from recursing into subdirectories.
       </para>
      </listitem>