Document about packageOverrides

1 files changed, 83 insertions, 49 deletions

diff --git a/doc/packageconfig.xml b/doc/packageconfig.xml
index b5e57df71ffc..cebbd5bf7725 100644
--- a/doc/packageconfig.xml
+++ b/doc/packageconfig.xml
@@ -1,70 +1,104 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-packageconfig">
+	 xmlns:xlink="http://www.w3.org/1999/xlink"
+	 xml:id="chap-packageconfig">
 
 <title><filename>~/.nixpkgs/config.nix</filename>: global configuration</title>
 
+<section><title>Allow unfree software</title>
+
     <para>
       Nix packages can be configured to allow or deny certain options.
     </para>
 
     <para>
-        To apply the configuration edit <filename>~/.nixpkgs/config.nix</filename>
-        and set it like
+	To apply the configuration edit <filename>~/.nixpkgs/config.nix</filename>
+	and set it like
 <programlisting>{
   allowUnfree = true;
 }</programlisting>
-        and will allow the Nix package manager to install unfree licensed packages.
+	and will allow the Nix package manager to install unfree licensed packages.
 
-        The configuration as listed also applies to NixOS under <option>nixpkgs.config</option> set.
+	The configuration as listed also applies to NixOS under <option>nixpkgs.config</option> set.
     </para>
 
     <itemizedlist>
-        <listitem>
-            <para>
-                Allow installing of packages that are distributed under unfree license by setting
-                <programlisting>allowUnfree = true;</programlisting>
-                or deny them by setting it to <literal>false</literal>.
-            </para>
-            <para>
-                Same can be achieved by setting the environment variable:
-                <programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                Whenever unfree packages are not allowed, single packages can
-                still be allowed by a predicate function that accepts package
-                as an argument and should return a boolean:
-                <programlisting>allowUnfreePredicate = (pkg: ...);</programlisting>
-
-                Example to allow flash player only:
-                <programlisting>allowUnfreePredicate = (pkg: pkgs.lib.hasPrefix "flashplayer-" pkg.name);</programlisting>
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                Whenever unfree packages are not allowed, packages can still be
-                whitelisted by their license:
-                <programlisting>whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];</programlisting>
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                In addition to whitelisting licenses which are denied by the
-                <literal>allowUnfree</literal> setting, you can also explicitely
-                deny installation of packages which have a certain license:
-                <programlisting>blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];</programlisting>
-            </para>
-        </listitem>
+	<listitem>
+	    <para>
+		Allow installing of packages that are distributed under unfree license by setting
+		<programlisting>allowUnfree = true;</programlisting>
+		or deny them by setting it to <literal>false</literal>.
+	    </para>
+	    <para>
+		Same can be achieved by setting the environment variable:
+		<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
+	    </para>
+	</listitem>
+
+	<listitem>
+	    <para>
+		Whenever unfree packages are not allowed, single packages can
+		still be allowed by a predicate function that accepts package
+		as an argument and should return a boolean:
+		<programlisting>allowUnfreePredicate = (pkg: ...);</programlisting>
+
+		Example to allow flash player only:
+		<programlisting>allowUnfreePredicate = (pkg: pkgs.lib.hasPrefix "flashplayer-" pkg.name);</programlisting>
+	    </para>
+	</listitem>
+
+	<listitem>
+	    <para>
+		Whenever unfree packages are not allowed, packages can still be
+		whitelisted by their license:
+		<programlisting>whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];</programlisting>
+	    </para>
+	</listitem>
+
+	<listitem>
+	    <para>
+		In addition to whitelisting licenses which are denied by the
+		<literal>allowUnfree</literal> setting, you can also explicitely
+		deny installation of packages which have a certain license:
+		<programlisting>blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];</programlisting>
+	    </para>
+	</listitem>
     </itemizedlist>
 
     <para>
-        A complete list of licenses can be found in the file
-        <filename>lib/licenses.nix</filename> of the nix package tree.
+	A complete list of licenses can be found in the file
+	<filename>lib/licenses.nix</filename> of the nix package tree.
     </para>
+</section>
+
+<section><title>Overriding existing packages</title>
+
+<para>
+  <filename>~/.nixpkgs/config.nix</filename> enables the user to
+  override package names without creating a fork of the Nixpkgs.
+  This is accomplished by defining a function called
+  <varname>packageOverrides</varname>.  It takes the set of
+  packages, usually called <varname>pkgs</varname>, and returns a
+  modified set of packages.
+</para>
+<para>
+  Here is an example.  Say we want to install
+  <varname>xbmc</varname> but we want to use another Python
+  version when running <varname>xbmc</varname>.
+
+<programlisting>
+packageOverrides = pkgs: rec {
+  xbmc = pkgs.xbmc.override {
+    python = pkgs.python26;
+  };
+};
+</programlisting>
+
+  Further information is available at the <command
+  xlink:href="https://nixos.org/wiki/Nix_Modifying_Packages">Nix
+  wiki</command>
+
+</para>
+
+</section>
 
-</chapter>
\ No newline at end of file
+</chapter>