tjh.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-packageconfig">
4 <title>Global configuration</title>
5 <para>
6 Nix comes with certain defaults about what packages can and cannot be
7 installed, based on a package's metadata. By default, Nix will prevent
8 installation if any of the following criteria are true:
9 </para>
10 <itemizedlist>
11 <listitem>
12 <para>
13 The package is thought to be broken, and has had its
14 <literal>meta.broken</literal> set to <literal>true</literal>.
15 </para>
16 </listitem>
17 <listitem>
18 <para>
19 The package's <literal>meta.license</literal> is set to a license which is
20 considered to be unfree.
21 </para>
22 </listitem>
23 <listitem>
24 <para>
25 The package has known security vulnerabilities but has not or can not be
26 updated for some reason, and a list of issues has been entered in to the
27 package's <literal>meta.knownVulnerabilities</literal>.
28 </para>
29 </listitem>
30 </itemizedlist>
31 <para>
32 Note that all this is checked during evaluation already, and the check
33 includes any package that is evaluated. In particular, all build-time
34 dependencies are checked. <literal>nix-env -qa</literal> will (attempt to)
35 hide any packages that would be refused.
36 </para>
37 <para>
38 Each of these criteria can be altered in the nixpkgs configuration.
39 </para>
40 <para>
41 The nixpkgs configuration for a NixOS system is set in the
42 <literal>configuration.nix</literal>, as in the following example:
43<programlisting>
44{
45 nixpkgs.config = {
46 allowUnfree = true;
47 };
48}
49</programlisting>
50 However, this does not allow unfree software for individual users. Their
51 configurations are managed separately.
52 </para>
53 <para>
54 A user's of nixpkgs configuration is stored in a user-specific configuration
55 file located at <filename>~/.config/nixpkgs/config.nix</filename>. For
56 example:
57<programlisting>
58{
59 allowUnfree = true;
60}
61</programlisting>
62 </para>
63 <para>
64 Note that we are not able to test or build unfree software on Hydra due to
65 policy. Most unfree licenses prohibit us from either executing or
66 distributing the software.
67 </para>
68 <section xml:id="sec-allow-broken">
69 <title>Installing broken packages</title>
70
71 <para>
72 There are two ways to try compiling a package which has been marked as
73 broken.
74 </para>
75
76 <itemizedlist>
77 <listitem>
78 <para>
79 For allowing the build of a broken package once, you can use an
80 environment variable for a single invocation of the nix tools:
81<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
82 </para>
83 </listitem>
84 <listitem>
85 <para>
86 For permanently allowing broken packages to be built, you may add
87 <literal>allowBroken = true;</literal> to your user's configuration file,
88 like this:
89<programlisting>
90{
91 allowBroken = true;
92}
93</programlisting>
94 </para>
95 </listitem>
96 </itemizedlist>
97 </section>
98 <section xml:id="sec-allow-unfree">
99 <title>Installing unfree packages</title>
100
101 <para>
102 There are several ways to tweak how Nix handles a package which has been
103 marked as unfree.
104 </para>
105
106 <itemizedlist>
107 <listitem>
108 <para>
109 To temporarily allow all unfree packages, you can use an environment
110 variable for a single invocation of the nix tools:
111<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
112 </para>
113 </listitem>
114 <listitem>
115 <para>
116 It is possible to permanently allow individual unfree packages, while
117 still blocking unfree packages by default using the
118 <literal>allowUnfreePredicate</literal> configuration option in the user
119 configuration file.
120 </para>
121 <para>
122 This option is a function which accepts a package as a parameter, and
123 returns a boolean. The following example configuration accepts a package
124 and always returns false:
125<programlisting>
126{
127 allowUnfreePredicate = (pkg: false);
128}
129</programlisting>
130 </para>
131 <para>
132 A more useful example, the following configuration allows only allows
133 flash player and visual studio code:
134<programlisting>
135{
136 allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
137}
138</programlisting>
139 </para>
140 </listitem>
141 <listitem>
142 <para>
143 It is also possible to whitelist and blacklist licenses that are
144 specifically acceptable or not acceptable, using
145 <literal>whitelistedLicenses</literal> and
146 <literal>blacklistedLicenses</literal>, respectively.
147 </para>
148 <para>
149 The following example configuration whitelists the licenses
150 <literal>amd</literal> and <literal>wtfpl</literal>:
151<programlisting>
152{
153 whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
154}
155</programlisting>
156 </para>
157 <para>
158 The following example configuration blacklists the <literal>gpl3</literal>
159 and <literal>agpl3</literal> licenses:
160<programlisting>
161{
162 blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
163}
164</programlisting>
165 </para>
166 </listitem>
167 </itemizedlist>
168
169 <para>
170 A complete list of licenses can be found in the file
171 <filename>lib/licenses.nix</filename> of the nixpkgs tree.
172 </para>
173 </section>
174 <section xml:id="sec-allow-insecure">
175 <title>Installing insecure packages</title>
176
177 <para>
178 There are several ways to tweak how Nix handles a package which has been
179 marked as insecure.
180 </para>
181
182 <itemizedlist>
183 <listitem>
184 <para>
185 To temporarily allow all insecure packages, you can use an environment
186 variable for a single invocation of the nix tools:
187<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
188 </para>
189 </listitem>
190 <listitem>
191 <para>
192 It is possible to permanently allow individual insecure packages, while
193 still blocking other insecure packages by default using the
194 <literal>permittedInsecurePackages</literal> configuration option in the
195 user configuration file.
196 </para>
197 <para>
198 The following example configuration permits the installation of the
199 hypothetically insecure package <literal>hello</literal>, version
200 <literal>1.2.3</literal>:
201<programlisting>
202{
203 permittedInsecurePackages = [
204 "hello-1.2.3"
205 ];
206}
207</programlisting>
208 </para>
209 </listitem>
210 <listitem>
211 <para>
212 It is also possible to create a custom policy around which insecure
213 packages to allow and deny, by overriding the
214 <literal>allowInsecurePredicate</literal> configuration option.
215 </para>
216 <para>
217 The <literal>allowInsecurePredicate</literal> option is a function which
218 accepts a package and returns a boolean, much like
219 <literal>allowUnfreePredicate</literal>.
220 </para>
221 <para>
222 The following configuration example only allows insecure packages with
223 very short names:
224<programlisting>
225{
226 allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) <= 5);
227}
228</programlisting>
229 </para>
230 <para>
231 Note that <literal>permittedInsecurePackages</literal> is only checked if
232 <literal>allowInsecurePredicate</literal> is not specified.
233 </para>
234 </listitem>
235 </itemizedlist>
236 </section>
237<!--============================================================-->
238 <section xml:id="sec-modify-via-packageOverrides">
239 <title>Modify packages via <literal>packageOverrides</literal></title>
240
241 <para>
242 You can define a function called <varname>packageOverrides</varname> in your
243 local <filename>~/.config/nixpkgs/config.nix</filename> to override nix
244 packages. It must be a function that takes pkgs as an argument and return
245 modified set of packages.
246<programlisting>
247{
248 packageOverrides = pkgs: rec {
249 foo = pkgs.foo.override { ... };
250 };
251}
252</programlisting>
253 </para>
254 </section>
255 <section xml:id="sec-declarative-package-management">
256 <title>Declarative Package Management</title>
257
258 <section xml:id="sec-building-environment">
259 <title>Build an environment</title>
260
261 <para>
262 Using <literal>packageOverrides</literal>, it is possible to manage
263 packages declaratively. This means that we can list all of our desired
264 packages within a declarative Nix expression. For example, to have
265 <literal>aspell</literal>, <literal>bc</literal>,
266 <literal>ffmpeg</literal>, <literal>coreutils</literal>,
267 <literal>gdb</literal>, <literal>nixUnstable</literal>,
268 <literal>emscripten</literal>, <literal>jq</literal>,
269 <literal>nox</literal>, and <literal>silver-searcher</literal>, we could
270 use the following in <filename>~/.config/nixpkgs/config.nix</filename>:
271 </para>
272
273<screen>
274{
275 packageOverrides = pkgs: with pkgs; {
276 myPackages = pkgs.buildEnv {
277 name = "my-packages";
278 paths = [ aspell bc coreutils gdb ffmpeg nixUnstable emscripten jq nox silver-searcher ];
279 };
280 };
281}
282 </screen>
283
284 <para>
285 To install it into our environment, you can just run <literal>nix-env -iA
286 nixpkgs.myPackages</literal>. If you want to load the packages to be built
287 from a working copy of <literal>nixpkgs</literal> you just run
288 <literal>nix-env -f. -iA myPackages</literal>. To explore what's been
289 installed, just look through <filename>~/.nix-profile/</filename>. You can
290 see that a lot of stuff has been installed. Some of this stuff is useful
291 some of it isn't. Let's tell Nixpkgs to only link the stuff that we want:
292 </para>
293
294<screen>
295{
296 packageOverrides = pkgs: with pkgs; {
297 myPackages = pkgs.buildEnv {
298 name = "my-packages";
299 paths = [ aspell bc coreutils gdb ffmpeg nixUnstable emscripten jq nox silver-searcher ];
300 pathsToLink = [ "/share" "/bin" ];
301 };
302 };
303}
304 </screen>
305
306 <para>
307 <literal>pathsToLink</literal> tells Nixpkgs to only link the paths listed
308 which gets rid of the extra stuff in the profile. <filename>/bin</filename>
309 and <filename>/share</filename> are good defaults for a user environment,
310 getting rid of the clutter. If you are running on Nix on MacOS, you may
311 want to add another path as well, <filename>/Applications</filename>, that
312 makes GUI apps available.
313 </para>
314 </section>
315
316 <section xml:id="sec-getting-documentation">
317 <title>Getting documentation</title>
318
319 <para>
320 After building that new environment, look through
321 <filename>~/.nix-profile</filename> to make sure everything is there that
322 we wanted. Discerning readers will note that some files are missing. Look
323 inside <filename>~/.nix-profile/share/man/man1/</filename> to verify this.
324 There are no man pages for any of the Nix tools! This is because some
325 packages like Nix have multiple outputs for things like documentation (see
326 section 4). Let's make Nix install those as well.
327 </para>
328
329<screen>
330{
331 packageOverrides = pkgs: with pkgs; {
332 myPackages = pkgs.buildEnv {
333 name = "my-packages";
334 paths = [ aspell bc coreutils ffmpeg nixUnstable emscripten jq nox silver-searcher ];
335 pathsToLink = [ "/share/man" "/share/doc" /bin" ];
336 extraOutputsToInstall = [ "man" "doc" ];
337 };
338 };
339}
340 </screen>
341
342 <para>
343 This provides us with some useful documentation for using our packages.
344 However, if we actually want those manpages to be detected by man, we need
345 to set up our environment. This can also be managed within Nix expressions.
346 </para>
347
348<screen>
349{
350 packageOverrides = pkgs: with pkgs; rec {
351 myProfile = writeText "my-profile" ''
352export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
353export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
354 '';
355 myPackages = pkgs.buildEnv {
356 name = "my-packages";
357 paths = [
358 (runCommand "profile" {} ''
359mkdir -p $out/etc/profile.d
360cp ${myProfile} $out/etc/profile.d/my-profile.sh
361 '')
362 aspell
363 bc
364 coreutils
365 ffmpeg
366 man
367 nixUnstable
368 emscripten
369 jq
370 nox
371 silver-searcher
372 ];
373 pathsToLink = [ "/share/man" "/share/doc" /bin" "/etc" ];
374 extraOutputsToInstall = [ "man" "doc" ];
375 };
376 };
377}
378 </screen>
379
380 <para>
381 For this to work fully, you must also have this script sourced when you are
382 logged in. Try adding something like this to your
383 <filename>~/.profile</filename> file:
384 </para>
385
386<screen>
387#!/bin/sh
388if [ -d $HOME/.nix-profile/etc/profile.d ]; then
389 for i in $HOME/.nix-profile/etc/profile.d/*.sh; do
390 if [ -r $i ]; then
391 . $i
392 fi
393 done
394fi
395 </screen>
396
397 <para>
398 Now just run <literal>source $HOME/.profile</literal> and you can starting
399 loading man pages from your environent.
400 </para>
401 </section>
402
403 <section xml:id="sec-gnu-info-setup">
404 <title>GNU info setup</title>
405
406 <para>
407 Configuring GNU info is a little bit trickier than man pages. To work
408 correctly, info needs a database to be generated. This can be done with
409 some small modifications to our environment scripts.
410 </para>
411
412<screen>
413{
414 packageOverrides = pkgs: with pkgs; rec {
415 myProfile = writeText "my-profile" ''
416export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
417export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
418export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
419 '';
420 myPackages = pkgs.buildEnv {
421 name = "my-packages";
422 paths = [
423 (runCommand "profile" {} ''
424mkdir -p $out/etc/profile.d
425cp ${myProfile} $out/etc/profile.d/my-profile.sh
426 '')
427 aspell
428 bc
429 coreutils
430 ffmpeg
431 man
432 nixUnstable
433 emscripten
434 jq
435 nox
436 silver-searcher
437 texinfoInteractive
438 ];
439 pathsToLink = [ "/share/man" "/share/doc" "/share/info" "/bin" "/etc" ];
440 extraOutputsToInstall = [ "man" "doc" "info" ];
441 postBuild = ''
442 if [ -x $out/bin/install-info -a -w $out/share/info ]; then
443 shopt -s nullglob
444 for i in $out/share/info/*.info $out/share/info/*.info.gz; do
445 $out/bin/install-info $i $out/share/info/dir
446 done
447 fi
448 '';
449 };
450 };
451}
452 </screen>
453
454 <para>
455 <literal>postBuild</literal> tells Nixpkgs to run a command after building
456 the environment. In this case, <literal>install-info</literal> adds the
457 installed info pages to <literal>dir</literal> which is GNU info's default
458 root node. Note that <literal>texinfoInteractive</literal> is added to the
459 environment to give the <literal>install-info</literal> command.
460 </para>
461 </section>
462 </section>
463</chapter>