diff options
Diffstat (limited to 'doc/functions/overrides.xml')
| -rw-r--r-- | doc/functions/overrides.xml | 286 |
1 files changed, 142 insertions, 144 deletions
diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml index dc81e37950656..99e2a63631a77 100644 --- a/doc/functions/overrides.xml +++ b/doc/functions/overrides.xml @@ -2,28 +2,28 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-overrides"> - <title>Overriding</title> + <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> + <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><pkg>.override</title> + <section xml:id="sec-pkg-override"> + <title><pkg>.override</title> - <para> - The function <varname>override</varname> is usually available for all the - derivations in the nixpkgs expression (<varname>pkgs</varname>). - </para> + <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> + It is used to override the arguments passed to a function. + </para> - <para> - Example usages: + <para> + Example usages: <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> <programlisting> import pkgs.path { overlays = [ (self: super: { @@ -35,105 +35,103 @@ mypkg = pkgs.callPackage ./mypkg.nix { mydep = pkgs.mydep.override { ... }; } </programlisting> - </para> + </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> + <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><pkg>.overrideAttrs</title> + <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> + 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: + <para> + Example usage: <programlisting> helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { separateDebugInfo = true; }); </programlisting> - </para> + </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> + 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> + <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 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> + <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> - 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. + 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> - Example usage: + 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"; @@ -144,62 +142,62 @@ mySed = pkgs.gnused.overrideDerivation (oldAttrs: { patches = []; }); </programlisting> - </para> + </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> + 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> - The argument <varname>oldAttrs</varname> is used to refer to the attribute - set of the original derivation. + 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> - <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> + <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> + 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: + <para> + Example usage: <programlisting> f = { a, b }: { result = a+b; }; c = lib.makeOverridable f { a = 1; b = 2; }; </programlisting> - </para> + </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> 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> + <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> |