Merge commit '0c0954781e257b8b0dc49341795a2fe7d96945a3'

9 files changed, 398 insertions, 146 deletions

diff --git a/nixpkgs/doc/Makefile b/nixpkgs/doc/Makefile
index cd6d7eb8d1c8..5badfe4138d4 100644
--- a/nixpkgs/doc/Makefile
+++ b/nixpkgs/doc/Makefile
@@ -78,15 +78,14 @@ manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml function
 	nix-instantiate --eval \
 		-E '(import ../lib).version' > .version
 
-function_locations := $(shell nix-build --no-out-link ./lib-function-locations.nix)
-
 functions/library/locations.xml:
-	ln -s $(function_locations) ./functions/library/locations.xml
+	nix-build ./lib-function-locations.nix \
+		--out-link $@
 
-functions/library/generated:
+functions/library/generated: functions/library/locations.xml
 	nix-build ./lib-function-docs.nix \
-		--arg locationsXml $(function_locations)\
-		--out-link ./functions/library/generated
+		--arg locationsXml $< \
+		--out-link $@
 
 %.section.xml: %.section.md
 	pandoc $^ -w docbook+smart \
diff --git a/nixpkgs/doc/cross-compilation.xml b/nixpkgs/doc/cross-compilation.xml
index dbaf6f104ec0..b7844da195d7 100644
--- a/nixpkgs/doc/cross-compilation.xml
+++ b/nixpkgs/doc/cross-compilation.xml
@@ -12,11 +12,12 @@
    computing power and memory to compile their own programs. One might think
    that cross-compilation is a fairly niche concern. However, there are
    significant advantages to rigorously distinguishing between build-time and
-   run-time environments! This applies even when one is developing and
-   deploying on the same machine. Nixpkgs is increasingly adopting the opinion
-   that packages should be written with cross-compilation in mind, and nixpkgs
-   should evaluate in a similar way (by minimizing cross-compilation-specific
-   special cases) whether or not one is cross-compiling.
+   run-time environments! Significant, because the benefits apply even when one
+   is developing and deploying on the same machine. Nixpkgs is increasingly
+   adopting the opinion that packages should be written with cross-compilation
+   in mind, and nixpkgs should evaluate in a similar way (by minimizing
+   cross-compilation-specific special cases) whether or not one is
+   cross-compiling.
   </para>
 
   <para>
@@ -30,7 +31,7 @@
  <section xml:id="sec-cross-packaging">
   <title>Packaging in a cross-friendly manner</title>
 
-  <section xml:id="sec-cross-platform-parameters">
+  <section xml:id="ssec-cross-platform-parameters">
    <title>Platform parameters</title>
 
    <para>
@@ -218,8 +219,20 @@
    </variablelist>
   </section>
 
-  <section xml:id="sec-cross-specifying-dependencies">
-   <title>Specifying Dependencies</title>
+  <section xml:id="ssec-cross-dependency-categorization">
+   <title>Theory of dependency categorization</title>
+
+   <note>
+    <para>
+     This is a rather philosophical description that isn't very
+     Nixpkgs-specific. For an overview of all the relevant attributes given to
+     <varname>mkDerivation</varname>, see
+     <xref
+     linkend="ssec-stdenv-dependencies"/>. For a description of how
+     everything is implemented, see
+     <xref linkend="ssec-cross-dependency-implementation" />.
+    </para>
+   </note>
 
    <para>
     In this section we explore the relationship between both runtime and
@@ -227,84 +240,98 @@
    </para>
 
    <para>
-    A runtime dependency between 2 packages implies that between them both the
-    host and target platforms match. This is directly implied by the meaning of
-    "host platform" and "runtime dependency": The package dependency exists
-    while both packages are running on a single host platform.
+    A run time dependency between two packages requires that their host
+    platforms match. This is directly implied by the meaning of "host platform"
+    and "runtime dependency": The package dependency exists while both packages
+    are running on a single host platform.
    </para>
 
    <para>
-    A build time dependency, however, implies a shift in platforms between the
-    depending package and the depended-on package. The meaning of a build time
-    dependency is that to build the depending package we need to be able to run
-    the depended-on's package. The depending package's build platform is
-    therefore equal to the depended-on package's host platform. Analogously,
-    the depending package's host platform is equal to the depended-on package's
-    target platform.
+    A build time dependency, however, has a shift in platforms between the
+    depending package and the depended-on package. "build time dependency"
+    means that to build the depending package we need to be able to run the
+    depended-on's package. The depending package's build platform is therefore
+    equal to the depended-on package's host platform.
    </para>
 
    <para>
-    In this manner, given the 3 platforms for one package, we can determine the
-    three platforms for all its transitive dependencies. This is the most
-    important guiding principle behind cross-compilation with Nixpkgs, and will
-    be called the <wordasword>sliding window principle</wordasword>.
+    If both the dependency and depending packages aren't compilers or other
+    machine-code-producing tools, we're done. And indeed
+    <varname>buildInputs</varname> and <varname>nativeBuildInputs</varname>
+    have covered these simpler build-time and run-time (respectively) changes
+    for many years. But if the dependency does produce machine code, we might
+    need to worry about its target platform too. In principle, that target
+    platform might be any of the depending package's build, host, or target
+    platforms, but we prohibit dependencies from a "later" platform to an
+    earlier platform to limit confusion because we've never seen a legitimate
+    use for them.
    </para>
 
    <para>
-    Some examples will make this clearer. If a package is being built with a
-    <literal>(build, host, target)</literal> platform triple of <literal>(foo,
-    bar, bar)</literal>, then its build-time dependencies would have a triple
-    of <literal>(foo, foo, bar)</literal>, and <emphasis>those
-    packages'</emphasis> build-time dependencies would have a triple of
-    <literal>(foo, foo, foo)</literal>. In other words, it should take two
-    "rounds" of following build-time dependency edges before one reaches a
-    fixed point where, by the sliding window principle, the platform triple no
-    longer changes. Indeed, this happens with cross-compilation, where only
-    rounds of native dependencies starting with the second necessarily coincide
-    with native packages.
+    Finally, if the depending package is a compiler or other
+    machine-code-producing tool, it might need dependencies that run at "emit
+    time". This is for compilers that (regrettably) insist on being built
+    together with their source langauges' standard libraries. Assuming build !=
+    host != target, a run-time dependency of the standard library cannot be run
+    at the compiler's build time or run time, but only at the run time of code
+    emitted by the compiler.
    </para>
 
-   <note>
-    <para>
-     The depending package's target platform is unconstrained by the sliding
-     window principle, which makes sense in that one can in principle build
-     cross compilers targeting arbitrary platforms.
-    </para>
-   </note>
-
    <para>
-    How does this work in practice? Nixpkgs is now structured so that
-    build-time dependencies are taken from <varname>buildPackages</varname>,
-    whereas run-time dependencies are taken from the top level attribute set.
-    For example, <varname>buildPackages.gcc</varname> should be used at
-    build-time, while <varname>gcc</varname> should be used at run-time. Now,
-    for most of Nixpkgs's history, there was no
-    <varname>buildPackages</varname>, and most packages have not been
-    refactored to use it explicitly. Instead, one can use the six
-    (<emphasis>gasp</emphasis>) attributes used for specifying dependencies as
-    documented in <xref linkend="ssec-stdenv-dependencies"/>. We "splice"
-    together the run-time and build-time package sets with
-    <varname>callPackage</varname>, and then <varname>mkDerivation</varname>
-    for each of four attributes pulls the right derivation out. This splicing
-    can be skipped when not cross-compiling as the package sets are the same,
-    but is a bit slow for cross-compiling. Because of this, a
-    best-of-both-worlds solution is in the works with no splicing or explicit
-    access of <varname>buildPackages</varname> needed. For now, feel free to
-    use either method.
+    Putting this all together, that means we have dependencies in the form
+    "host → target", in at most the following six combinations:
+    <table>
+     <caption>Possible dependency types</caption>
+     <thead>
+      <tr>
+       <th>Dependency's host platform</th>
+       <th>Dependency's target platform</th>
+      </tr>
+     </thead>
+     <tbody>
+      <tr>
+       <td>build</td>
+       <td>build</td>
+      </tr>
+      <tr>
+       <td>build</td>
+       <td>host</td>
+      </tr>
+      <tr>
+       <td>build</td>
+       <td>target</td>
+      </tr>
+      <tr>
+       <td>host</td>
+       <td>host</td>
+      </tr>
+      <tr>
+       <td>host</td>
+       <td>target</td>
+      </tr>
+      <tr>
+       <td>target</td>
+       <td>target</td>
+      </tr>
+     </tbody>
+    </table>
    </para>
 
-   <note>
-    <para>
-     There is also a "backlink" <varname>targetPackages</varname>, yielding a
-     package set whose <varname>buildPackages</varname> is the current package
-     set. This is a hack, though, to accommodate compilers with lousy build
-     systems. Please do not use this unless you are absolutely sure you are
-     packaging such a compiler and there is no other way.
-    </para>
-   </note>
+   <para>
+    Some examples will make this table clearer. Suppose there's some package
+    that is being built with a <literal>(build, host, target)</literal>
+    platform triple of <literal>(foo, bar, baz)</literal>. If it has a
+    build-time library dependency, that would be a "host → build" dependency
+    with a triple of <literal>(foo, foo, *)</literal> (the target platform is
+    irrelevant). If it needs a compiler to be built, that would be a "build →
+    host" dependency with a triple of <literal>(foo, foo, *)</literal> (the
+    target platform is irrelevant). That compiler, would be built with another
+    compiler, also "build → host" dependency, with a triple of <literal>(foo,
+    foo, foo)</literal>.
+   </para>
   </section>
 
-  <section xml:id="sec-cross-cookbook">
+  <section xml:id="ssec-cross-cookbook">
    <title>Cross packaging cookbook</title>
 
    <para>
@@ -450,21 +477,202 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
  <section xml:id="sec-cross-infra">
   <title>Cross-compilation infrastructure</title>
 
-  <para>
-   To be written.
-  </para>
+  <section xml:id="ssec-cross-dependency-implementation">
+   <title>Implementation of dependencies</title>
 
-  <note>
    <para>
-    If one explores Nixpkgs, they will see derivations with names like
-    <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is
-    a holdover from before we properly distinguished between the host and
-    target platforms—the derivation with "Cross" in the name covered the
-    <literal>build = host != target</literal> case, while the other covered the
-    <literal>host = target</literal>, with build platform the same or not based
-    on whether one was using its <literal>.nativeDrv</literal> or
-    <literal>.crossDrv</literal>. This ugliness will disappear soon.
+    The categorizes of dependencies developed in
+    <xref
+    linkend="ssec-cross-dependency-categorization"/> are specified as
+    lists of derivations given to <varname>mkDerivation</varname>, as
+    documented in <xref linkend="ssec-stdenv-dependencies"/>. In short,
+    each list of dependencies for "host → target" of "foo → bar" is called
+    <varname>depsFooBar</varname>, with exceptions for backwards
+    compatibility that <varname>depsBuildHost</varname> is instead called
+    <varname>nativeBuildInputs</varname> and <varname>depsHostTarget</varname>
+    is instead called <varname>buildInputs</varname>. Nixpkgs is now structured
+    so that each <varname>depsFooBar</varname> is automatically taken from
+    <varname>pkgsFooBar</varname>. (These <varname>pkgsFooBar</varname>s are
+    quite new, so there is no special case for
+    <varname>nativeBuildInputs</varname> and <varname>buildInputs</varname>.)
+    For example, <varname>pkgsBuildHost.gcc</varname> should be used at
+    build-time, while <varname>pkgsHostTarget.gcc</varname> should be used at
+    run-time.
    </para>
-  </note>
+
+   <para>
+    Now, for most of Nixpkgs's history, there were no
+    <varname>pkgsFooBar</varname> attributes, and most packages have not been
+    refactored to use it explicitly. Prior to those, there were just
+    <varname>buildPackages</varname>, <varname>pkgs</varname>, and
+    <varname>targetPackages</varname>. Those are now redefined as aliases to
+    <varname>pkgsBuildHost</varname>, <varname>pkgsHostTarget</varname>, and
+    <varname>pkgsTargetTarget</varname>. It is acceptable, even
+    recommended, to use them for libraries to show that the host platform is
+    irrelevant.
+   </para>
+
+   <para>
+    But before that, there was just <varname>pkgs</varname>, even though both
+    <varname>buildInputs</varname> and <varname>nativeBuildInputs</varname>
+    existed. [Cross barely worked, and those were implemented with some hacks
+    on <varname>mkDerivation</varname> to override dependencies.] What this
+    means is the vast majority of packages do not use any explicit package set
+    to populate their dependencies, just using whatever
+    <varname>callPackage</varname> gives them even if they do correctly sort
+    their dependencies into the multiple lists described above. And indeed,
+    asking that users both sort their dependencies, <emphasis>and</emphasis>
+    take them from the right attribute set, is both too onerous and redundant,
+    so the recommended approach (for now) is to continue just categorizing by
+    list and not using an explicit package set.
+   </para>
+
+   <para>
+    To make this work, we "splice" together the six
+    <varname>pkgsFooBar</varname> package sets and have
+    <varname>callPackage</varname> actually take its arguments from that. This
+    is currently implemented in <filename>pkgs/top-level/splice.nix</filename>.
+    <varname>mkDerivation</varname> then, for each dependency attribute, pulls
+    the right derivation out from the splice. This splicing can be skipped when
+    not cross-compiling as the package sets are the same, but still is a bit
+    slow for cross-compiling. We'd like to do something better, but haven't
+    come up with anything yet.
+   </para>
+  </section>
+
+  <section xml:id="ssec-bootstrapping">
+   <title>Bootstrapping</title>
+
+   <para>
+    Each of the package sets described above come from a single bootstrapping
+    stage. While <filename>pkgs/top-level/default.nix</filename>, coordinates
+    the composition of stages at a high level,
+    <filename>pkgs/top-level/stage.nix</filename> "ties the knot" (creates the
+    fixed point) of each stage. The package sets are defined per-stage however,
+    so they can be thought of as edges between stages (the nodes) in a graph.
+    Compositions like <literal>pkgsBuildTarget.targetPackages</literal> can be
+    thought of as paths to this graph.
+   </para>
+
+   <para>
+    While there are many package sets, and thus many edges, the stages can also
+    be arranged in a linear chain. In other words, many of the edges are
+    redundant as far as connectivity is concerned. This hinges on the type of
+    bootstrapping we do. Currently for cross it is:
+    <orderedlist>
+     <listitem>
+      <para>
+       <literal>(native, native, native)</literal>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <literal>(native, native, foreign)</literal>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <literal>(native, foreign, foreign)</literal>
+      </para>
+     </listitem>
+    </orderedlist>
+    In each stage, <varname>pkgsBuildHost</varname> refers the the previous
+    stage, <varname>pkgsBuildBuild</varname> refers to the one before that, and
+    <varname>pkgsHostTarget</varname> refers to the current one, and
+    <varname>pkgsTargetTarget</varname> refers to the next one. When there is
+    no previous or next stage, they instead refer to the current stage. Note
+    how all the invariants regarding the mapping between dependency and depending
+    packages' build host and target platforms are preserved.
+    <varname>pkgsBuildTarget</varname> and <varname>pkgsHostHost</varname> are
+    more complex in that the stage fitting the requirements isn't always a
+    fixed chain of "prevs" and "nexts" away (modulo the "saturating"
+    self-references at the ends). We just special case each instead. All the primary
+    edges are implemented is in <filename>pkgs/stdenv/booter.nix</filename>,
+    and secondarily aliases in <filename>pkgs/top-level/stage.nix</filename>.
+   </para>
+
+   <note>
+    <para>
+     Note the native stages are bootstrapped in legacy ways that predate the
+     current cross implementation. This is why the the bootstrapping stages
+     leading up to the final stages are ignored inthe previous paragraph.
+    </para>
+   </note>
+
+   <para>
+    If one looks at the 3 platform triples, one can see that they overlap such
+    that one could put them together into a chain like:
+<programlisting>
+(native, native, native, foreign, foreign)
+</programlisting>
+    If one imagines the saturating self references at the end being replaced
+    with infinite stages, and then overlays those platform triples, one ends up
+    with the infinite tuple:
+<programlisting>
+(native..., native, native, native, foreign, foreign, foreign...)
+</programlisting>
+    On can then imagine any sequence of platforms such that there are bootstrap
+    stages with their 3 platforms determined by "sliding a window" that is the
+    3 tuple through the sequence. This was the original model for
+    bootstrapping. Without a target platform (assume a better world where all
+    compilers are multi-target and all standard libraries are built in their
+    own derivation), this is sufficient. Conversely if one wishes to cross
+    compile "faster", with a "Canadian Cross" bootstraping stage where
+    <literal>build != host != target</literal>, more bootstrapping stages are
+    needed since no sliding window providess the pesky
+    <varname>pkgsBuildTarget</varname> package set since it skips the Canadian
+    cross stage's "host".
+   </para>
+
+   <note>
+    <para>
+     It is much better to refer to <varname>buildPackages</varname> than
+     <varname>targetPackages</varname>, or more broadly package sets that do
+     not mention "target". There are three reasons for this.
+    </para>
+    <para>
+     First, it is because bootstrapping stages do not have a unique
+     <varname>targetPackages</varname>. For example a <literal>(x86-linux,
+     x86-linux, arm-linux)</literal> and <literal>(x86-linux, x86-linux,
+     x86-windows)</literal> package set both have a <literal>(x86-linux,
+     x86-linux, x86-linux)</literal> package set. Because there is no canonical
+     <varname>targetPackages</varname> for such a native (<literal>build ==
+     host == target</literal>) package set, we set their
+     <varname>targetPackages</varname>
+    </para>
+    <para>
+     Second, it is because this is a frequent source of hard-to-follow
+     "infinite recursions" / cycles. When only package sets that don't mention
+     target are used, the package set forms a directed acyclic graph. This
+     means that all cycles that exist are confined to one stage. This means
+     they are a lot smaller, and easier to follow in the code or a backtrace. It
+     also means they are present in native and cross builds alike, and so more
+     likely to be caught by CI and other users.
+    </para>
+    <para>
+     Thirdly, it is because everything target-mentioning only exists to
+     accommodate compilers with lousy build systems that insist on the compiler
+     itself and standard library being built together. Of course that is bad
+     because bigger derivations means longer rebuilds. It is also problematic because
+     it tends to make the standard libraries less like other libraries than
+     they could be, complicating code and build systems alike. Because of the
+     other problems, and because of these innate disadvantages, compilers ought
+     to be packaged another way where possible.
+    </para>
+   </note>
+
+   <note>
+    <para>
+     If one explores Nixpkgs, they will see derivations with names like
+     <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is
+     a holdover from before we properly distinguished between the host and
+     target platforms—the derivation with "Cross" in the name covered the
+     <literal>build = host != target</literal> case, while the other covered
+     the <literal>host = target</literal>, with build platform the same or not
+     based on whether one was using its <literal>.nativeDrv</literal> or
+     <literal>.crossDrv</literal>. This ugliness will disappear soon.
+    </para>
+   </note>
+  </section>
  </section>
 </chapter>
diff --git a/nixpkgs/doc/functions/dockertools.xml b/nixpkgs/doc/functions/dockertools.xml
index 75db0bd3918c..cb32db74b424 100644
--- a/nixpkgs/doc/functions/dockertools.xml
+++ b/nixpkgs/doc/functions/dockertools.xml
@@ -417,10 +417,11 @@ pkgs.dockerTools.buildLayeredImage {
 pullImage {
   imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
   imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
-  finalImageTag = "1.11";  <co xml:id='ex-dockerTools-pullImage-3' />
-  sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
-  os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
-  arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
+  finalImageName = "nix"; <co xml:id='ex-dockerTools-pullImage-3' />
+  finalImageTag = "1.11";  <co xml:id='ex-dockerTools-pullImage-4' />
+  sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-5' />
+  os = "linux"; <co xml:id='ex-dockerTools-pullImage-6' />
+  arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-7' />
 }
 </programlisting>
   </example>
@@ -452,25 +453,33 @@ sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
    </callout>
    <callout arearefs='ex-dockerTools-pullImage-3'>
     <para>
+     <varname>finalImageName</varname>, if specified, this is the name of the
+     image to be created. Note it is never used to fetch the image since we
+     prefer to rely on the immutable digest ID. By default it's equal to
+     <varname>imageName</varname>.
+    </para>
+   </callout>
+   <callout arearefs='ex-dockerTools-pullImage-4'>
+    <para>
      <varname>finalImageTag</varname>, if specified, this is the tag of the
      image to be created. Note it is never used to fetch the image since we
      prefer to rely on the immutable digest ID. By default it's
      <literal>latest</literal>.
     </para>
    </callout>
-   <callout arearefs='ex-dockerTools-pullImage-4'>
+   <callout arearefs='ex-dockerTools-pullImage-5'>
     <para>
      <varname>sha256</varname> is the checksum of the whole fetched image. This
      argument is required.
     </para>
    </callout>
-   <callout arearefs='ex-dockerTools-pullImage-5'>
+   <callout arearefs='ex-dockerTools-pullImage-6'>
     <para>
      <varname>os</varname>, if specified, is the operating system of the
      fetched image. By default it's <literal>linux</literal>.
     </para>
    </callout>
-   <callout arearefs='ex-dockerTools-pullImage-6'>
+   <callout arearefs='ex-dockerTools-pullImage-7'>
     <para>
      <varname>arch</varname>, if specified, is the cpu architecture of the
      fetched image. By default it's <literal>x86_64</literal>.
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index 1c9f9fdebe42..e1630c8cb03a 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -188,25 +188,24 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
 ```nix
 { lib, buildPythonPackage, fetchPypi }:
 
-  toolz = buildPythonPackage rec {
-    pname = "toolz";
-    version = "0.7.4";
+buildPythonPackage rec {
+  pname = "toolz";
+  version = "0.7.4";
 
-    src = fetchPypi {
-      inherit pname version;
-      sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
-    };
+  src = fetchPypi {
+    inherit pname version;
+    sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+  };
 
-    doCheck = false;
+  doCheck = false;
 
-    meta = with lib; {
-      homepage = https://github.com/pytoolz/toolz;
-      description = "List processing tools and functional utilities";
-      license = licenses.bsd3;
-      maintainers = with maintainers; [ fridh ];
-    };
+  meta = with lib; {
+    homepage = https://github.com/pytoolz/toolz;
+    description = "List processing tools and functional utilities";
+    license = licenses.bsd3;
+    maintainers = with maintainers; [ fridh ];
   };
-}
+};
 ```
 
 What happens here? The function `buildPythonPackage` is called and as argument
diff --git a/nixpkgs/doc/multiple-output.xml b/nixpkgs/doc/multiple-output.xml
index d18e282c5bd3..d0247e081f99 100644
--- a/nixpkgs/doc/multiple-output.xml
+++ b/nixpkgs/doc/multiple-output.xml
@@ -101,6 +101,13 @@
    contain <varname>$outputBin</varname> and <varname>$outputLib</varname> are
    also added. (See <xref linkend="multiple-output-file-type-groups" />.)
   </para>
+
+  <para>
+   In some cases it may be desirable to combine different outputs under a
+   single store path. A function <literal>symlinkJoin</literal> can be used to
+   do this. (Note that it may negate some closure size benefits of using a
+   multiple-output package.)
+  </para>
  </section>
  <section xml:id="sec-multiple-outputs-">
   <title>Writing a split derivation</title>
diff --git a/nixpkgs/doc/package-notes.xml b/nixpkgs/doc/package-notes.xml
index dfdada3d28c2..169f70283e6d 100644
--- a/nixpkgs/doc/package-notes.xml
+++ b/nixpkgs/doc/package-notes.xml
@@ -887,4 +887,31 @@ citrix_receiver.override {
    </para>
   </section>
  </section>
+ <section xml:id="dlib">
+  <title>DLib</title>
+
+  <para>
+    <link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which
+    provides several machine learning algorithms.
+  </para>
+
+  <section xml:id="compiling-without-avx-support">
+   <title>Compiling without AVX support</title>
+
+   <para>
+     Especially older CPUs don't support
+     <link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link>
+     (<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by DLib to
+     optimize their algorithms.
+   </para>
+
+   <para>
+    On the affected hardware errors like <literal>Illegal instruction</literal> will occur.
+    In those cases AVX support needs to be disabled:
+<programlisting>self: super: {
+  dlib = super.dlib.override { avxSupport = false; };
+}</programlisting>
+   </para>
+  </section>
+ </section>
 </chapter>
diff --git a/nixpkgs/doc/reviewing-contributions.xml b/nixpkgs/doc/reviewing-contributions.xml
index d31c6deb4909..6e3b6face3a5 100644
--- a/nixpkgs/doc/reviewing-contributions.xml
+++ b/nixpkgs/doc/reviewing-contributions.xml
@@ -189,14 +189,15 @@ $ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
      </listitem>
      <listitem>
       <para>
-       The <link xlink:href="https://github.com/madjar/nox">nox</link> tool can
-       be used to review a pull request content in a single command. It doesn't
-       rebase on a channel branch so it might trigger multiple source builds.
+       The
+       <link xlink:href="https://github.com/Mic92/nix-review">nix-review</link>
+       tool can be used to review a pull request content in a single command.
        <varname>PRNUMBER</varname> should be replaced by the number at the end
-       of the pull request title.
+       of the pull request title. You can also provide the full github pull
+       request url.
       </para>
 <screen>
-$ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
+$ nix-shell -p nix-review --run "nix-review pr PRNUMBER"
 </screen>
      </listitem>
     </itemizedlist>
diff --git a/nixpkgs/doc/stdenv.xml b/nixpkgs/doc/stdenv.xml
index a3990dec052f..74f815fc1d79 100644
--- a/nixpkgs/doc/stdenv.xml
+++ b/nixpkgs/doc/stdenv.xml
@@ -222,9 +222,10 @@ genericBuild
    </footnote>
    But even if one is not cross compiling, the platforms imply whether or not
    the dependency is needed at run-time or build-time, a concept that makes
-   perfect sense outside of cross compilation. For now, the run-time/build-time
-   distinction is just a hint for mental clarity, but in the future it perhaps
-   could be enforced.
+   perfect sense outside of cross compilation. By default, the
+   run-time/build-time distinction is just a hint for mental clarity, but with
+   <varname>strictDeps</varname> set it is mostly enforced even in the native
+   case.
   </para>
 
   <para>
@@ -348,7 +349,10 @@ let f(h, h + 1, i) = i + h
   <para>
    Overall, the unifying theme here is that propagation shouldn't be
    introducing transitive dependencies involving platforms the depending
-   package is unaware of. The offset bounds checking and definition of
+   package is unaware of. [One can imagine the dependending package asking for
+   dependencies with the platforms it knows about; other platforms it doesn't
+   know how to ask for. The platform description in that scenario is a kind of
+   unforagable capability.] The offset bounds checking and definition of
    <function>mapOffset</function> together ensure that this is the case.
    Discovering a new offset is discovering a new platform, and since those
    platforms weren't in the derivation "spec" of the needing package, they
@@ -2633,21 +2637,20 @@ addEnvHooks "$hostOffset" myBashFunction
        happens. It prevents nix from cleaning up the build environment
        immediately and allows the user to attach to a build environment using
        the <command>cntr</command> command. Upon build error it will print
-       instructions on how to use <command>cntr</command>, which can be used
-       to enter the environment for debugging. Installing cntr and
-       running the command will provide shell access to the build sandbox of
-       failed build. At <filename>/var/lib/cntr</filename> the sandboxed
-       filesystem is mounted. All commands and files of the system are still
-       accessible within the shell. To execute commands from the sandbox use
-       the cntr exec subcommand. Note that <command>cntr</command> also needs
-       to be executed on the machine that is doing the build, which might not
-       be the case when remote builders are enabled. <command>cntr</command> is
-       only supported on Linux-based platforms. To use it first add
-       <literal>cntr</literal> to your
-       <literal>environment.systemPackages</literal> on NixOS or alternatively
-       to the root user on non-NixOS systems. Then in the package that is
-       supposed to be inspected, add <literal>breakpointHook</literal> to
-       <literal>nativeBuildInputs</literal>.
+       instructions on how to use <command>cntr</command>, which can be used to
+       enter the environment for debugging. Installing cntr and running the
+       command will provide shell access to the build sandbox of failed build.
+       At <filename>/var/lib/cntr</filename> the sandboxed filesystem is
+       mounted. All commands and files of the system are still accessible
+       within the shell. To execute commands from the sandbox use the cntr exec
+       subcommand. Note that <command>cntr</command> also needs to be executed
+       on the machine that is doing the build, which might not be the case when
+       remote builders are enabled. <command>cntr</command> is only supported
+       on Linux-based platforms. To use it first add <literal>cntr</literal> to
+       your <literal>environment.systemPackages</literal> on NixOS or
+       alternatively to the root user on non-NixOS systems. Then in the package
+       that is supposed to be inspected, add <literal>breakpointHook</literal>
+       to <literal>nativeBuildInputs</literal>.
 <programlisting>
          nativeBuildInputs = [ breakpointHook ];
        </programlisting>
diff --git a/nixpkgs/doc/submitting-changes.xml b/nixpkgs/doc/submitting-changes.xml
index 4a6a2c634a58..bc090fd757ce 100644
--- a/nixpkgs/doc/submitting-changes.xml
+++ b/nixpkgs/doc/submitting-changes.xml
@@ -351,25 +351,24 @@ Additional information.
   </section>
 
   <section xml:id="submitting-changes-tested-compilation">
-   <title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title>
+   <title>Tested compilation of all pkgs that depend on this change using <command>nix-review</command></title>
 
    <para>
-    If you are updating a package's version, you can use nox to make sure all
-    packages that depend on the updated package still compile correctly. This
-    can be done using the nox utility. The <command>nox-review</command>
-    utility can look for and build all dependencies either based on uncommited
-    changes with the <literal>wip</literal> option or specifying a github pull
-    request number.
+    If you are updating a package's version, you can use nix-review to make
+    sure all packages that depend on the updated package still compile
+    correctly. The <command>nix-review</command> utility can look for and build
+    all dependencies either based on uncommited changes with the
+    <literal>wip</literal> option or specifying a github pull request number.
    </para>
 
    <para>
-    review uncommitted changes:
-<screen>nix-shell -p nox --run "nox-review wip"</screen>
+    review changes from pull request number 12345:
+<screen>nix-shell -p nix-review --run "nix-review pr 12345"</screen>
    </para>
 
    <para>
-    review changes from pull request number 12345:
-<screen>nix-shell -p nox --run "nox-review pr 12345"</screen>
+    review uncommitted changes:
+<screen>nix-shell -p nix-review --run "nix-review wip"</screen>
    </para>
   </section>