diff options
| -rw-r--r-- | doc/functions.xml | 61 | ||||
| -rw-r--r-- | lib/customisation.nix | 22 | ||||
| -rw-r--r-- | pkgs/stdenv/generic/default.nix | 1 |
3 files changed, 74 insertions, 10 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 908e9571ed69..f5fb90921bfa 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -85,10 +85,71 @@ in ...</programlisting> </section> +<section xml:id="sec-pkg-overrideAttrs"> + <title><pkg>.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><pkg>.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 diff --git a/lib/customisation.nix b/lib/customisation.nix index efe82d786600..3e6e279824be 100644 --- a/lib/customisation.nix +++ b/lib/customisation.nix @@ -56,16 +56,18 @@ rec { ff = f origArgs; overrideWith = newArgs: origArgs // (if builtins.isFunction newArgs then newArgs origArgs else newArgs); in - if builtins.isAttrs ff then (ff // - { override = newArgs: makeOverridable f (overrideWith newArgs); - overrideDerivation = fdrv: - makeOverridable (args: overrideDerivation (f args) fdrv) origArgs; - }) - else if builtins.isFunction ff then - { override = newArgs: makeOverridable f (overrideWith newArgs); - __functor = self: ff; - overrideDerivation = throw "overrideDerivation not yet supported for functors"; - } + if builtins.isAttrs ff then (ff // { + override = newArgs: makeOverridable f (overrideWith newArgs); + overrideDerivation = fdrv: + makeOverridable (args: overrideDerivation (f args) fdrv) origArgs; + ${if ff ? overrideAttrs then "overrideAttrs" else null} = fdrv: + makeOverridable (args: (f args).overrideAttrs fdrv) origArgs; + }) + else if builtins.isFunction ff then { + override = newArgs: makeOverridable f (overrideWith newArgs); + __functor = self: ff; + overrideDerivation = throw "overrideDerivation not yet supported for functors"; + } else ff; diff --git a/pkgs/stdenv/generic/default.nix b/pkgs/stdenv/generic/default.nix index e71c2f770b9b..489b6cbb426a 100644 --- a/pkgs/stdenv/generic/default.nix +++ b/pkgs/stdenv/generic/default.nix @@ -227,6 +227,7 @@ let outputs = outputs'; } else { })))) ( { + overrideAttrs = f: mkDerivation (attrs // (f attrs)); # The meta attribute is passed in the resulting attribute set, # but it's not part of the actual derivation, i.e., it's not # passed to the builder and is not a dependency. But since we |