diff options
Diffstat (limited to 'doc/functions.xml')
-rw-r--r-- | doc/functions.xml | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 908e9571ed699..f5fb90921bfa8 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 |