Merge master into staging-next

3 files changed, 128 insertions, 88 deletions

diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml
index 99e2a63631a7..1bd90d2a0c76 100644
--- a/doc/functions/overrides.xml
+++ b/doc/functions/overrides.xml
@@ -6,8 +6,14 @@
 
  <para>
   Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
-  derivation attributes, the results of derivations or even the whole package
-  set.
+  derivation attributes, the results of derivations.
+ </para>
+
+ <para>
+  These functions are used to make changes to packages, returning only single
+  packages. <link xlink:href="#chap-overlays">Overlays</link>, on the other
+  hand, can be used to combine the overridden packages across the entire
+  package set of Nixpkgs.
  </para>
 
  <section xml:id="sec-pkg-override">
@@ -25,6 +31,9 @@
   <para>
    Example usages:
 <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
+<!-- TODO: move below programlisting to a new section about extending and overlays
+           and reference it
+  -->
 <programlisting>
 import pkgs.path { overlays = [ (self: super: {
   foo = super.foo.override { barSupport = true ; };
@@ -86,11 +95,11 @@ helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec {
     in this case, as it overrides only the attributes of the final derivation.
     It is for this reason that <varname>overrideAttrs</varname> should be
     preferred in (almost) all cases to <varname>overrideDerivation</varname>,
-    i.e. to allow using <varname>sdenv.mkDerivation</varname> to process input
+    i.e. to allow using <varname>stdenv.mkDerivation</varname> to process input
     arguments, as well as the fact that it is easier to use (you can use the
     same attribute names you see in your Nix code, instead of the ones
     generated (e.g. <varname>buildInputs</varname> vs
-    <varname>nativeBuildInputs</varname>, and involves less typing.
+    <varname>nativeBuildInputs</varname>), and it involves less typing).
    </para>
   </note>
  </section>
diff --git a/doc/overlays.xml b/doc/overlays.xml
index 2decf9febe80..90dd163072d3 100644
--- a/doc/overlays.xml
+++ b/doc/overlays.xml
@@ -17,91 +17,122 @@
   <title>Installing overlays</title>
 
   <para>
-   The list of overlays is determined as follows.
+   The list of overlays can be set either explicitly in a Nix expression, or
+   through <literal>&lt;nixpkgs-overlays></literal> or user configuration
+   files.
   </para>
 
-  <para>
-   If the <varname>overlays</varname> argument is not provided explicitly, we
-   look for overlays in a path. The path is determined as follows:
-   <orderedlist>
-    <listitem>
-     <para>
-      First, if an <varname>overlays</varname> argument to the nixpkgs function
-      itself is given, then that is used.
-     </para>
-     <para>
-      This can be passed explicitly when importing nipxkgs, for example
-      <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
-      }</literal>.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      Otherwise, if the Nix path entry <literal>&lt;nixpkgs-overlays></literal>
-      exists, we look for overlays at that path, as described below.
-     </para>
-     <para>
-      See the section on <literal>NIX_PATH</literal> in the Nix manual for more
-      details on how to set a value for
-      <literal>&lt;nixpkgs-overlays>.</literal>
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
-      <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for
-      overlays at that path, as described below. It is an error if both exist.
-     </para>
-    </listitem>
-   </orderedlist>
-  </para>
+  <section xml:id="sec-overlays-argument">
+   <title>Set overlays in NixOS or Nix expressions</title>
 
-  <para>
-   If we are looking for overlays at a path, then there are two cases:
-   <itemizedlist>
-    <listitem>
-     <para>
-      If the path is a file, then the file is imported as a Nix expression and
-      used as the list of overlays.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      If the path is a directory, then we take the content of the directory,
-      order it lexicographically, and attempt to interpret each as an overlay
-      by:
-      <itemizedlist>
-       <listitem>
-        <para>
-         Importing the file, if it is a <literal>.nix</literal> file.
-        </para>
-       </listitem>
-       <listitem>
-        <para>
-         Importing a top-level <filename>default.nix</filename> file, if it is
-         a directory.
-        </para>
-       </listitem>
-      </itemizedlist>
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
+   <para>
+    On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
+    option, if present, is passed to the system Nixpkgs directly as an
+    argument. Note that this does not affect the overlays for non-NixOS
+    operations (e.g. <literal>nix-env</literal>), which are
+    <link xlink:href="#sec-overlays-lookup">looked</link> up independently.
+   </para>
 
-  <para>
-   On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
-   option, if present, is passed to the system Nixpkgs directly as an argument.
-   Note that this does not affect the overlays for non-NixOS operations (e.g.
-   <literal>nix-env</literal>), which are looked up independently.
-  </para>
+   <para>
+    The list of overlays can be passed explicitly when importing nixpkgs, for
+    example <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
+    }</literal>.
+   </para>
 
-  <para>
-   The <filename>overlays.nix</filename> option therefore provides a convenient
-   way to use the same overlays for a NixOS system configuration and user
-   configuration: the same file can be used as
-   <filename>overlays.nix</filename> and imported as the value of
-   <literal>nixpkgs.overlays</literal>.
-  </para>
+   <para>
+    Further overlays can be added by calling the <literal>pkgs.extend</literal>
+    or <literal>pkgs.appendOverlays</literal>, although it is often preferable
+    to avoid these functions, because they recompute the Nixpkgs fixpoint,
+    which is somewhat expensive to do.
+   </para>
+  </section>
+
+  <section xml:id="sec-overlays-lookup">
+   <title>Install overlays via configuration lookup</title>
+
+   <para>
+    The list of overlays is determined as follows.
+   </para>
+
+   <para>
+    <orderedlist>
+     <listitem>
+      <para>
+       First, if an
+       <link xlink:href="#sec-overlays-argument"><varname>overlays</varname>
+       argument</link> to the nixpkgs function itself is given, then that is
+       used and no path lookup will be performed.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Otherwise, if the Nix path entry
+       <literal>&lt;nixpkgs-overlays></literal> exists, we look for overlays at
+       that path, as described below.
+      </para>
+      <para>
+       See the section on <literal>NIX_PATH</literal> in the Nix manual for
+       more details on how to set a value for
+       <literal>&lt;nixpkgs-overlays>.</literal>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
+       <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look
+       for overlays at that path, as described below. It is an error if both
+       exist.
+      </para>
+     </listitem>
+    </orderedlist>
+   </para>
+
+   <para>
+    If we are looking for overlays at a path, then there are two cases:
+    <itemizedlist>
+     <listitem>
+      <para>
+       If the path is a file, then the file is imported as a Nix expression and
+       used as the list of overlays.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       If the path is a directory, then we take the content of the directory,
+       order it lexicographically, and attempt to interpret each as an overlay
+       by:
+       <itemizedlist>
+        <listitem>
+         <para>
+          Importing the file, if it is a <literal>.nix</literal> file.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          Importing a top-level <filename>default.nix</filename> file, if it is
+          a directory.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+
+   <para>
+    Because overlays that are set in NixOS configuration do not affect
+    non-NixOS operations such as <literal>nix-env</literal>, the
+    <filename>overlays.nix</filename> option provides a convenient way to use
+    the same overlays for a NixOS system configuration and user configuration:
+    the same file can be used as <filename>overlays.nix</filename> and imported
+    as the value of <literal>nixpkgs.overlays</literal>.
+   </para>
+
+<!-- TODO: Example of sharing overlays between NixOS configuration
+     and configuration lookup. Also reference the example
+     from the sec-overlays-argument paragraph about NixOS.
+ -->
+  </section>
  </section>
 <!--============================================================-->
  <section xml:id="sec-overlays-definition">
diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index dad28d3ec8b2..49f94f3bd5d2 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -681,10 +681,10 @@ overrides = self: super: rec {
   </para>
 
   <para>
-   The python plugin allows the addition of extra libraries. For instance, the
-   <literal>inotify.py</literal> script in weechat-scripts requires D-Bus or
-   libnotify, and the <literal>fish.py</literal> script requires pycrypto. To
-   use these scripts, use the <literal>python</literal> plugin's
+   The python and perl plugins allows the addition of extra libraries. For
+   instance, the <literal>inotify.py</literal> script in weechat-scripts
+   requires D-Bus or libnotify, and the <literal>fish.py</literal> script
+   requires pycrypto. To use these scripts, use the plugin's
    <literal>withPackages</literal> attribute:
 <programlisting>weechat.override { configure = {availablePlugins, ...}: {
     plugins = with availablePlugins; [