diff options
author | Graham Christensen <graham@grahamc.com> | 2018-10-02 13:52:21 -0400 |
---|---|---|
committer | Graham Christensen <graham@grahamc.com> | 2018-10-02 13:52:21 -0400 |
commit | f200a322c4f55c853d6543e47ebdbe7457262a61 (patch) | |
tree | c9a24290abc66ad508dcb40198d0b6da553410b6 /doc | |
parent | 18b468ed8186131d5a8a6590ff10253e12d0195a (diff) | |
download | nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.tar nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.tar.gz nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.tar.bz2 nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.tar.lz nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.tar.xz nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.tar.zst nixlib-f200a322c4f55c853d6543e47ebdbe7457262a61.zip |
nixpkgs docs: move overrides to its own file
Diffstat (limited to 'doc')
-rw-r--r-- | doc/functions.xml | 202 | ||||
-rw-r--r-- | doc/functions/overrides.xml | 205 |
2 files changed, 206 insertions, 201 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 8223a8b0531c..754159bff4f1 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -7,208 +7,8 @@ The nixpkgs repository has several utility functions to manipulate Nix expressions. </para> - <section xml:id="sec-overrides"> - <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> - - <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> - It is used to override the arguments passed to a function. - </para> - - <para> - Example usages: -<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> -<programlisting> -import pkgs.path { overlays = [ (self: super: { - foo = super.foo.override { barSupport = true ; }; - })]}; -</programlisting> -<programlisting> -mypkg = pkgs.callPackage ./mypkg.nix { - mydep = pkgs.mydep.override { ... }; - } -</programlisting> - </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> - - <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 - 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> - - <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> - - <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"; - src = fetchurl { - url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; - sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k"; - }; - patches = []; -}); -</programlisting> - </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> - 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> - - <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: -<programlisting> -f = { a, b }: { result = a+b; }; -c = lib.makeOverridable f { a = 1; b = 2; }; -</programlisting> - </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> - </section> + <xi:include href="functions/overrides.xml" /> <section xml:id="sec-generators"> <title>Generators</title> diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml new file mode 100644 index 000000000000..dc81e3795065 --- /dev/null +++ b/doc/functions/overrides.xml @@ -0,0 +1,205 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-overrides"> + <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> + + <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> + It is used to override the arguments passed to a function. + </para> + + <para> + Example usages: +<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> +<programlisting> +import pkgs.path { overlays = [ (self: super: { + foo = super.foo.override { barSupport = true ; }; + })]}; +</programlisting> +<programlisting> +mypkg = pkgs.callPackage ./mypkg.nix { + mydep = pkgs.mydep.override { ... }; + } +</programlisting> + </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> + + <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 + 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> + + <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> + + <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"; + src = fetchurl { + url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; + sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k"; + }; + patches = []; +}); +</programlisting> + </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> + 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> + + <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: +<programlisting> +f = { a, b }: { result = a+b; }; +c = lib.makeOverridable f { a = 1; b = 2; }; +</programlisting> + </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> + </section> |