diff options
Diffstat (limited to 'doc/functions.xml')
| -rw-r--r-- | doc/functions.xml | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 908e9571ed69..3850e58c0168 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -52,6 +52,20 @@ in ...</programlisting> It's equivalent to <varname>pkgs</varname> in the above example. </para> + <para> + Note that in previous versions of nixpkgs, this method replaced any changes from <link + linkend="sec-modify-via-packageOverrides">config.packageOverrides</link>, + along with that from previous calls if this function was called repeatedly. + Now those previous changes will be preserved so this function can be "chained" meaningfully. + To recover the old behavior, make sure <varname>config.packageOverrides</varname> is unset, + and call this only once off a "freshly" imported nixpkgs: + + <programlisting>let + pkgs = import <nixpkgs> { config: {}; }; + newpkgs = pkgs.overridePackages ...; +in ...</programlisting> + </para> + </section> <section xml:id="sec-pkg-override"> @@ -85,10 +99,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 |