From 39b64b52ed349bb7b6f26f50013335d76d1605f6 Mon Sep 17 00:00:00 2001
From: Aneesh Agrawal <aneeshusa@gmail.com>
Date: Fri, 19 Aug 2016 22:21:32 -0400
Subject: mkDerivation: add overrideAttrs function

This is similar to `overrideDerivation`, but overrides the arguments to
`mkDerivation` instead of the underlying `derivation` call.

Also update `makeOverridable` so that uses of `overrideAttrs` can be
followed by `override` and `overrideDerivation`, i.e. they can be
mix-and-matched.
---
 doc/functions.xml | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

(limited to 'doc')

diff --git a/doc/functions.xml b/doc/functions.xml
index 908e9571ed6..f5fb90921bf 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -85,9 +85,70 @@ in ...</programlisting>
 
 </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
+    overriden 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
-- 
cgit 1.4.1