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