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