summary refs log tree commit diff
path: root/doc/functions.xml
diff options
context:
space:
mode:
authorLuca Bruno <lethalman88@gmail.com>2015-06-24 22:57:37 +0200
committerLuca Bruno <lethalman88@gmail.com>2015-06-26 15:08:11 +0200
commit7f5f9072ad487ff6b3bffce716943d46fb167813 (patch)
treee636521c997ee5bc74302fd773db8713af60a741 /doc/functions.xml
parentdf92d1c711434ab864115597edd00bd4fa0d805c (diff)
downloadnixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.tar
nixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.tar.gz
nixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.tar.bz2
nixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.tar.lz
nixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.tar.xz
nixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.tar.zst
nixlib-7f5f9072ad487ff6b3bffce716943d46fb167813.zip
all-packages.nix: Add pkgs.overridePackages
Diffstat (limited to 'doc/functions.xml')
-rw-r--r--doc/functions.xml57
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/functions.xml b/doc/functions.xml
new file mode 100644
index 000000000000..16f4f262a25f
--- /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>