pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-stdenv">
4
5<title>The Standard Environment</title>
6
7
8<para>The standard build environment in the Nix Packages collection
9provides an environment for building Unix packages that does a lot of
10common build tasks automatically. In fact, for Unix packages that use
11the standard <literal>./configure; make; make install</literal> build
12interface, you don’t need to write a build script at all; the standard
13environment does everything automatically. If
14<literal>stdenv</literal> doesn’t do what you need automatically, you
15can easily customise or override the various build phases.</para>
16
17
18<section xml:id="sec-using-stdenv"><title>Using
19<literal>stdenv</literal></title>
20
21<para>To build a package with the standard environment, you use the
22function <varname>stdenv.mkDerivation</varname>, instead of the
23primitive built-in function <varname>derivation</varname>, e.g.
24
25<programlisting>
26stdenv.mkDerivation {
27 name = "libfoo-1.2.3";
28 src = fetchurl {
29 url = http://example.org/libfoo-1.2.3.tar.bz2;
30 md5 = "e1ec107956b6ddcb0b8b0679367e9ac9";
31 };
32}</programlisting>
33
34(<varname>stdenv</varname> needs to be in scope, so if you write this
35in a separate Nix expression from
36<filename>pkgs/all-packages.nix</filename>, you need to pass it as a
37function argument.) Specifying a <varname>name</varname> and a
38<varname>src</varname> is the absolute minimum you need to do. Many
39packages have dependencies that are not provided in the standard
40environment. It’s usually sufficient to specify those dependencies in
41the <varname>buildInputs</varname> attribute:
42
43<programlisting>
44stdenv.mkDerivation {
45 name = "libfoo-1.2.3";
46 ...
47 buildInputs = [libbar perl ncurses];
48}</programlisting>
49
50This attribute ensures that the <filename>bin</filename>
51subdirectories of these packages appear in the <envar>PATH</envar>
52environment variable during the build, that their
53<filename>include</filename> subdirectories are searched by the C
54compiler, and so on. (See <xref linkend="ssec-setup-hooks"/> for
55details.)</para>
56
57<para>Often it is necessary to override or modify some aspect of the
58build. To make this easier, the standard environment breaks the
59package build into a number of <emphasis>phases</emphasis>, all of
60which can be overridden or modified individually: unpacking the
61sources, applying patches, configuring, building, and installing.
62(There are some others; see <xref linkend="sec-stdenv-phases"/>.)
63For instance, a package that doesn’t supply a makefile but instead has
64to be compiled “manually” could be handled like this:
65
66<programlisting>
67stdenv.mkDerivation {
68 name = "fnord-4.5";
69 ...
70 buildPhase = ''
71 gcc foo.c -o foo
72 '';
73 installPhase = ''
74 mkdir -p $out/bin
75 cp foo $out/bin
76 '';
77}</programlisting>
78
79(Note the use of <literal>''</literal>-style string literals, which
80are very convenient for large multi-line script fragments because they
81don’t need escaping of <literal>"</literal> and <literal>\</literal>,
82and because indentation is intelligently removed.)</para>
83
84<para>There are many other attributes to customise the build. These
85are listed in <xref linkend="ssec-stdenv-attributes"/>.</para>
86
87<para>While the standard environment provides a generic builder, you
88can still supply your own build script:
89
90<programlisting>
91stdenv.mkDerivation {
92 name = "libfoo-1.2.3";
93 ...
94 builder = ./builder.sh;
95}</programlisting>
96
97where the builder can do anything it wants, but typically starts with
98
99<programlisting>
100source $stdenv/setup
101</programlisting>
102
103to let <literal>stdenv</literal> set up the environment (e.g., process
104the <varname>buildInputs</varname>). If you want, you can still use
105<literal>stdenv</literal>’s generic builder:
106
107<programlisting>
108source $stdenv/setup
109
110buildPhase() {
111 echo "... this is my custom build phase ..."
112 gcc foo.c -o foo
113}
114
115installPhase() {
116 mkdir -p $out/bin
117 cp foo $out/bin
118}
119
120genericBuild
121</programlisting>
122
123</para>
124
125</section>
126
127
128<section xml:id="sec-tools-of-stdenv"><title>Tools provided by
129<literal>stdenv</literal></title>
130
131<para>The standard environment provides the following packages:
132
133<itemizedlist>
134
135 <listitem><para>The GNU C Compiler, configured with C and C++
136 support.</para></listitem>
137
138 <listitem><para>GNU coreutils (contains a few dozen standard Unix
139 commands).</para></listitem>
140
141 <listitem><para>GNU findutils (contains
142 <command>find</command>).</para></listitem>
143
144 <listitem><para>GNU diffutils (contains <command>diff</command>,
145 <command>cmp</command>).</para></listitem>
146
147 <listitem><para>GNU <command>sed</command>.</para></listitem>
148
149 <listitem><para>GNU <command>grep</command>.</para></listitem>
150
151 <listitem><para>GNU <command>awk</command>.</para></listitem>
152
153 <listitem><para>GNU <command>tar</command>.</para></listitem>
154
155 <listitem><para><command>gzip</command>, <command>bzip2</command>
156 and <command>xz</command>.</para></listitem>
157
158 <listitem><para>GNU Make. It has been patched to provide
159 <quote>nested</quote> output that can be fed into the
160 <command>nix-log2xml</command> command and
161 <command>log2html</command> stylesheet to create a structured,
162 readable output of the build steps performed by
163 Make.</para></listitem>
164
165 <listitem><para>Bash. This is the shell used for all builders in
166 the Nix Packages collection. Not using <command>/bin/sh</command>
167 removes a large source of portability problems.</para></listitem>
168
169 <listitem><para>The <command>patch</command>
170 command.</para></listitem>
171
172</itemizedlist>
173
174</para>
175
176<para>On Linux, <literal>stdenv</literal> also includes the
177<command>patchelf</command> utility.</para>
178
179</section>
180
181
182<section xml:id="ssec-stdenv-attributes"><title>Attributes</title>
183
184<variablelist>
185 <title>Variables affecting <literal>stdenv</literal>
186 initialisation</title>
187
188 <varlistentry>
189 <term><varname>NIX_DEBUG</varname></term>
190 <listitem><para>If set, <literal>stdenv</literal> will print some
191 debug information during the build. In particular, the
192 <command>gcc</command> and <command>ld</command> wrapper scripts
193 will print out the complete command line passed to the wrapped
194 tools.</para></listitem>
195 </varlistentry>
196
197 <varlistentry>
198 <term><varname>buildInputs</varname></term>
199 <listitem><para>A list of dependencies used by
200 <literal>stdenv</literal> to set up the environment for the build.
201 For each dependency <replaceable>dir</replaceable>, the directory
202 <filename><replaceable>dir</replaceable>/bin</filename>, if it
203 exists, is added to the <envar>PATH</envar> environment variable.
204 Other environment variables are also set up via a pluggable
205 mechanism. For instance, if <varname>buildInputs</varname>
206 contains Perl, then the <filename>lib/site_perl</filename>
207 subdirectory of each input is added to the <envar>PERL5LIB</envar>
208 environment variable. See <xref linkend="ssec-setup-hooks"/> for
209 details.</para></listitem>
210 </varlistentry>
211
212 <varlistentry>
213 <term><varname>propagatedBuildInputs</varname></term>
214 <listitem><para>Like <varname>buildInputs</varname>, but these
215 dependencies are <emphasis>propagated</emphasis>: that is, the
216 dependencies listed here are added to the
217 <varname>buildInputs</varname> of any package that uses
218 <emphasis>this</emphasis> package as a dependency. So if package
219 Y has <literal>propagatedBuildInputs = [X]</literal>, and package
220 Z has <literal>buildInputs = [Y]</literal>, then package X will
221 appear in Z’s build environment automatically.</para></listitem>
222 </varlistentry>
223
224
225</variablelist>
226
227<variablelist>
228 <title>Variables affecting build properties</title>
229
230 <varlistentry>
231 <term><varname>enableParallelBuilding</varname></term>
232 <listitem><para>If set, <literal>stdenv</literal> will pass specific
233 flags to <literal>make</literal> and other build tools to enable
234 parallel building with up to <literal>build-cores</literal>
235 workers.</para></listitem>
236 </varlistentry>
237
238 <varlistentry>
239 <term><varname>preferLocalBuild</varname></term>
240 <listitem><para>If set, specifies that the package is so lightweight
241 in terms of build operations (e.g. write a text file from a Nix string
242 to the store) that there's no need to look for it in binary caches --
243 it's faster to just build it locally. It also tells Hydra and other
244 facilities that this package doesn't need to be exported in binary
245 caches (noone would use it, after all).</para></listitem>
246 </varlistentry>
247
248</variablelist>
249
250<variablelist>
251 <title>Special variables</title>
252
253 <varlistentry>
254 <term><varname>passthru</varname></term>
255 <listitem><para>This is an attribute set which can be filled with arbitrary
256 values. For example:
257
258<programlisting>
259passthru = {
260 foo = "bar";
261 baz = {
262 value1 = 4;
263 value2 = 5;
264 };
265}
266</programlisting>
267
268</para>
269
270 <para>Values inside it are not passed to the builder, so you can change
271 them without triggering a rebuild. However, they can be accessed outside of a
272 derivation directly, as if they were set inside a derivation itself, e.g.
273 <literal>hello.baz.value1</literal>. We don't specify any usage or
274 schema of <literal>passthru</literal> - it is meant for values that would be
275 useful outside the derivation in other parts of a Nix expression (e.g. in other
276 derivations). An example would be to convey some specific dependency of your
277 derivation which contains a program with plugins support. Later, others who
278 make derivations with plugins can use passed-through dependency to ensure that
279 their plugin would be binary-compatible with built program.</para></listitem>
280 </varlistentry>
281
282</variablelist>
283
284</section>
285
286
287<section xml:id="sec-stdenv-phases"><title>Phases</title>
288
289<para>The generic builder has a number of <emphasis>phases</emphasis>.
290Package builds are split into phases to make it easier to override
291specific parts of the build (e.g., unpacking the sources or installing
292the binaries). Furthermore, it allows a nicer presentation of build
293logs in the Nix build farm.</para>
294
295<para>Each phase can be overridden in its entirety either by setting
296the environment variable
297<varname><replaceable>name</replaceable>Phase</varname> to a string
298containing some shell commands to be executed, or by redefining the
299shell function
300<varname><replaceable>name</replaceable>Phase</varname>. The former
301is convenient to override a phase from the derivation, while the
302latter is convenient from a build script.</para>
303
304
305<section xml:id="ssec-controlling-phases"><title>Controlling
306phases</title>
307
308<para>There are a number of variables that control what phases are
309executed and in what order:
310
311<variablelist>
312 <title>Variables affecting phase control</title>
313
314 <varlistentry>
315 <term><varname>phases</varname></term>
316 <listitem>
317 <para>Specifies the phases. You can change the order in which
318 phases are executed, or add new phases, by setting this
319 variable. If it’s not set, the default value is used, which is
320 <literal>$prePhases unpackPhase patchPhase $preConfigurePhases
321 configurePhase $preBuildPhases buildPhase checkPhase
322 $preInstallPhases installPhase fixupPhase $preDistPhases
323 distPhase $postPhases</literal>.
324 </para>
325
326 <para>Usually, if you just want to add a few phases, it’s more
327 convenient to set one of the variables below (such as
328 <varname>preInstallPhases</varname>), as you then don’t specify
329 all the normal phases.</para>
330 </listitem>
331 </varlistentry>
332
333 <varlistentry>
334 <term><varname>prePhases</varname></term>
335 <listitem>
336 <para>Additional phases executed before any of the default phases.</para>
337 </listitem>
338 </varlistentry>
339
340 <varlistentry>
341 <term><varname>preConfigurePhases</varname></term>
342 <listitem>
343 <para>Additional phases executed just before the configure phase.</para>
344 </listitem>
345 </varlistentry>
346
347 <varlistentry>
348 <term><varname>preBuildPhases</varname></term>
349 <listitem>
350 <para>Additional phases executed just before the build phase.</para>
351 </listitem>
352 </varlistentry>
353
354 <varlistentry>
355 <term><varname>preInstallPhases</varname></term>
356 <listitem>
357 <para>Additional phases executed just before the install phase.</para>
358 </listitem>
359 </varlistentry>
360
361 <varlistentry>
362 <term><varname>preFixupPhases</varname></term>
363 <listitem>
364 <para>Additional phases executed just before the fixup phase.</para>
365 </listitem>
366 </varlistentry>
367
368 <varlistentry>
369 <term><varname>preDistPhases</varname></term>
370 <listitem>
371 <para>Additional phases executed just before the distribution phase.</para>
372 </listitem>
373 </varlistentry>
374
375 <varlistentry>
376 <term><varname>postPhases</varname></term>
377 <listitem>
378 <para>Additional phases executed after any of the default
379 phases.</para>
380 </listitem>
381 </varlistentry>
382
383</variablelist>
384
385</para>
386
387</section>
388
389
390<section xml:id="ssec-unpack-phase"><title>The unpack phase</title>
391
392<para>The unpack phase is responsible for unpacking the source code of
393the package. The default implementation of
394<function>unpackPhase</function> unpacks the source files listed in
395the <envar>src</envar> environment variable to the current directory.
396It supports the following files by default:
397
398<variablelist>
399
400 <varlistentry>
401 <term>Tar files</term>
402 <listitem><para>These can optionally be compressed using
403 <command>gzip</command> (<filename>.tar.gz</filename>,
404 <filename>.tgz</filename> or <filename>.tar.Z</filename>),
405 <command>bzip2</command> (<filename>.tar.bz2</filename> or
406 <filename>.tbz2</filename>) or <command>xz</command>
407 (<filename>.tar.xz</filename> or
408 <filename>.tar.lzma</filename>).</para></listitem>
409 </varlistentry>
410
411 <varlistentry>
412 <term>Zip files</term>
413 <listitem><para>Zip files are unpacked using
414 <command>unzip</command>. However, <command>unzip</command> is
415 not in the standard environment, so you should add it to
416 <varname>buildInputs</varname> yourself.</para></listitem>
417 </varlistentry>
418
419 <varlistentry>
420 <term>Directories in the Nix store</term>
421 <listitem><para>These are simply copied to the current directory.
422 The hash part of the file name is stripped,
423 e.g. <filename>/nix/store/1wydxgby13cz...-my-sources</filename>
424 would be copied to
425 <filename>my-sources</filename>.</para></listitem>
426 </varlistentry>
427
428</variablelist>
429
430Additional file types can be supported by setting the
431<varname>unpackCmd</varname> variable (see below).</para>
432
433<para></para>
434
435<variablelist>
436 <title>Variables controlling the unpack phase</title>
437
438 <varlistentry>
439 <term><varname>srcs</varname> / <varname>src</varname></term>
440 <listitem><para>The list of source files or directories to be
441 unpacked or copied. One of these must be set.</para></listitem>
442 </varlistentry>
443
444 <varlistentry>
445 <term><varname>sourceRoot</varname></term>
446 <listitem><para>After running <function>unpackPhase</function>,
447 the generic builder changes the current directory to the directory
448 created by unpacking the sources. If there are multiple source
449 directories, you should set <varname>sourceRoot</varname> to the
450 name of the intended directory.</para></listitem>
451 </varlistentry>
452
453 <varlistentry>
454 <term><varname>setSourceRoot</varname></term>
455 <listitem><para>Alternatively to setting
456 <varname>sourceRoot</varname>, you can set
457 <varname>setSourceRoot</varname> to a shell command to be
458 evaluated by the unpack phase after the sources have been
459 unpacked. This command must set
460 <varname>sourceRoot</varname>.</para></listitem>
461 </varlistentry>
462
463 <varlistentry>
464 <term><varname>preUnpack</varname></term>
465 <listitem><para>Hook executed at the start of the unpack
466 phase.</para></listitem>
467 </varlistentry>
468
469 <varlistentry>
470 <term><varname>postUnpack</varname></term>
471 <listitem><para>Hook executed at the end of the unpack
472 phase.</para></listitem>
473 </varlistentry>
474
475 <varlistentry>
476 <term><varname>dontMakeSourcesWritable</varname></term>
477 <listitem><para>If set to <literal>1</literal>, the unpacked
478 sources are <emphasis>not</emphasis> made
479 writable. By default, they are made writable to prevent problems
480 with read-only sources. For example, copied store directories
481 would be read-only without this.</para></listitem>
482 </varlistentry>
483
484 <varlistentry>
485 <term><varname>unpackCmd</varname></term>
486 <listitem><para>The unpack phase evaluates the string
487 <literal>$unpackCmd</literal> for any unrecognised file. The path
488 to the current source file is contained in the
489 <varname>curSrc</varname> variable.</para></listitem>
490 </varlistentry>
491
492</variablelist>
493
494</section>
495
496
497<section xml:id="ssec-patch-phase"><title>The patch phase</title>
498
499<para>The patch phase applies the list of patches defined in the
500<varname>patches</varname> variable.</para>
501
502<variablelist>
503 <title>Variables controlling the patch phase</title>
504
505 <varlistentry>
506 <term><varname>patches</varname></term>
507 <listitem><para>The list of patches. They must be in the format
508 accepted by the <command>patch</command> command, and may
509 optionally be compressed using <command>gzip</command>
510 (<filename>.gz</filename>), <command>bzip2</command>
511 (<filename>.bz2</filename>) or <command>xz</command>
512 (<filename>.xz</filename>).</para></listitem>
513 </varlistentry>
514
515 <varlistentry>
516 <term><varname>patchFlags</varname></term>
517 <listitem><para>Flags to be passed to <command>patch</command>.
518 If not set, the argument <option>-p1</option> is used, which
519 causes the leading directory component to be stripped from the
520 file names in each patch.</para></listitem>
521 </varlistentry>
522
523 <varlistentry>
524 <term><varname>prePatch</varname></term>
525 <listitem><para>Hook executed at the start of the patch
526 phase.</para></listitem>
527 </varlistentry>
528
529 <varlistentry>
530 <term><varname>postPatch</varname></term>
531 <listitem><para>Hook executed at the end of the patch
532 phase.</para></listitem>
533 </varlistentry>
534
535</variablelist>
536
537</section>
538
539
540<section xml:id="ssec-configure-phase"><title>The configure phase</title>
541
542<para>The configure phase prepares the source tree for building. The
543default <function>configurePhase</function> runs
544<filename>./configure</filename> (typically an Autoconf-generated
545script) if it exists.</para>
546
547<variablelist>
548 <title>Variables controlling the configure phase</title>
549
550 <varlistentry>
551 <term><varname>configureScript</varname></term>
552 <listitem><para>The name of the configure script. It defaults to
553 <filename>./configure</filename> if it exists; otherwise, the
554 configure phase is skipped. This can actually be a command (like
555 <literal>perl ./Configure.pl</literal>).</para></listitem>
556 </varlistentry>
557
558 <varlistentry>
559 <term><varname>configureFlags</varname></term>
560 <listitem><para>A list of strings passed as additional arguments to the
561 configure script.</para></listitem>
562 </varlistentry>
563
564 <varlistentry>
565 <term><varname>configureFlagsArray</varname></term>
566 <listitem><para>A shell array containing additional arguments
567 passed to the configure script. You must use this instead of
568 <varname>configureFlags</varname> if the arguments contain
569 spaces.</para></listitem>
570 </varlistentry>
571
572 <varlistentry>
573 <term><varname>dontAddPrefix</varname></term>
574 <listitem><para>By default, the flag
575 <literal>--prefix=$prefix</literal> is added to the configure
576 flags. If this is undesirable, set this variable to
577 true.</para></listitem>
578 </varlistentry>
579
580 <varlistentry>
581 <term><varname>prefix</varname></term>
582 <listitem><para>The prefix under which the package must be
583 installed, passed via the <option>--prefix</option> option to the
584 configure script. It defaults to
585 <option>$out</option>.</para></listitem>
586 </varlistentry>
587
588 <varlistentry>
589 <term><varname>dontAddDisableDepTrack</varname></term>
590 <listitem><para>By default, the flag
591 <literal>--disable-dependency-tracking</literal> is added to the
592 configure flags to speed up Automake-based builds. If this is
593 undesirable, set this variable to true.</para></listitem>
594 </varlistentry>
595
596 <varlistentry>
597 <term><varname>dontFixLibtool</varname></term>
598 <listitem><para>By default, the configure phase applies some
599 special hackery to all files called <filename>ltmain.sh</filename>
600 before running the configure script in order to improve the purity
601 of Libtool-based packages<footnote><para>It clears the
602 <varname>sys_lib_<replaceable>*</replaceable>search_path</varname>
603 variables in the Libtool script to prevent Libtool from using
604 libraries in <filename>/usr/lib</filename> and
605 such.</para></footnote>. If this is undesirable, set this
606 variable to true.</para></listitem>
607 </varlistentry>
608
609 <varlistentry>
610 <term><varname>dontDisableStatic</varname></term>
611 <listitem><para>By default, when the configure script has
612 <option>--enable-static</option>, the option
613 <option>--disable-static</option> is added to the configure flags.</para>
614 <para>If this is undesirable, set this variable to
615 true.</para></listitem>
616 </varlistentry>
617
618 <varlistentry>
619 <term><varname>preConfigure</varname></term>
620 <listitem><para>Hook executed at the start of the configure
621 phase.</para></listitem>
622 </varlistentry>
623
624 <varlistentry>
625 <term><varname>postConfigure</varname></term>
626 <listitem><para>Hook executed at the end of the configure
627 phase.</para></listitem>
628 </varlistentry>
629
630</variablelist>
631
632
633</section>
634
635
636<section xml:id="build-phase"><title>The build phase</title>
637
638<para>The build phase is responsible for actually building the package
639(e.g. compiling it). The default <function>buildPhase</function>
640simply calls <command>make</command> if a file named
641<filename>Makefile</filename>, <filename>makefile</filename> or
642<filename>GNUmakefile</filename> exists in the current directory (or
643the <varname>makefile</varname> is explicitly set); otherwise it does
644nothing.</para>
645
646<variablelist>
647 <title>Variables controlling the build phase</title>
648
649 <varlistentry>
650 <term><varname>dontBuild</varname></term>
651 <listitem><para>Set to true to skip the build phase.</para></listitem>
652 </varlistentry>
653
654 <varlistentry>
655 <term><varname>makefile</varname></term>
656 <listitem><para>The file name of the Makefile.</para></listitem>
657 </varlistentry>
658
659 <varlistentry>
660 <term><varname>makeFlags</varname></term>
661 <listitem><para>A list of strings passed as additional flags to
662 <command>make</command>. These flags are also used by the default
663 install and check phase. For setting make flags specific to the
664 build phase, use <varname>buildFlags</varname> (see
665 below).</para></listitem>
666 </varlistentry>
667
668 <varlistentry>
669 <term><varname>makeFlagsArray</varname></term>
670 <listitem><para>A shell array containing additional arguments
671 passed to <command>make</command>. You must use this instead of
672 <varname>makeFlags</varname> if the arguments contain
673 spaces, e.g.
674
675<programlisting>
676makeFlagsArray=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar")
677</programlisting>
678
679 Note that shell arrays cannot be passed through environment
680 variables, so you cannot set <varname>makeFlagsArray</varname> in
681 a derivation attribute (because those are passed through
682 environment variables): you have to define them in shell
683 code.</para></listitem>
684 </varlistentry>
685
686 <varlistentry>
687 <term><varname>buildFlags</varname> / <varname>buildFlagsArray</varname></term>
688 <listitem><para>A list of strings passed as additional flags to
689 <command>make</command>. Like <varname>makeFlags</varname> and
690 <varname>makeFlagsArray</varname>, but only used by the build
691 phase.</para></listitem>
692 </varlistentry>
693
694 <varlistentry>
695 <term><varname>preBuild</varname></term>
696 <listitem><para>Hook executed at the start of the build
697 phase.</para></listitem>
698 </varlistentry>
699
700 <varlistentry>
701 <term><varname>postBuild</varname></term>
702 <listitem><para>Hook executed at the end of the build
703 phase.</para></listitem>
704 </varlistentry>
705
706</variablelist>
707
708
709<para>
710You can set flags for <command>make</command> through the
711<varname>makeFlags</varname> variable.</para>
712
713<para>Before and after running <command>make</command>, the hooks
714<varname>preBuild</varname> and <varname>postBuild</varname> are
715called, respectively.</para>
716
717</section>
718
719
720<section xml:id="ssec-check-phase"><title>The check phase</title>
721
722<para>The check phase checks whether the package was built correctly
723by running its test suite. The default
724<function>checkPhase</function> calls <command>make check</command>,
725but only if the <varname>doCheck</varname> variable is enabled.</para>
726
727<variablelist>
728 <title>Variables controlling the check phase</title>
729
730 <varlistentry>
731 <term><varname>doCheck</varname></term>
732 <listitem><para>If set to a non-empty string, the check phase is
733 executed, otherwise it is skipped (default). Thus you should set
734
735 <programlisting>
736doCheck = true;</programlisting>
737
738 in the derivation to enable checks.</para></listitem>
739 </varlistentry>
740
741 <varlistentry>
742 <term><varname>makeFlags</varname> /
743 <varname>makeFlagsArray</varname> /
744 <varname>makefile</varname></term>
745 <listitem><para>See the build phase for details.</para></listitem>
746 </varlistentry>
747
748 <varlistentry>
749 <term><varname>checkTarget</varname></term>
750 <listitem><para>The make target that runs the tests. Defaults to
751 <literal>check</literal>.</para></listitem>
752 </varlistentry>
753
754 <varlistentry>
755 <term><varname>checkFlags</varname> / <varname>checkFlagsArray</varname></term>
756 <listitem><para>A list of strings passed as additional flags to
757 <command>make</command>. Like <varname>makeFlags</varname> and
758 <varname>makeFlagsArray</varname>, but only used by the check
759 phase.</para></listitem>
760 </varlistentry>
761
762 <varlistentry>
763 <term><varname>preCheck</varname></term>
764 <listitem><para>Hook executed at the start of the check
765 phase.</para></listitem>
766 </varlistentry>
767
768 <varlistentry>
769 <term><varname>postCheck</varname></term>
770 <listitem><para>Hook executed at the end of the check
771 phase.</para></listitem>
772 </varlistentry>
773
774</variablelist>
775
776
777</section>
778
779
780<section xml:id="ssec-install-phase"><title>The install phase</title>
781
782<para>The install phase is responsible for installing the package in
783the Nix store under <envar>out</envar>. The default
784<function>installPhase</function> creates the directory
785<literal>$out</literal> and calls <command>make
786install</command>.</para>
787
788<variablelist>
789 <title>Variables controlling the install phase</title>
790
791 <varlistentry>
792 <term><varname>makeFlags</varname> /
793 <varname>makeFlagsArray</varname> /
794 <varname>makefile</varname></term>
795 <listitem><para>See the build phase for details.</para></listitem>
796 </varlistentry>
797
798 <varlistentry>
799 <term><varname>installTargets</varname></term>
800 <listitem><para>The make targets that perform the installation.
801 Defaults to <literal>install</literal>. Example:
802
803<programlisting>
804installTargets = "install-bin install-doc";</programlisting>
805
806 </para></listitem>
807 </varlistentry>
808
809 <varlistentry>
810 <term><varname>installFlags</varname> / <varname>installFlagsArray</varname></term>
811 <listitem><para>A list of strings passed as additional flags to
812 <command>make</command>. Like <varname>makeFlags</varname> and
813 <varname>makeFlagsArray</varname>, but only used by the install
814 phase.</para></listitem>
815 </varlistentry>
816
817 <varlistentry>
818 <term><varname>preInstall</varname></term>
819 <listitem><para>Hook executed at the start of the install
820 phase.</para></listitem>
821 </varlistentry>
822
823 <varlistentry>
824 <term><varname>postInstall</varname></term>
825 <listitem><para>Hook executed at the end of the install
826 phase.</para></listitem>
827 </varlistentry>
828
829</variablelist>
830
831
832</section>
833
834
835<section xml:id="ssec-fixup-phase"><title>The fixup phase</title>
836
837<para>The fixup phase performs some (Nix-specific) post-processing
838actions on the files installed under <filename>$out</filename> by the
839install phase. The default <function>fixupPhase</function> does the
840following:
841
842<itemizedlist>
843
844 <listitem><para>It moves the <filename>man/</filename>,
845 <filename>doc/</filename> and <filename>info/</filename>
846 subdirectories of <envar>$out</envar> to
847 <filename>share/</filename>.</para></listitem>
848
849 <listitem><para>It strips libraries and executables of debug
850 information.</para></listitem>
851
852 <listitem><para>On Linux, it applies the <command>patchelf</command>
853 command to ELF executables and libraries to remove unused
854 directories from the <literal>RPATH</literal> in order to prevent
855 unnecessary runtime dependencies.</para></listitem>
856
857 <listitem><para>It rewrites the interpreter paths of shell scripts
858 to paths found in <envar>PATH</envar>. E.g.,
859 <filename>/usr/bin/perl</filename> will be rewritten to
860 <filename>/nix/store/<replaceable>some-perl</replaceable>/bin/perl</filename>
861 found in <envar>PATH</envar>.</para></listitem>
862
863</itemizedlist>
864
865</para>
866
867<variablelist>
868 <title>Variables controlling the fixup phase</title>
869
870 <varlistentry>
871 <term><varname>dontStrip</varname></term>
872 <listitem><para>If set, libraries and executables are not
873 stripped. By default, they are.</para></listitem>
874 </varlistentry>
875
876 <varlistentry>
877 <term><varname>dontMoveSbin</varname></term>
878 <listitem><para>If set, files in <filename>$out/sbin</filename> are not moved
879 to <filename>$out/bin</filename>. By default, they are.</para></listitem>
880 </varlistentry>
881
882 <varlistentry>
883 <term><varname>stripAllList</varname></term>
884 <listitem><para>List of directories to search for libraries and
885 executables from which <emphasis>all</emphasis> symbols should be
886 stripped. By default, it’s empty. Stripping all symbols is
887 risky, since it may remove not just debug symbols but also ELF
888 information necessary for normal execution.</para></listitem>
889 </varlistentry>
890
891 <varlistentry>
892 <term><varname>stripAllFlags</varname></term>
893 <listitem><para>Flags passed to the <command>strip</command>
894 command applied to the files in the directories listed in
895 <varname>stripAllList</varname>. Defaults to <option>-s</option>
896 (i.e. <option>--strip-all</option>).</para></listitem>
897 </varlistentry>
898
899 <varlistentry>
900 <term><varname>stripDebugList</varname></term>
901 <listitem><para>List of directories to search for libraries and
902 executables from which only debugging-related symbols should be
903 stripped. It defaults to <literal>lib bin
904 sbin</literal>.</para></listitem>
905 </varlistentry>
906
907 <varlistentry>
908 <term><varname>stripDebugFlags</varname></term>
909 <listitem><para>Flags passed to the <command>strip</command>
910 command applied to the files in the directories listed in
911 <varname>stripDebugList</varname>. Defaults to
912 <option>-S</option>
913 (i.e. <option>--strip-debug</option>).</para></listitem>
914 </varlistentry>
915
916 <varlistentry>
917 <term><varname>dontPatchELF</varname></term>
918 <listitem><para>If set, the <command>patchelf</command> command is
919 not used to remove unnecessary <literal>RPATH</literal> entries.
920 Only applies to Linux.</para></listitem>
921 </varlistentry>
922
923 <varlistentry>
924 <term><varname>dontPatchShebangs</varname></term>
925 <listitem><para>If set, scripts starting with
926 <literal>#!</literal> do not have their interpreter paths
927 rewritten to paths in the Nix store.</para></listitem>
928 </varlistentry>
929
930 <varlistentry>
931 <term><varname>forceShare</varname></term>
932 <listitem><para>The list of directories that must be moved from
933 <filename>$out</filename> to <filename>$out/share</filename>.
934 Defaults to <literal>man doc info</literal>.</para></listitem>
935 </varlistentry>
936
937 <varlistentry>
938 <term><varname>setupHook</varname></term>
939 <listitem><para>A package can export a <link
940 linkend="ssec-setup-hooks">setup hook</link> by setting this
941 variable. The setup hook, if defined, is copied to
942 <filename>$out/nix-support/setup-hook</filename>. Environment
943 variables are then substituted in it using <function
944 linkend="fun-substituteAll">substituteAll</function>.</para></listitem>
945 </varlistentry>
946
947 <varlistentry>
948 <term><varname>preFixup</varname></term>
949 <listitem><para>Hook executed at the start of the fixup
950 phase.</para></listitem>
951 </varlistentry>
952
953 <varlistentry>
954 <term><varname>postFixup</varname></term>
955 <listitem><para>Hook executed at the end of the fixup
956 phase.</para></listitem>
957 </varlistentry>
958
959 <varlistentry xml:id="stdenv-separateDebugInfo">
960 <term><varname>separateDebugInfo</varname></term>
961 <listitem><para>If set to <literal>true</literal>, the standard
962 environment will enable debug information in C/C++ builds. After
963 installation, the debug information will be separated from the
964 executables and stored in the output named
965 <literal>debug</literal>. (This output is enabled automatically;
966 you don’t need to set the <varname>outputs</varname> attribute
967 explicitly.) To be precise, the debug information is stored in
968 <filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>,
969 where <replaceable>XXYYYY…</replaceable> is the <replaceable>build
970 ID</replaceable> of the binary — a SHA-1 hash of the contents of
971 the binary. Debuggers like GDB use the build ID to look up the
972 separated debug information.</para>
973
974 <para>For example, with GDB, you can add
975
976<programlisting>
977set debug-file-directory ~/.nix-profile/lib/debug
978</programlisting>
979
980 to <filename>~/.gdbinit</filename>. GDB will then be able to find
981 debug information installed via <literal>nix-env
982 -i</literal>.</para>
983
984 </listitem>
985 </varlistentry>
986
987</variablelist>
988
989</section>
990
991
992<section xml:id="ssec-distribution-phase"><title>The distribution
993phase</title>
994
995<para>The distribution phase is intended to produce a source
996distribution of the package. The default
997<function>distPhase</function> first calls <command>make
998dist</command>, then it copies the resulting source tarballs to
999<filename>$out/tarballs/</filename>. This phase is only executed if
1000the attribute <varname>doDist</varname> is set.</para>
1001
1002<variablelist>
1003 <title>Variables controlling the distribution phase</title>
1004
1005 <varlistentry>
1006 <term><varname>distTarget</varname></term>
1007 <listitem><para>The make target that produces the distribution.
1008 Defaults to <literal>dist</literal>.</para></listitem>
1009 </varlistentry>
1010
1011 <varlistentry>
1012 <term><varname>distFlags</varname> / <varname>distFlagsArray</varname></term>
1013 <listitem><para>Additional flags passed to
1014 <command>make</command>.</para></listitem>
1015 </varlistentry>
1016
1017 <varlistentry>
1018 <term><varname>tarballs</varname></term>
1019 <listitem><para>The names of the source distribution files to be
1020 copied to <filename>$out/tarballs/</filename>. It can contain
1021 shell wildcards. The default is
1022 <filename>*.tar.gz</filename>.</para></listitem>
1023 </varlistentry>
1024
1025 <varlistentry>
1026 <term><varname>dontCopyDist</varname></term>
1027 <listitem><para>If set, no files are copied to
1028 <filename>$out/tarballs/</filename>.</para></listitem>
1029 </varlistentry>
1030
1031 <varlistentry>
1032 <term><varname>preDist</varname></term>
1033 <listitem><para>Hook executed at the start of the distribution
1034 phase.</para></listitem>
1035 </varlistentry>
1036
1037 <varlistentry>
1038 <term><varname>postDist</varname></term>
1039 <listitem><para>Hook executed at the end of the distribution
1040 phase.</para></listitem>
1041 </varlistentry>
1042
1043</variablelist>
1044
1045
1046</section>
1047
1048
1049</section>
1050
1051
1052<section xml:id="ssec-stdenv-functions"><title>Shell functions</title>
1053
1054<para>The standard environment provides a number of useful
1055functions.</para>
1056
1057<variablelist>
1058
1059
1060 <varlistentry xml:id='fun-substitute'>
1061 <term><function>substitute</function>
1062 <replaceable>infile</replaceable>
1063 <replaceable>outfile</replaceable>
1064 <replaceable>subs</replaceable></term>
1065
1066 <listitem>
1067 <para>Performs string substitution on the contents of
1068 <replaceable>infile</replaceable>, writing the result to
1069 <replaceable>outfile</replaceable>. The substitutions in
1070 <replaceable>subs</replaceable> are of the following form:
1071
1072 <variablelist>
1073 <varlistentry>
1074 <term><option>--replace</option>
1075 <replaceable>s1</replaceable>
1076 <replaceable>s2</replaceable></term>
1077 <listitem><para>Replace every occurence of the string
1078 <replaceable>s1</replaceable> by
1079 <replaceable>s2</replaceable>.</para></listitem>
1080 </varlistentry>
1081
1082 <varlistentry>
1083 <term><option>--subst-var</option>
1084 <replaceable>varName</replaceable></term>
1085 <listitem><para>Replace every occurence of
1086 <literal>@<replaceable>varName</replaceable>@</literal> by
1087 the contents of the environment variable
1088 <replaceable>varName</replaceable>. This is useful for
1089 generating files from templates, using
1090 <literal>@<replaceable>...</replaceable>@</literal> in the
1091 template as placeholders.</para></listitem>
1092 </varlistentry>
1093
1094 <varlistentry>
1095 <term><option>--subst-var-by</option>
1096 <replaceable>varName</replaceable>
1097 <replaceable>s</replaceable></term>
1098 <listitem><para>Replace every occurence of
1099 <literal>@<replaceable>varName</replaceable>@</literal> by
1100 the string <replaceable>s</replaceable>.</para></listitem>
1101 </varlistentry>
1102
1103 </variablelist>
1104
1105 </para>
1106
1107 <para>Example:
1108
1109<programlisting>
1110substitute ./foo.in ./foo.out \
1111 --replace /usr/bin/bar $bar/bin/bar \
1112 --replace "a string containing spaces" "some other text" \
1113 --subst-var someVar
1114</programlisting>
1115
1116 </para>
1117
1118 <para><function>substitute</function> is implemented using the
1119 <command
1120 xlink:href="http://replace.richardlloyd.org.uk/">replace</command>
1121 command. Unlike with the <command>sed</command> command, you
1122 don’t have to worry about escaping special characters. It
1123 supports performing substitutions on binary files (such as
1124 executables), though there you’ll probably want to make sure
1125 that the replacement string is as long as the replaced
1126 string.</para>
1127
1128 </listitem>
1129 </varlistentry>
1130
1131
1132 <varlistentry xml:id='fun-substituteInPlace'>
1133 <term><function>substituteInPlace</function>
1134 <replaceable>file</replaceable>
1135 <replaceable>subs</replaceable></term>
1136 <listitem><para>Like <function>substitute</function>, but performs
1137 the substitutions in place on the file
1138 <replaceable>file</replaceable>.</para></listitem>
1139 </varlistentry>
1140
1141
1142 <varlistentry xml:id='fun-substituteAll'>
1143 <term><function>substituteAll</function>
1144 <replaceable>infile</replaceable>
1145 <replaceable>outfile</replaceable></term>
1146 <listitem><para>Replaces every occurence of
1147 <literal>@<replaceable>varName</replaceable>@</literal>, where
1148 <replaceable>varName</replaceable> is any environment variable, in
1149 <replaceable>infile</replaceable>, writing the result to
1150 <replaceable>outfile</replaceable>. For instance, if
1151 <replaceable>infile</replaceable> has the contents
1152
1153<programlisting>
1154#! @bash@/bin/sh
1155PATH=@coreutils@/bin
1156echo @foo@
1157</programlisting>
1158
1159 and the environment contains
1160 <literal>bash=/nix/store/bmwp0q28cf21...-bash-3.2-p39</literal>
1161 and
1162 <literal>coreutils=/nix/store/68afga4khv0w...-coreutils-6.12</literal>,
1163 but does not contain the variable <varname>foo</varname>, then the
1164 output will be
1165
1166<programlisting>
1167#! /nix/store/bmwp0q28cf21...-bash-3.2-p39/bin/sh
1168PATH=/nix/store/68afga4khv0w...-coreutils-6.12/bin
1169echo @foo@
1170</programlisting>
1171
1172 That is, no substitution is performed for undefined variables.</para>
1173
1174 <para>Environment variables that start with an uppercase letter or an
1175 underscore are filtered out,
1176 to prevent global variables (like <literal>HOME</literal>) or private
1177 variables (like <literal>__ETC_PROFILE_DONE</literal>) from accidentally
1178 getting substituted.
1179 The variables also have to be valid bash “names”, as
1180 defined in the bash manpage (alphanumeric or <literal>_</literal>,
1181 must not start with a number).</para>
1182 </listitem>
1183 </varlistentry>
1184
1185
1186 <varlistentry xml:id='fun-substituteAllInPlace'>
1187 <term><function>substituteAllInPlace</function>
1188 <replaceable>file</replaceable></term>
1189 <listitem><para>Like <function>substituteAll</function>, but performs
1190 the substitutions in place on the file
1191 <replaceable>file</replaceable>.</para></listitem>
1192 </varlistentry>
1193
1194
1195 <varlistentry xml:id='fun-stripHash'>
1196 <term><function>stripHash</function>
1197 <replaceable>path</replaceable></term>
1198 <listitem><para>Strips the directory and hash part of a store
1199 path, storing the name part in the environment variable
1200 <literal>strippedName</literal>. For example:
1201
1202<programlisting>
1203stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24"
1204# prints coreutils-8.24
1205echo $strippedName
1206</programlisting>
1207
1208 If you wish to store the result in another variable, then the
1209 following idiom may be useful:
1210
1211<programlisting>
1212name="/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24"
1213someVar=$(stripHash $name; echo $strippedName)
1214</programlisting>
1215
1216 </para></listitem>
1217 </varlistentry>
1218
1219
1220</variablelist>
1221
1222</section>
1223
1224
1225<section xml:id="ssec-setup-hooks"><title>Package setup hooks</title>
1226
1227<para>The following packages provide a setup hook:
1228
1229<variablelist>
1230
1231 <varlistentry>
1232 <term>GCC wrapper</term>
1233 <listitem><para>Adds the <filename>include</filename> subdirectory
1234 of each build input to the <envar>NIX_CFLAGS_COMPILE</envar>
1235 environment variable, and the <filename>lib</filename> and
1236 <filename>lib64</filename> subdirectories to
1237 <envar>NIX_LDFLAGS</envar>.</para></listitem>
1238 </varlistentry>
1239
1240 <varlistentry>
1241 <term>Perl</term>
1242 <listitem><para>Adds the <filename>lib/site_perl</filename> subdirectory
1243 of each build input to the <envar>PERL5LIB</envar>
1244 environment variable.</para></listitem>
1245 </varlistentry>
1246
1247 <varlistentry>
1248 <term>Python</term>
1249 <listitem><para>Adds the
1250 <filename>lib/${python.libPrefix}/site-packages</filename> subdirectory of
1251 each build input to the <envar>PYTHONPATH</envar> environment
1252 variable.</para></listitem>
1253 </varlistentry>
1254
1255 <varlistentry>
1256 <term>pkg-config</term>
1257 <listitem><para>Adds the <filename>lib/pkgconfig</filename> and
1258 <filename>share/pkgconfig</filename> subdirectories of each
1259 build input to the <envar>PKG_CONFIG_PATH</envar> environment
1260 variable.</para></listitem>
1261 </varlistentry>
1262
1263 <varlistentry>
1264 <term>Automake</term>
1265 <listitem><para>Adds the <filename>share/aclocal</filename>
1266 subdirectory of each build input to the <envar>ACLOCAL_PATH</envar>
1267 environment variable.</para></listitem>
1268 </varlistentry>
1269
1270 <varlistentry>
1271 <term>Autoconf</term>
1272 <listitem><para>The <varname>autoreconfHook</varname> derivation adds
1273 <varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize and
1274 automake, essentially preparing the configure script in autotools-based
1275 builds.</para></listitem>
1276 </varlistentry>
1277
1278 <varlistentry>
1279 <term>libxml2</term>
1280 <listitem><para>Adds every file named
1281 <filename>catalog.xml</filename> found under the
1282 <filename>xml/dtd</filename> and <filename>xml/xsl</filename>
1283 subdirectories of each build input to the
1284 <envar>XML_CATALOG_FILES</envar> environment
1285 variable.</para></listitem>
1286 </varlistentry>
1287
1288 <varlistentry>
1289 <term>teTeX / TeX Live</term>
1290 <listitem><para>Adds the <filename>share/texmf-nix</filename>
1291 subdirectory of each build input to the <envar>TEXINPUTS</envar>
1292 environment variable.</para></listitem>
1293 </varlistentry>
1294
1295 <varlistentry>
1296 <term>Qt 4</term>
1297 <listitem><para>Sets the <envar>QTDIR</envar> environment variable
1298 to Qt’s path.</para></listitem>
1299 </varlistentry>
1300
1301 <varlistentry>
1302 <term>gdk-pixbuf</term>
1303 <listitem><para>Exports <envar>GDK_PIXBUF_MODULE_FILE</envar>
1304 environment variable the the builder. Add librsvg package
1305 to <varname>buildInputs</varname> to get svg support.</para></listitem>
1306 </varlistentry>
1307
1308 <varlistentry>
1309 <term>GHC</term>
1310 <listitem><para>Creates a temporary package database and registers
1311 every Haskell build input in it (TODO: how?).</para></listitem>
1312 </varlistentry>
1313
1314 <varlistentry>
1315 <term>GStreamer</term>
1316 <listitem><para>Adds the
1317 GStreamer plugins subdirectory of
1318 each build input to the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> or
1319 <envar>GST_PLUGIN_SYSTEM_PATH</envar> environment variable.</para></listitem>
1320 </varlistentry>
1321
1322 <varlistentry>
1323 <term>paxctl</term>
1324 <listitem><para>Defines the <varname>paxmark</varname> helper for
1325 setting per-executable PaX flags on Linux (where it is available by
1326 default; on all other platforms, <varname>paxmark</varname> is a no-op).
1327 For example, to disable secure memory protections on the executable
1328 <replaceable>foo</replaceable>:
1329 <programlisting>
1330 postFixup = ''
1331 paxmark m $out/bin/<replaceable>foo</replaceable>
1332 '';
1333 </programlisting>
1334 The <literal>m</literal> flag is the most common flag and is typically
1335 required for applications that employ JIT compilation or otherwise need to
1336 execute code generated at run-time. Disabling PaX protections should be
1337 considered a last resort: if possible, problematic features should be
1338 disabled or patched to work with PaX.</para></listitem>
1339 </varlistentry>
1340
1341</variablelist>
1342
1343</para>
1344
1345</section>
1346
1347
1348<section xml:id="sec-purity-in-nixpkgs"><title>Purity in Nixpkgs</title>
1349
1350<para>[measures taken to prevent dependencies on packages outside the
1351store, and what you can do to prevent them]</para>
1352
1353<para>GCC doesn't search in locations such as
1354<filename>/usr/include</filename>. In fact, attempts to add such
1355directories through the <option>-I</option> flag are filtered out.
1356Likewise, the linker (from GNU binutils) doesn't search in standard
1357locations such as <filename>/usr/lib</filename>. Programs built on
1358Linux are linked against a GNU C Library that likewise doesn't search
1359in the default system locations.</para>
1360
1361</section>
1362
1363<section xml:id="sec-hardening-in-nixpkgs"><title>Hardening in Nixpkgs</title>
1364
1365<para>There are flags available to harden packages at compile or link-time.
1366These can be toggled using the <varname>stdenv.mkDerivation</varname> parameters
1367<varname>hardeningDisable</varname> and <varname>hardeningEnable</varname>.
1368</para>
1369
1370<para>The following flags are enabled by default and might require disabling
1371if the program to package is incompatible.
1372</para>
1373
1374<variablelist>
1375
1376 <varlistentry>
1377 <term><varname>format</varname></term>
1378 <listitem><para>Adds the <option>-Wformat -Wformat-security
1379 -Werror=format-security</option> compiler options. At present,
1380 this warns about calls to <varname>printf</varname> and
1381 <varname>scanf</varname> functions where the format string is
1382 not a string literal and there are no format arguments, as in
1383 <literal>printf(foo);</literal>. This may be a security hole
1384 if the format string came from untrusted input and contains
1385 <literal>%n</literal>.</para>
1386
1387 <para>This needs to be turned off or fixed for errors similar to:</para>
1388
1389 <programlisting>
1390/tmp/nix-build-zynaddsubfx-2.5.2.drv-0/zynaddsubfx-2.5.2/src/UI/guimain.cpp:571:28: error: format not a string literal and no format arguments [-Werror=format-security]
1391 printf(help_message);
1392 ^
1393cc1plus: some warnings being treated as errors
1394 </programlisting></listitem>
1395 </varlistentry>
1396
1397 <varlistentry>
1398 <term><varname>stackprotector</varname></term>
1399 <listitem>
1400 <para>Adds the <option>-fstack-protector-strong
1401 --param ssp-buffer-size=4</option>
1402 compiler options. This adds safety checks against stack overwrites
1403 rendering many potential code injection attacks into aborting situations.
1404 In the best case this turns code injection vulnerabilities into denial
1405 of service or into non-issues (depending on the application).</para>
1406
1407 <para>This needs to be turned off or fixed for errors similar to:</para>
1408
1409 <programlisting>
1410bin/blib.a(bios_console.o): In function `bios_handle_cup':
1411/tmp/nix-build-ipxe-20141124-5cbdc41.drv-0/ipxe-5cbdc41/src/arch/i386/firmware/pcbios/bios_console.c:86: undefined reference to `__stack_chk_fail'
1412 </programlisting></listitem>
1413 </varlistentry>
1414
1415 <varlistentry>
1416 <term><varname>fortify</varname></term>
1417 <listitem>
1418 <para>Adds the <option>-O2 -D_FORTIFY_SOURCE=2</option> compiler
1419 options. During code generation the compiler knows a great deal of
1420 information about buffer sizes (where possible), and attempts to replace
1421 insecure unlimited length buffer function calls with length-limited ones.
1422 This is especially useful for old, crufty code. Additionally, format
1423 strings in writable memory that contain '%n' are blocked. If an application
1424 depends on such a format string, it will need to be worked around.
1425 </para>
1426
1427 <para>Addtionally, some warnings are enabled which might trigger build
1428 failures if compiler warnings are treated as errors in the package build.
1429 In this case, set <option>NIX_CFLAGS_COMPILE</option> to
1430 <option>-Wno-error=warning-type</option>.</para>
1431
1432 <para>This needs to be turned off or fixed for errors similar to:</para>
1433
1434 <programlisting>
1435malloc.c:404:15: error: return type is an incomplete type
1436malloc.c:410:19: error: storage size of 'ms' isn't known
1437 </programlisting>
1438 <programlisting>
1439strdup.h:22:1: error: expected identifier or '(' before '__extension__'
1440 </programlisting>
1441 <programlisting>
1442strsep.c:65:23: error: register name not specified for 'delim'
1443 </programlisting>
1444 <programlisting>
1445installwatch.c:3751:5: error: conflicting types for '__open_2'
1446 </programlisting>
1447 <programlisting>
1448fcntl2.h:50:4: error: call to '__open_missing_mode' declared with attribute error: open with O_CREAT or O_TMPFILE in second argument needs 3 arguments
1449 </programlisting>
1450 </listitem>
1451 </varlistentry>
1452
1453 <varlistentry>
1454 <term><varname>pic</varname></term>
1455 <listitem>
1456 <para>Adds the <option>-fPIC</option> compiler options. This options adds
1457 support for position independant code in shared libraries and thus making
1458 ASLR possible.</para>
1459 <para>Most notably, the Linux kernel, kernel modules and other code
1460 not running in an operating system environment like boot loaders won't
1461 build with PIC enabled. The compiler will is most cases complain that
1462 PIC is not supported for a specific build.
1463 </para>
1464
1465 <para>This needs to be turned off or fixed for assembler errors similar to:</para>
1466
1467 <programlisting>
1468ccbLfRgg.s: Assembler messages:
1469ccbLfRgg.s:33: Error: missing or invalid displacement expression `private_key_len@GOTOFF'
1470 </programlisting>
1471 </listitem>
1472 </varlistentry>
1473
1474 <varlistentry>
1475 <term><varname>strictoverflow</varname></term>
1476 <listitem>
1477 <para>Signed integer overflow is undefined behaviour according to the C
1478 standard. If it happens, it is an error in the program as it should check
1479 for overflow before it can happen, not afterwards. GCC provides built-in
1480 functions to perform arithmetic with overflow checking, which are correct
1481 and faster than any custom implementation. As a workaround, the option
1482 <option>-fno-strict-overflow</option> makes gcc behave as if signed
1483 integer overflows were defined.
1484 </para>
1485
1486 <para>This flag should not trigger any build or runtime errors.</para>
1487 </listitem>
1488 </varlistentry>
1489
1490 <varlistentry>
1491 <term><varname>relro</varname></term>
1492 <listitem>
1493 <para>Adds the <option>-z relro</option> linker option. During program
1494 load, several ELF memory sections need to be written to by the linker,
1495 but can be turned read-only before turning over control to the program.
1496 This prevents some GOT (and .dtors) overwrite attacks, but at least the
1497 part of the GOT used by the dynamic linker (.got.plt) is still vulnerable.
1498 </para>
1499
1500 <para>This flag can break dynamic shared object loading. For instance, the
1501 module systems of Xorg and OpenCV are incompatible with this flag. In almost
1502 all cases the <varname>bindnow</varname> flag must also be disabled and
1503 incompatible programs typically fail with similar errors at runtime.</para>
1504 </listitem>
1505 </varlistentry>
1506
1507 <varlistentry>
1508 <term><varname>bindnow</varname></term>
1509 <listitem>
1510 <para>Adds the <option>-z bindnow</option> linker option. During program
1511 load, all dynamic symbols are resolved, allowing for the complete GOT to
1512 be marked read-only (due to <varname>relro</varname>). This prevents GOT
1513 overwrite attacks. For very large applications, this can incur some
1514 performance loss during initial load while symbols are resolved, but this
1515 shouldn't be an issue for daemons.
1516 </para>
1517
1518 <para>This flag can break dynamic shared object loading. For instance, the
1519 module systems of Xorg and PHP are incompatible with this flag. Programs
1520 incompatible with this flag often fail at runtime due to missing symbols,
1521 like:</para>
1522
1523 <programlisting>
1524intel_drv.so: undefined symbol: vgaHWFreeHWRec
1525 </programlisting>
1526 </listitem>
1527 </varlistentry>
1528
1529</variablelist>
1530
1531<para>The following flags are disabled by default and should be enabled
1532for packages that take untrusted input, like network services.
1533</para>
1534
1535<variablelist>
1536
1537 <varlistentry>
1538 <term><varname>pie</varname></term>
1539 <listitem>
1540 <para>Adds the <option>-fPIE</option> compiler and <option>-pie</option>
1541 linker options. Position Independent Executables are needed to take
1542 advantage of Address Space Layout Randomization, supported by modern
1543 kernel versions. While ASLR can already be enforced for data areas in
1544 the stack and heap (brk and mmap), the code areas must be compiled as
1545 position-independent. Shared libraries already do this with the
1546 <varname>pic</varname> flag, so they gain ASLR automatically, but binary
1547 .text regions need to be build with <varname>pie</varname> to gain ASLR.
1548 When this happens, ROP attacks are much harder since there are no static
1549 locations to bounce off of during a memory corruption attack.
1550 </para>
1551 </listitem>
1552 </varlistentry>
1553
1554</variablelist>
1555
1556<para>For more in-depth information on these hardening flags and hardening in
1557general, refer to the
1558<link xlink:href="https://wiki.debian.org/Hardening">Debian Wiki</link>,
1559<link xlink:href="https://wiki.ubuntu.com/Security/Features">Ubuntu Wiki</link>,
1560<link xlink:href="https://wiki.gentoo.org/wiki/Project:Hardened">Gentoo Wiki</link>,
1561and the <link xlink:href="https://wiki.archlinux.org/index.php/DeveloperWiki:Security">
1562Arch Wiki</link>.
1563</para>
1564
1565</section>
1566
1567</chapter>
1568