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