pyrox.dev
1# Overriding {#chap-overrides}
2
3Sometimes one wants to override parts of `nixpkgs`, e.g. derivation attributes, the results of derivations.
4
5These functions are used to make changes to packages, returning only single packages. [Overlays](#chap-overlays), on the other hand, can be used to combine the overridden packages across the entire package set of Nixpkgs.
6
7## <pkg>.override {#sec-pkg-override}
8
9The function `override` is usually available for all the derivations in the nixpkgs expression (`pkgs`).
10
11It is used to override the arguments passed to a function.
12
13Example usages:
14
15```nix
16pkgs.foo.override {
17 arg1 = val1;
18 arg2 = val2; # ...
19}
20```
21
22It's also possible to access the previous arguments.
23
24```nix
25pkgs.foo.override (previous: {
26 arg1 = previous.arg1; # ...
27})
28```
29
30<!-- TODO: move below programlisting to a new section about extending and overlays and reference it -->
31
32```nix
33import pkgs.path {
34 overlays = [
35 (self: super: {
36 foo = super.foo.override { barSupport = true; };
37 })
38 ];
39}
40```
41
42```nix
43{
44 mypkg = pkgs.callPackage ./mypkg.nix {
45 mydep = pkgs.mydep.override {
46 # ...
47 };
48 };
49}
50```
51
52In 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.
53
54Many packages, like the `foo` example above, provide package options with default values in their arguments, to facilitate overriding.
55Because it's not usually feasible to test that packages build with all combinations of options, you might find that a package doesn't build if you override options to non-default values.
56
57Package maintainers are not expected to fix arbitrary combinations of options.
58If you find that something doesn't work, please submit a fix, ideally with a regression test.
59If you want to ensure that things keep working, consider [becoming a maintainer](https://github.com/NixOS/nixpkgs/tree/master/maintainers) for the package.
60
61## <pkg>.overrideAttrs {#sec-pkg-overrideAttrs}
62
63The 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`.
64
65Example usages:
66
67```nix
68{
69 helloBar = pkgs.hello.overrideAttrs (
70 finalAttrs: previousAttrs: {
71 pname = previousAttrs.pname + "-bar";
72 }
73 );
74}
75```
76
77In the above example, "-bar" is appended to the pname attribute, while all other attributes will be retained from the original `hello` package.
78
79The argument `previousAttrs` is conventionally used to refer to the attr set originally passed to `stdenv.mkDerivation`.
80
81The argument `finalAttrs` refers to the final attributes passed to `mkDerivation`, plus the `finalPackage` attribute which is equal to the result of `mkDerivation` or subsequent `overrideAttrs` calls.
82
83If only a one-argument function is written, the argument has the meaning of `previousAttrs`.
84
85Function arguments can be omitted entirely if there is no need to access `previousAttrs` or `finalAttrs`.
86
87```nix
88{
89 helloWithDebug = pkgs.hello.overrideAttrs {
90 separateDebugInfo = true;
91 };
92}
93```
94
95In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`.
96
97::: {.note}
98Note 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 `stdenv.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 it involves less typing).
99:::
100
101## <pkg>.overrideDerivation {#sec-pkg-overrideDerivation}
102
103::: {.warning}
104You 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`.
105:::
106
107::: {.warning}
108Do not use this function in Nixpkgs as it evaluates a derivation before modifying it, which breaks package abstraction. 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`.
109:::
110
111The 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.
112
113Example usage:
114
115```nix
116{
117 mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
118 name = "sed-4.2.2-pre";
119 src = fetchurl {
120 url = "ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2";
121 hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
122 };
123 patches = [ ];
124 });
125}
126```
127
128In 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.
129
130The argument `oldAttrs` is used to refer to the attribute set of the original derivation.
131
132::: {.note}
133A 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.
134:::
135
136## lib.makeOverridable {#sec-lib-makeOverridable}
137
138The 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.
139
140Example usage:
141
142```nix
143{
144 f =
145 { a, b }:
146 {
147 result = a + b;
148 };
149 c = lib.makeOverridable f {
150 a = 1;
151 b = 2;
152 };
153}
154```
155
156The 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.
157
158The variable `c` however also has some additional functions, like
159[c.override](#sec-pkg-override) which can be used to override the
160default arguments. In this example the value of
161`(c.override { a = 4; }).result` is 6.