Merge remote-tracking branch 'origin/master'

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
+  derivation attributes, the results of derivations.
-  set.
+ </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 ; };

doc/overlays.xml

@@ -16,41 +16,72 @@
  <section xml:id="sec-overlays-install">
   <title>Installing overlays</title>
 
+  <para>
+   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>
+
+  <section xml:id="sec-overlays-argument">
+   <title>Set overlays in NixOS or Nix expressions</title>
+
+   <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>
+    The list of overlays can be passed explicitly when importing nixpkgs, for
+    example <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
+    }</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>
-   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
+       First, if an
-      itself is given, then that is used.
+       <link xlink:href="#sec-overlays-argument"><varname>overlays</varname>
-     </para>
+       argument</link> to the nixpkgs function itself is given, then that is
-     <para>
+       used and no path lookup will be performed.
-      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>
+       Otherwise, if the Nix path entry
-      exists, we look for overlays at that path, as described below.
+       <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
+       See the section on <literal>NIX_PATH</literal> in the Nix manual for
-      details on how to set a value 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
+       <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look
-      overlays at that path, as described below. It is an error if both exist.
+       for overlays at that path, as described below. It is an error if both
+       exist.
       </para>
      </listitem>
     </orderedlist>
@@ -89,19 +120,19 @@
    </para>
 
    <para>
-   On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
+    Because overlays that are set in NixOS configuration do not affect
-   option, if present, is passed to the system Nixpkgs directly as an argument.
+    non-NixOS operations such as <literal>nix-env</literal>, the
-   Note that this does not affect the overlays for non-NixOS operations (e.g.
+    <filename>overlays.nix</filename> option provides a convenient way to use
-   <literal>nix-env</literal>), which are looked up independently.
+    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>
+<!-- TODO: Example of sharing overlays between NixOS configuration
-   The <filename>overlays.nix</filename> option therefore provides a convenient
+     and configuration lookup. Also reference the example
-   way to use the same overlays for a NixOS system configuration and user
+     from the sec-overlays-argument paragraph about NixOS.
-   configuration: the same file can be used as
+ -->
-   <filename>overlays.nix</filename> and imported as the value of
+  </section>
-   <literal>nixpkgs.overlays</literal>.
-  </para>
  </section>
 <!--============================================================-->
  <section xml:id="sec-overlays-definition">

pkgs/top-level/stage.nix

@@ -56,7 +56,7 @@
 , # A list of overlays (Additional `self: super: { .. }` customization
   # functions) to be fixed together in the produced package set
   overlays
-}:
+} @args:
 
 let
   stdenvAdapters = self: super:
@@ -159,6 +159,19 @@ let
         };
       };
     };
+
+    # Extend the package set with zero or more overlays. This preserves
+    # preexisting overlays. Prefer to initialize with the right overlays
+    # in one go when calling Nixpkgs, for performance and simplicity.
+    appendOverlays = extraOverlays:
+      import ./stage.nix (args // { overlays = args.overlays ++ extraOverlays; });
+
+    # Extend the package set with a single overlay. This preserves
+    # preexisting overlays. Prefer to initialize with the right overlays
+    # in one go when calling Nixpkgs, for performance and simplicity.
+    # Prefer appendOverlays if used repeatedly.
+    extend = f: self.appendOverlays [f];
+
   };
 
   # The complete chain of package set builders, applied from top to bottom.