diff --git a/doc/functions.xml b/doc/functions.xml
index 8223a8b0531..754159bff4f 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 00000000000..dc81e379506
--- /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.
+
+
+