pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-overlays">
4 <title>Overlays</title>
5 <para>
6 This chapter describes how to extend and change Nixpkgs packages using
7 overlays. Overlays are used to add layers in the fix-point used by Nixpkgs to
8 compose the set of all packages.
9 </para>
10 <para>
11 Nixpkgs can be configured with a list of overlays, which are applied in
12 order. This means that the order of the overlays can be significant if
13 multiple layers override the same package.
14 </para>
15<!--============================================================-->
16 <section xml:id="sec-overlays-install">
17 <title>Installing overlays</title>
18
19 <para>
20 The list of overlays is determined as follows.
21 </para>
22
23 <para>
24 If the <varname>overlays</varname> argument is not provided explicitly, we
25 look for overlays in a path. The path is determined as follows:
26 <orderedlist>
27 <listitem>
28 <para>
29 First, if an <varname>overlays</varname> argument to the nixpkgs function
30 itself is given, then that is used.
31 </para>
32 <para>
33 This can be passed explicitly when importing nipxkgs, for example
34 <literal>import <nixpkgs> { overlays = [ overlay1 overlay2 ];
35 }</literal>.
36 </para>
37 </listitem>
38 <listitem>
39 <para>
40 Otherwise, if the Nix path entry <literal><nixpkgs-overlays></literal>
41 exists, we look for overlays at that path, as described below.
42 </para>
43 <para>
44 See the section on <literal>NIX_PATH</literal> in the Nix manual for more
45 details on how to set a value for
46 <literal><nixpkgs-overlays>.</literal>
47 </para>
48 </listitem>
49 <listitem>
50 <para>
51 If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
52 <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for
53 overlays at that path, as described below. It is an error if both exist.
54 </para>
55 </listitem>
56 </orderedlist>
57 </para>
58
59 <para>
60 If we are looking for overlays at a path, then there are two cases:
61 <itemizedlist>
62 <listitem>
63 <para>
64 If the path is a file, then the file is imported as a Nix expression and
65 used as the list of overlays.
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 If the path is a directory, then we take the content of the directory,
71 order it lexicographically, and attempt to interpret each as an overlay
72 by:
73 <itemizedlist>
74 <listitem>
75 <para>
76 Importing the file, if it is a <literal>.nix</literal> file.
77 </para>
78 </listitem>
79 <listitem>
80 <para>
81 Importing a top-level <filename>default.nix</filename> file, if it is
82 a directory.
83 </para>
84 </listitem>
85 </itemizedlist>
86 </para>
87 </listitem>
88 </itemizedlist>
89 </para>
90
91 <para>
92 On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
93 option, if present, is passed to the system Nixpkgs directly as an argument.
94 Note that this does not affect the overlays for non-NixOS operations (e.g.
95 <literal>nix-env</literal>), which are looked up independently.
96 </para>
97
98 <para>
99 The <filename>overlays.nix</filename> option therefore provides a convenient
100 way to use the same overlays for a NixOS system configuration and user
101 configuration: the same file can be used as
102 <filename>overlays.nix</filename> and imported as the value of
103 <literal>nixpkgs.overlays</literal>.
104 </para>
105 </section>
106<!--============================================================-->
107 <section xml:id="sec-overlays-definition">
108 <title>Defining overlays</title>
109
110 <para>
111 Overlays are Nix functions which accept two arguments, conventionally called
112 <varname>self</varname> and <varname>super</varname>, and return a set of
113 packages. For example, the following is a valid overlay.
114 </para>
115
116<programlisting>
117self: super:
118
119{
120 boost = super.boost.override {
121 python = self.python3;
122 };
123 rr = super.callPackage ./pkgs/rr {
124 stdenv = self.stdenv_32bit;
125 };
126}
127</programlisting>
128
129 <para>
130 The first argument (<varname>self</varname>) corresponds to the final
131 package set. You should use this set for the dependencies of all packages
132 specified in your overlay. For example, all the dependencies of
133 <varname>rr</varname> in the example above come from
134 <varname>self</varname>, as well as the overridden dependencies used in the
135 <varname>boost</varname> override.
136 </para>
137
138 <para>
139 The second argument (<varname>super</varname>) corresponds to the result of
140 the evaluation of the previous stages of Nixpkgs. It does not contain any of
141 the packages added by the current overlay, nor any of the following
142 overlays. This set should be used either to refer to packages you wish to
143 override, or to access functions defined in Nixpkgs. For example, the
144 original recipe of <varname>boost</varname> in the above example, comes from
145 <varname>super</varname>, as well as the <varname>callPackage</varname>
146 function.
147 </para>
148
149 <para>
150 The value returned by this function should be a set similar to
151 <filename>pkgs/top-level/all-packages.nix</filename>, containing overridden
152 and/or new packages.
153 </para>
154
155 <para>
156 Overlays are similar to other methods for customizing Nixpkgs, in particular
157 the <literal>packageOverrides</literal> attribute described in
158 <xref linkend="sec-modify-via-packageOverrides"/>. Indeed,
159 <literal>packageOverrides</literal> acts as an overlay with only the
160 <varname>super</varname> argument. It is therefore appropriate for basic
161 use, but overlays are more powerful and easier to distribute.
162 </para>
163 </section>
164</chapter>