From f200a322c4f55c853d6543e47ebdbe7457262a61 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 13:52:21 -0400 Subject: [PATCH] nixpkgs docs: move overrides to its own file --- doc/functions.xml | 202 +---------------------------------- doc/functions/overrides.xml | 205 ++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 201 deletions(-) create mode 100644 doc/functions/overrides.xml 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. -
- Overriding - - Sometimes one wants to override parts of nixpkgs, e.g. - derivation attributes, the results of derivations or even the whole package - set. - - -
- <pkg>.override - - - The function override is usually available for all the - derivations in the nixpkgs expression (pkgs). - - - - It is used to override the arguments passed to a function. - - - - Example usages: -pkgs.foo.override { arg1 = val1; arg2 = val2; ... } - -import pkgs.path { overlays = [ (self: super: { - foo = super.foo.override { barSupport = true ; }; - })]}; - - -mypkg = pkgs.callPackage ./mypkg.nix { - mydep = pkgs.mydep.override { ... }; - } - - - - - In the first example, pkgs.foo is the result of a - function call with some default arguments, usually a derivation. Using - pkgs.foo.override will call the same function with the - given new arguments. - -
- -
- <pkg>.overrideAttrs - - - The function overrideAttrs allows overriding the - attribute set passed to a stdenv.mkDerivation call, - producing a new derivation based on the original one. This function is - available on all derivations produced by the - stdenv.mkDerivation function, which is most packages in - the nixpkgs expression pkgs. - - - - Example usage: - -helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { - separateDebugInfo = true; -}); - - - - - In the above example, the separateDebugInfo attribute is - overridden to be true, thus building debug info for - helloWithDebug, while all other attributes will be - retained from the original hello package. - - - - The argument oldAttrs is conventionally used to refer to - the attr set originally passed to stdenv.mkDerivation. - - - - - Note that separateDebugInfo is processed only by the - stdenv.mkDerivation function, not the generated, raw - Nix derivation. Thus, using overrideDerivation will not - work in this case, as it overrides only the attributes of the final - derivation. It is for this reason that overrideAttrs - should be preferred in (almost) all cases to - overrideDerivation, i.e. to allow using - sdenv.mkDerivation 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. - buildInputs vs nativeBuildInputs, - and involves less typing. - - -
- -
- <pkg>.overrideDerivation - - - - You should prefer overrideAttrs in almost all cases, - see its documentation for the reasons why. - overrideDerivation is not deprecated and will continue - to work, but is less nice to use and does not have as many abilities as - overrideAttrs. - - - - - - 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 ~/.config/nixpkgs/config.nix. - - - - - The function overrideDerivation 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 - makeOverridable function. Most standard - derivation-producing functions, such as - stdenv.mkDerivation, are defined using this function, - which means most packages in the nixpkgs expression, - pkgs, have this function. - - - - Example usage: - -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 = []; -}); - - - - - In the above example, the name, src, - and patches of the derivation will be overridden, while - all other attributes will be retained from the original derivation. - - - - The argument oldAttrs is used to refer to the attribute - set of the original derivation. - - - - - A package's attributes are evaluated *before* being modified by the - overrideDerivation function. For example, the - name attribute reference in url = - "mirror://gnu/hello/${name}.tar.gz"; is filled-in *before* the - overrideDerivation function modifies the attribute set. - This means that overriding the name attribute, in this - example, *will not* change the value of the url - attribute. Instead, we need to override both the name - *and* url attributes. - - -
- -
- lib.makeOverridable - - - The function lib.makeOverridable 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. - - - - Example usage: - -f = { a, b }: { result = a+b; }; -c = lib.makeOverridable f { a = 1; b = 2; }; - - - - - The variable c is the value of the f - function applied with some default arguments. Hence the value of - c.result is 3, in this example. - - - - The variable c however also has some additional - functions, like c.override which - can be used to override the default arguments. In this example the value of - (c.override { a = 4; }).result is 6. - -
-
+
Generators 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 @@ +
+ Overriding + + + Sometimes one wants to override parts of nixpkgs, e.g. + derivation attributes, the results of derivations or even the whole package + set. + + +
+ <pkg>.override + + + The function override is usually available for all the + derivations in the nixpkgs expression (pkgs). + + + + It is used to override the arguments passed to a function. + + + + Example usages: +pkgs.foo.override { arg1 = val1; arg2 = val2; ... } + +import pkgs.path { overlays = [ (self: super: { + foo = super.foo.override { barSupport = true ; }; + })]}; + + +mypkg = pkgs.callPackage ./mypkg.nix { + mydep = pkgs.mydep.override { ... }; + } + + + + + In the first example, pkgs.foo is the result of a + function call with some default arguments, usually a derivation. Using + pkgs.foo.override will call the same function with the + given new arguments. + +
+ +
+ <pkg>.overrideAttrs + + + The function overrideAttrs allows overriding the + attribute set passed to a stdenv.mkDerivation call, + producing a new derivation based on the original one. This function is + available on all derivations produced by the + stdenv.mkDerivation function, which is most packages in + the nixpkgs expression pkgs. + + + + Example usage: + +helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { + separateDebugInfo = true; +}); + + + + + In the above example, the separateDebugInfo attribute is + overridden to be true, thus building debug info for + helloWithDebug, while all other attributes will be + retained from the original hello package. + + + + The argument oldAttrs is conventionally used to refer to + the attr set originally passed to stdenv.mkDerivation. + + + + + Note that separateDebugInfo is processed only by the + stdenv.mkDerivation function, not the generated, raw + Nix derivation. Thus, using overrideDerivation will not + work in this case, as it overrides only the attributes of the final + derivation. It is for this reason that overrideAttrs + should be preferred in (almost) all cases to + overrideDerivation, i.e. to allow using + sdenv.mkDerivation 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. + buildInputs vs nativeBuildInputs, + and involves less typing. + + +
+ +
+ <pkg>.overrideDerivation + + + + You should prefer overrideAttrs in almost all cases, + see its documentation for the reasons why. + overrideDerivation is not deprecated and will continue + to work, but is less nice to use and does not have as many abilities as + overrideAttrs. + + + + + + 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 ~/.config/nixpkgs/config.nix. + + + + + The function overrideDerivation 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 + makeOverridable function. Most standard + derivation-producing functions, such as + stdenv.mkDerivation, are defined using this function, + which means most packages in the nixpkgs expression, + pkgs, have this function. + + + + Example usage: + +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 = []; +}); + + + + + In the above example, the name, src, + and patches of the derivation will be overridden, while + all other attributes will be retained from the original derivation. + + + + The argument oldAttrs is used to refer to the attribute + set of the original derivation. + + + + + A package's attributes are evaluated *before* being modified by the + overrideDerivation function. For example, the + name attribute reference in url = + "mirror://gnu/hello/${name}.tar.gz"; is filled-in *before* the + overrideDerivation function modifies the attribute set. + This means that overriding the name attribute, in this + example, *will not* change the value of the url + attribute. Instead, we need to override both the name + *and* url attributes. + + +
+ +
+ lib.makeOverridable + + + The function lib.makeOverridable 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. + + + + Example usage: + +f = { a, b }: { result = a+b; }; +c = lib.makeOverridable f { a = 1; b = 2; }; + + + + + The variable c is the value of the f + function applied with some default arguments. Hence the value of + c.result is 3, in this example. + + + + The variable c however also has some additional + functions, like c.override which + can be used to override the default arguments. In this example the value of + (c.override { a = 4; }).result is 6. + +
+