1 files changed, 86 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml b/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml
new file mode 100644
index 000000000000..03b5bb53197b
--- /dev/null
+++ b/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml
@@ -0,0 +1,86 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="sec-customising-packages">
+ <title>Customising Packages</title>
+
+ <para>
+  Some packages in Nixpkgs have options to enable or disable optional
+  functionality or change other aspects of the package. For instance, the
+  Firefox wrapper package (which provides Firefox with a set of plugins such as
+  the Adobe Flash player) has an option to enable the Google Talk plugin. It
+  can be set in <filename>configuration.nix</filename> as follows: <filename>
+  nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>
+ </para>
+
+ <warning>
+  <para>
+   Unfortunately, Nixpkgs currently lacks a way to query available
+   configuration options.
+  </para>
+ </warning>
+
+ <para>
+  Apart from high-level options, it’s possible to tweak a package in almost
+  arbitrary ways, such as changing or disabling dependencies of a package. For
+  instance, the Emacs package in Nixpkgs by default has a dependency on GTK+ 2.
+  If you want to build it against GTK+ 3, you can specify that as follows:
+<programlisting>
+<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+</programlisting>
+  The function <varname>override</varname> performs the call to the Nix
+  function that produces Emacs, with the original arguments amended by the set
+  of arguments specified by you. So here the function argument
+  <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing
+  Emacs to depend on GTK+ 3. (The parentheses are necessary because in Nix,
+  function application binds more weakly than list construction, so without
+  them, <xref linkend="opt-environment.systemPackages"/> would be a list with
+  two elements.)
+ </para>
+
+ <para>
+  Even greater customisation is possible using the function
+  <varname>overrideAttrs</varname>. While the <varname>override</varname>
+  mechanism above overrides the arguments of a package function,
+  <varname>overrideAttrs</varname> allows changing the
+  <emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
+  This permits changing any aspect of the package, such as the source code. For
+  instance, if you want to override the source code of Emacs, you can say:
+<programlisting>
+<xref linkend="opt-environment.systemPackages"/> = [
+  (pkgs.emacs.overrideAttrs (oldAttrs: {
+    name = "emacs-25.0-pre";
+    src = /path/to/my/emacs/tree;
+  }))
+];
+</programlisting>
+  Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by
+  <varname>pkgs.emacs</varname> and produces a new derivation in which the
+  original’s <literal>name</literal> and <literal>src</literal> attribute
+  have been replaced by the given values by re-calling
+  <literal>stdenv.mkDerivation</literal>. The original attributes are
+  accessible via the function argument, which is conventionally named
+  <varname>oldAttrs</varname>.
+ </para>
+
+ <para>
+  The overrides shown above are not global. They do not affect the original
+  package; other packages in Nixpkgs continue to depend on the original rather
+  than the customised package. This means that if another package in your
+  system depends on the original package, you end up with two instances of the
+  package. If you want to have everything depend on your customised instance,
+  you can apply a <emphasis>global</emphasis> override as follows:
+<screen>
+nixpkgs.config.packageOverrides = pkgs:
+  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+  };
+</screen>
+  The effect of this definition is essentially equivalent to modifying the
+  <literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in
+  Nixpkgs that depends on <literal>emacs</literal> will be passed your
+  customised instance. (However, the value <literal>pkgs.emacs</literal> in
+  <varname>nixpkgs.config.packageOverrides</varname> refers to the original
+  rather than overridden instance, to prevent an infinite recursion.)
+ </para>
+</section>