From f200a322c4f55c853d6543e47ebdbe7457262a61 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 13:52:21 -0400 Subject: nixpkgs docs: move overrides to its own file --- doc/functions.xml | 202 +----------------------------------------------------- 1 file changed, 1 insertion(+), 201 deletions(-) (limited to 'doc/functions.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 -- cgit v1.2.3