From 7f5f9072ad487ff6b3bffce716943d46fb167813 Mon Sep 17 00:00:00 2001
From: Luca Bruno <lethalman88@gmail.com>
Date: Wed, 24 Jun 2015 22:57:37 +0200
Subject: [PATCH] all-packages.nix: Add pkgs.overridePackages

---
 doc/functions.xml               | 57 +++++++++++++++++++++++++++++++++
 doc/manual.xml                  |  1 +
 pkgs/top-level/all-packages.nix | 21 ++++++++++--
 3 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 doc/functions.xml

diff --git a/doc/functions.xml b/doc/functions.xml
new file mode 100644
index 00000000000..16f4f262a25
--- /dev/null
+++ b/doc/functions.xml
@@ -0,0 +1,57 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xlink="http://www.w3.org/1999/xlink"
+	 xml:id="chap-functions">
+
+<title>Functions reference</title>
+
+<para>
+  The nixpkgs repository has several utility functions to manipulate Nix expressions.
+</para>
+
+<section xml:id="sec-pkgs-overridePackages">
+  <title>pkgs.overridePackages</title>
+
+  <para>
+    This function inside the nixpkgs expression (<varname>pkgs</varname>)
+    can be used to override the set of packages itself.
+  </para>
+  <para>
+    Warning: this function is expensive and must not be used from within
+    the nixpkgs repository.
+  </para>
+  <para>
+    Example usage:
+
+    <programlisting>let
+  pkgs = import &lt;nixpkgs&gt; {};
+  newpkgs = pkgs.overridePackages (self: super: {
+    foo = super.foo.override { ... };
+  };
+in ...</programlisting>
+  </para>
+
+  <para>
+    The resulting <varname>newpkgs</varname> will have the new <varname>foo</varname>
+    expression, and all other expressions depending on <varname>foo</varname> will also
+    use the new <varname>foo</varname> expression.
+  </para>
+
+  <para>
+    The behavior of this function is similar to <link 
+    linkend="sec-modify-via-packageOverrides">config.packageOverrides</link>.
+  </para>
+
+  <para>
+    The <varname>self</varname> parameter refers to the final package set with the
+    applied overrides. Using this parameter may lead to infinite recursion if not
+    used consciously.
+  </para>
+
+  <para>
+    The <varname>super</varname> parameter refers to the old package set.
+    It's equivalent to <varname>pkgs</varname> in the above example.
+  </para>
+
+</section>
+
+</chapter>
diff --git a/doc/manual.xml b/doc/manual.xml
index a6400c98d6e..11f37184e6d 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -13,6 +13,7 @@
   <xi:include href="quick-start.xml" />
   <xi:include href="stdenv.xml" />
   <xi:include href="packageconfig.xml" />
+  <xi:include href="functions.xml" />
   <xi:include href="meta.xml" />
   <xi:include href="language-support.xml" />
   <xi:include href="package-notes.xml" />
diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix
index e7d5caa4471..876db4b0236 100644
--- a/pkgs/top-level/all-packages.nix
+++ b/pkgs/top-level/all-packages.nix
@@ -100,6 +100,8 @@ let
   # ... pkgs.foo ...").
   pkgs = applyGlobalOverrides (config.packageOverrides or (pkgs: {}));
 
+  mkOverrides = pkgsOrig: overrides: overrides //
+        (lib.optionalAttrs (pkgsOrig.stdenv ? overrides && crossSystem == null) (pkgsOrig.stdenv.overrides pkgsOrig));
 
   # Return the complete set of packages, after applying the overrides
   # returned by the `overrider' function (see above).  Warning: this
@@ -110,8 +112,7 @@ let
       # in the case of cross-building, or otherwise the basic
       # overrided packages will not be built with the crossStdenv
       # adapter.
-      overrides = overrider pkgsOrig //
-        (lib.optionalAttrs (pkgsOrig.stdenv ? overrides && crossSystem == null) (pkgsOrig.stdenv.overrides pkgsOrig));
+      overrides = mkOverrides pkgsOrig (overrider pkgsOrig);
 
       # The un-overriden packages, passed to `overrider'.
       pkgsOrig = pkgsFun pkgs {};
@@ -142,6 +143,22 @@ let
 
   newScope = extra: lib.callPackageWith (defaultScope // extra);
 
+  # Easily override this package set.
+  # Warning: this function is very expensive and must not be used
+  # from within the nixpkgs repository.
+  #
+  # Example:
+  #  pkgs.overridePackages (self: super: {
+  #    foo = super.foo.override { ... };
+  #  }
+  #
+  # The result is `pkgs' where all the derivations depending on `foo'
+  # will use the new version.
+  overridePackages = f:
+    let
+      newpkgs = pkgsFun newpkgs overrides;
+      overrides = mkOverrides pkgs (f newpkgs pkgs);
+    in newpkgs;
 
   # Override system. This is useful to build i686 packages on x86_64-linux.
   forceSystem = system: kernel: (import ./all-packages.nix) {