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