1 files changed, 205 insertions, 0 deletions
diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml
new file mode 100644
index 000000000000..dc81e3795065
--- /dev/null
+++ b/doc/functions/overrides.xml
@@ -0,0 +1,205 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-overrides">
+  <title>Overriding</title>
+
+  <para>
+   Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
+   derivation attributes, the results of derivations or even the whole package
+   set.
+  </para>
+
+  <section xml:id="sec-pkg-override">
+   <title>&lt;pkg&gt;.override</title>
+
+   <para>
+    The function <varname>override</varname> is usually available for all the
+    derivations in the nixpkgs expression (<varname>pkgs</varname>).
+   </para>
+
+   <para>
+    It is used to override the arguments passed to a function.
+   </para>
+
+   <para>
+    Example usages:
+<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
+<programlisting>
+import pkgs.path { overlays = [ (self: super: {
+  foo = super.foo.override { barSupport = true ; };
+  })]};
+</programlisting>
+<programlisting>
+mypkg = pkgs.callPackage ./mypkg.nix {
+  mydep = pkgs.mydep.override { ... };
+  }
+</programlisting>
+   </para>
+
+   <para>
+    In the first example, <varname>pkgs.foo</varname> is the result of a
+    function call with some default arguments, usually a derivation. Using
+    <varname>pkgs.foo.override</varname> will call the same function with the
+    given new arguments.
+   </para>
+  </section>
+
+  <section xml:id="sec-pkg-overrideAttrs">
+   <title>&lt;pkg&gt;.overrideAttrs</title>
+
+   <para>
+    The function <varname>overrideAttrs</varname> allows overriding the
+    attribute set passed to a <varname>stdenv.mkDerivation</varname> call,
+    producing a new derivation based on the original one. This function is
+    available on all derivations produced by the
+    <varname>stdenv.mkDerivation</varname> function, which is most packages in
+    the nixpkgs expression <varname>pkgs</varname>.
+   </para>
+
+   <para>
+    Example usage:
+<programlisting>
+helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec {
+  separateDebugInfo = true;
+});
+</programlisting>
+   </para>
+
+   <para>
+    In the above example, the <varname>separateDebugInfo</varname> attribute is
+    overridden to be true, thus building debug info for
+    <varname>helloWithDebug</varname>, while all other attributes will be
+    retained from the original <varname>hello</varname> package.
+   </para>
+
+   <para>
+    The argument <varname>oldAttrs</varname> is conventionally used to refer to
+    the attr set originally passed to <varname>stdenv.mkDerivation</varname>.
+   </para>
+
+   <note>
+    <para>
+     Note that <varname>separateDebugInfo</varname> is processed only by the
+     <varname>stdenv.mkDerivation</varname> function, not the generated, raw
+     Nix derivation. Thus, using <varname>overrideDerivation</varname> will not
+     work in this case, as it overrides only the attributes of the final
+     derivation. It is for this reason that <varname>overrideAttrs</varname>
+     should be preferred in (almost) all cases to
+     <varname>overrideDerivation</varname>, i.e. to allow using
+     <varname>sdenv.mkDerivation</varname> to process input arguments, as well
+     as the fact that it is easier to use (you can use the same attribute names
+     you see in your Nix code, instead of the ones generated (e.g.
+     <varname>buildInputs</varname> vs <varname>nativeBuildInputs</varname>,
+     and involves less typing.
+    </para>
+   </note>
+  </section>
+
+  <section xml:id="sec-pkg-overrideDerivation">
+   <title>&lt;pkg&gt;.overrideDerivation</title>
+
+   <warning>
+    <para>
+     You should prefer <varname>overrideAttrs</varname> in almost all cases,
+     see its documentation for the reasons why.
+     <varname>overrideDerivation</varname> is not deprecated and will continue
+     to work, but is less nice to use and does not have as many abilities as
+     <varname>overrideAttrs</varname>.
+    </para>
+   </warning>
+
+   <warning>
+    <para>
+     Do not use this function in Nixpkgs as it evaluates a Derivation before
+     modifying it, which breaks package abstraction and removes error-checking
+     of function arguments. In addition, this evaluation-per-function
+     application incurs a performance penalty, which can become a problem if
+     many overrides are used. It is only intended for ad-hoc customisation,
+     such as in <filename>~/.config/nixpkgs/config.nix</filename>.
+    </para>
+   </warning>
+
+   <para>
+    The function <varname>overrideDerivation</varname> creates a new derivation
+    based on an existing one by overriding the original's attributes with the
+    attribute set produced by the specified function. This function is
+    available on all derivations defined using the
+    <varname>makeOverridable</varname> function. Most standard
+    derivation-producing functions, such as
+    <varname>stdenv.mkDerivation</varname>, are defined using this function,
+    which means most packages in the nixpkgs expression,
+    <varname>pkgs</varname>, have this function.
+   </para>
+
+   <para>
+    Example usage:
+<programlisting>
+mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
+  name = "sed-4.2.2-pre";
+  src = fetchurl {
+    url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
+    sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k";
+  };
+  patches = [];
+});
+</programlisting>
+   </para>
+
+   <para>
+    In the above example, the <varname>name</varname>, <varname>src</varname>,
+    and <varname>patches</varname> of the derivation will be overridden, while
+    all other attributes will be retained from the original derivation.
+   </para>
+
+   <para>
+    The argument <varname>oldAttrs</varname> is used to refer to the attribute
+    set of the original derivation.
+   </para>
+
+   <note>
+    <para>
+     A package's attributes are evaluated *before* being modified by the
+     <varname>overrideDerivation</varname> function. For example, the
+     <varname>name</varname> attribute reference in <varname>url =
+     "mirror://gnu/hello/${name}.tar.gz";</varname> is filled-in *before* the
+     <varname>overrideDerivation</varname> function modifies the attribute set.
+     This means that overriding the <varname>name</varname> attribute, in this
+     example, *will not* change the value of the <varname>url</varname>
+     attribute. Instead, we need to override both the <varname>name</varname>
+     *and* <varname>url</varname> attributes.
+    </para>
+   </note>
+  </section>
+
+  <section xml:id="sec-lib-makeOverridable">
+   <title>lib.makeOverridable</title>
+
+   <para>
+    The function <varname>lib.makeOverridable</varname> is used to make the
+    result of a function easily customizable. This utility only makes sense for
+    functions that accept an argument set and return an attribute set.
+   </para>
+
+   <para>
+    Example usage:
+<programlisting>
+f = { a, b }: { result = a+b; };
+c = lib.makeOverridable f { a = 1; b = 2; };
+</programlisting>
+   </para>
+
+   <para>
+    The variable <varname>c</varname> is the value of the <varname>f</varname>
+    function applied with some default arguments. Hence the value of
+    <varname>c.result</varname> is <literal>3</literal>, in this example.
+   </para>
+
+   <para>
+    The variable <varname>c</varname> however also has some additional
+    functions, like <link linkend="sec-pkg-override">c.override</link> which
+    can be used to override the default arguments. In this example the value of
+    <varname>(c.override { a = 4; }).result</varname> is 6.
+   </para>
+  </section>
+ </section>