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</section>
228
229
230<section xml:id="sec-stdenv-phases"><title>Phases</title>
231
232<para>The generic builder has a number of <emphasis>phases</emphasis>.
233Package builds are split into phases to make it easier to override
234specific parts of the build (e.g., unpacking the sources or installing
235the binaries). Furthermore, it allows a nicer presentation of build
236logs in the Nix build farm.</para>
237
238<para>Each phase can be overridden in its entirety either by setting
239the environment variable
240<varname><replaceable>name</replaceable>Phase</varname> to a string
241containing some shell commands to be executed, or by redefining the
242shell function
243<varname><replaceable>name</replaceable>Phase</varname>. The former
244is convenient to override a phase from the derivation, while the
245latter is convenient from a build script.</para>
246
247
248<section xml:id="ssec-controlling-phases"><title>Controlling
249phases</title>
250
251<para>There are a number of variables that control what phases are
252executed and in what order:
253
254<variablelist>
255 <title>Variables affecting phase control</title>
256
257 <varlistentry>
258 <term><varname>phases</varname></term>
259 <listitem>
260 <para>Specifies the phases. You can change the order in which
261 phases are executed, or add new phases, by setting this
262 variable. If it’s not set, the default value is used, which is
263 <literal>$prePhases unpackPhase patchPhase $preConfigurePhases
264 configurePhase $preBuildPhases buildPhase checkPhase
265 $preInstallPhases installPhase fixupPhase $preDistPhases
266 distPhase $postPhases</literal>.
267 </para>
268
269 <para>Usually, if you just want to add a few phases, it’s more
270 convenient to set one of the variables below (such as
271 <varname>preInstallPhases</varname>), as you then don’t specify
272 all the normal phases.</para>
273 </listitem>
274 </varlistentry>
275
276 <varlistentry>
277 <term><varname>prePhases</varname></term>
278 <listitem>
279 <para>Additional phases executed before any of the default phases.</para>
280 </listitem>
281 </varlistentry>
282
283 <varlistentry>
284 <term><varname>preConfigurePhases</varname></term>
285 <listitem>
286 <para>Additional phases executed just before the configure phase.</para>
287 </listitem>
288 </varlistentry>
289
290 <varlistentry>
291 <term><varname>preBuildPhases</varname></term>
292 <listitem>
293 <para>Additional phases executed just before the build phase.</para>
294 </listitem>
295 </varlistentry>
296
297 <varlistentry>
298 <term><varname>preInstallPhases</varname></term>
299 <listitem>
300 <para>Additional phases executed just before the install phase.</para>
301 </listitem>
302 </varlistentry>
303
304 <varlistentry>
305 <term><varname>preFixupPhases</varname></term>
306 <listitem>
307 <para>Additional phases executed just before the fixup phase.</para>
308 </listitem>
309 </varlistentry>
310
311 <varlistentry>
312 <term><varname>preDistPhases</varname></term>
313 <listitem>
314 <para>Additional phases executed just before the distribution phase.</para>
315 </listitem>
316 </varlistentry>
317
318 <varlistentry>
319 <term><varname>postPhases</varname></term>
320 <listitem>
321 <para>Additional phases executed after any of the default
322 phases.</para>
323 </listitem>
324 </varlistentry>
325
326</variablelist>
327
328</para>
329
330</section>
331
332
333<section xml:id="ssec-unpack-phase"><title>The unpack phase</title>
334
335<para>The unpack phase is responsible for unpacking the source code of
336the package. The default implementation of
337<function>unpackPhase</function> unpacks the source files listed in
338the <envar>src</envar> environment variable to the current directory.
339It supports the following files by default:
340
341<variablelist>
342
343 <varlistentry>
344 <term>Tar files</term>
345 <listitem><para>These can optionally be compressed using
346 <command>gzip</command> (<filename>.tar.gz</filename>,
347 <filename>.tgz</filename> or <filename>.tar.Z</filename>),
348 <command>bzip2</command> (<filename>.tar.bz2</filename> or
349 <filename>.tbz2</filename>) or <command>xz</command>
350 (<filename>.tar.xz</filename> or
351 <filename>.tar.lzma</filename>).</para></listitem>
352 </varlistentry>
353
354 <varlistentry>
355 <term>Zip files</term>
356 <listitem><para>Zip files are unpacked using
357 <command>unzip</command>. However, <command>unzip</command> is
358 not in the standard environment, so you should add it to
359 <varname>buildInputs</varname> yourself.</para></listitem>
360 </varlistentry>
361
362 <varlistentry>
363 <term>Directories in the Nix store</term>
364 <listitem><para>These are simply copied to the current directory.
365 The hash part of the file name is stripped,
366 e.g. <filename>/nix/store/1wydxgby13cz...-my-sources</filename>
367 would be copied to
368 <filename>my-sources</filename>.</para></listitem>
369 </varlistentry>
370
371</variablelist>
372
373Additional file types can be supported by setting the
374<varname>unpackCmd</varname> variable (see below).</para>
375
376<para></para>
377
378<variablelist>
379 <title>Variables controlling the unpack phase</title>
380
381 <varlistentry>
382 <term><varname>srcs</varname> / <varname>src</varname></term>
383 <listitem><para>The list of source files or directories to be
384 unpacked or copied. One of these must be set.</para></listitem>
385 </varlistentry>
386
387 <varlistentry>
388 <term><varname>sourceRoot</varname></term>
389 <listitem><para>After running <function>unpackPhase</function>,
390 the generic builder changes the current directory to the directory
391 created by unpacking the sources. If there are multiple source
392 directories, you should set <varname>sourceRoot</varname> to the
393 name of the intended directory.</para></listitem>
394 </varlistentry>
395
396 <varlistentry>
397 <term><varname>setSourceRoot</varname></term>
398 <listitem><para>Alternatively to setting
399 <varname>sourceRoot</varname>, you can set
400 <varname>setSourceRoot</varname> to a shell command to be
401 evaluated by the unpack phase after the sources have been
402 unpacked. This command must set
403 <varname>sourceRoot</varname>.</para></listitem>
404 </varlistentry>
405
406 <varlistentry>
407 <term><varname>preUnpack</varname></term>
408 <listitem><para>Hook executed at the start of the unpack
409 phase.</para></listitem>
410 </varlistentry>
411
412 <varlistentry>
413 <term><varname>postUnpack</varname></term>
414 <listitem><para>Hook executed at the end of the unpack
415 phase.</para></listitem>
416 </varlistentry>
417
418 <varlistentry>
419 <term><varname>dontMakeSourcesWritable</varname></term>
420 <listitem><para>If set to <literal>1</literal>, the unpacked
421 sources are <emphasis>not</emphasis> made
422 writable. By default, they are made writable to prevent problems
423 with read-only sources. For example, copied store directories
424 would be read-only without this.</para></listitem>
425 </varlistentry>
426
427 <varlistentry>
428 <term><varname>unpackCmd</varname></term>
429 <listitem><para>The unpack phase evaluates the string
430 <literal>$unpackCmd</literal> for any unrecognised file. The path
431 to the current source file is contained in the
432 <varname>curSrc</varname> variable.</para></listitem>
433 </varlistentry>
434
435</variablelist>
436
437</section>
438
439
440<section xml:id="ssec-patch-phase"><title>The patch phase</title>
441
442<para>The patch phase applies the list of patches defined in the
443<varname>patches</varname> variable.</para>
444
445<variablelist>
446 <title>Variables controlling the patch phase</title>
447
448 <varlistentry>
449 <term><varname>patches</varname></term>
450 <listitem><para>The list of patches. They must be in the format
451 accepted by the <command>patch</command> command, and may
452 optionally be compressed using <command>gzip</command>
453 (<filename>.gz</filename>), <command>bzip2</command>
454 (<filename>.bz2</filename>) or <command>xz</command>
455 (<filename>.xz</filename>).</para></listitem>
456 </varlistentry>
457
458 <varlistentry>
459 <term><varname>patchFlags</varname></term>
460 <listitem><para>Flags to be passed to <command>patch</command>.
461 If not set, the argument <option>-p1</option> is used, which
462 causes the leading directory component to be stripped from the
463 file names in each patch.</para></listitem>
464 </varlistentry>
465
466 <varlistentry>
467 <term><varname>prePatch</varname></term>
468 <listitem><para>Hook executed at the start of the patch
469 phase.</para></listitem>
470 </varlistentry>
471
472 <varlistentry>
473 <term><varname>postPatch</varname></term>
474 <listitem><para>Hook executed at the end of the patch
475 phase.</para></listitem>
476 </varlistentry>
477
478</variablelist>
479
480</section>
481
482
483<section xml:id="ssec-configure-phase"><title>The configure phase</title>
484
485<para>The configure phase prepares the source tree for building. The
486default <function>configurePhase</function> runs
487<filename>./configure</filename> (typically an Autoconf-generated
488script) if it exists.</para>
489
490<variablelist>
491 <title>Variables controlling the configure phase</title>
492
493 <varlistentry>
494 <term><varname>configureScript</varname></term>
495 <listitem><para>The name of the configure script. It defaults to
496 <filename>./configure</filename> if it exists; otherwise, the
497 configure phase is skipped. This can actually be a command (like
498 <literal>perl ./Configure.pl</literal>).</para></listitem>
499 </varlistentry>
500
501 <varlistentry>
502 <term><varname>configureFlags</varname></term>
503 <listitem><para>Additional arguments passed to the configure
504 script.</para></listitem>
505 </varlistentry>
506
507 <varlistentry>
508 <term><varname>configureFlagsArray</varname></term>
509 <listitem><para>A shell array containing additional arguments
510 passed to the configure script. You must use this instead of
511 <varname>configureFlags</varname> if the arguments contain
512 spaces.</para></listitem>
513 </varlistentry>
514
515 <varlistentry>
516 <term><varname>dontAddPrefix</varname></term>
517 <listitem><para>By default, the flag
518 <literal>--prefix=$prefix</literal> is added to the configure
519 flags. If this is undesirable, set this variable to
520 true.</para></listitem>
521 </varlistentry>
522
523 <varlistentry>
524 <term><varname>prefix</varname></term>
525 <listitem><para>The prefix under which the package must be
526 installed, passed via the <option>--prefix</option> option to the
527 configure script. It defaults to
528 <option>$out</option>.</para></listitem>
529 </varlistentry>
530
531 <varlistentry>
532 <term><varname>dontAddDisableDepTrack</varname></term>
533 <listitem><para>By default, the flag
534 <literal>--disable-dependency-tracking</literal> is added to the
535 configure flags to speed up Automake-based builds. If this is
536 undesirable, set this variable to true.</para></listitem>
537 </varlistentry>
538
539 <varlistentry>
540 <term><varname>dontFixLibtool</varname></term>
541 <listitem><para>By default, the configure phase applies some
542 special hackery to all files called <filename>ltmain.sh</filename>
543 before running the configure script in order to improve the purity
544 of Libtool-based packages<footnote><para>It clears the
545 <varname>sys_lib_<replaceable>*</replaceable>search_path</varname>
546 variables in the Libtool script to prevent Libtool from using
547 libraries in <filename>/usr/lib</filename> and
548 such.</para></footnote>. If this is undesirable, set this
549 variable to true.</para></listitem>
550 </varlistentry>
551
552 <varlistentry>
553 <term><varname>dontDisableStatic</varname></term>
554 <listitem><para>By default, when the configure script has
555 <option>--enable-static</option>, the option
556 <option>--disable-static</option> is added to the configure flags.</para>
557 <para>If this is undesirable, set this variable to
558 true.</para></listitem>
559 </varlistentry>
560
561 <varlistentry>
562 <term><varname>preConfigure</varname></term>
563 <listitem><para>Hook executed at the start of the configure
564 phase.</para></listitem>
565 </varlistentry>
566
567 <varlistentry>
568 <term><varname>postConfigure</varname></term>
569 <listitem><para>Hook executed at the end of the configure
570 phase.</para></listitem>
571 </varlistentry>
572
573</variablelist>
574
575
576</section>
577
578
579<section xml:id="build-phase"><title>The build phase</title>
580
581<para>The build phase is responsible for actually building the package
582(e.g. compiling it). The default <function>buildPhase</function>
583simply calls <command>make</command> if a file named
584<filename>Makefile</filename>, <filename>makefile</filename> or
585<filename>GNUmakefile</filename> exists in the current directory (or
586the <varname>makefile</varname> is explicitly set); otherwise it does
587nothing.</para>
588
589<variablelist>
590 <title>Variables controlling the build phase</title>
591
592 <varlistentry>
593 <term><varname>dontBuild</varname></term>
594 <listitem><para>Set to true to skip the build phase.</para></listitem>
595 </varlistentry>
596
597 <varlistentry>
598 <term><varname>makefile</varname></term>
599 <listitem><para>The file name of the Makefile.</para></listitem>
600 </varlistentry>
601
602 <varlistentry>
603 <term><varname>makeFlags</varname></term>
604 <listitem><para>Additional flags passed to
605 <command>make</command>. These flags are also used by the default
606 install and check phase. For setting make flags specific to the
607 build phase, use <varname>buildFlags</varname> (see
608 below).</para></listitem>
609 </varlistentry>
610
611 <varlistentry>
612 <term><varname>makeFlagsArray</varname></term>
613 <listitem><para>A shell array containing additional arguments
614 passed to <command>make</command>. You must use this instead of
615 <varname>makeFlags</varname> if the arguments contain
616 spaces, e.g.
617
618<programlisting>
619makeFlagsArray=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar")
620</programlisting>
621
622 Note that shell arrays cannot be passed through environment
623 variables, so you cannot set <varname>makeFlagsArray</varname> in
624 a derivation attribute (because those are passed through
625 environment variables): you have to define them in shell
626 code.</para></listitem>
627 </varlistentry>
628
629 <varlistentry>
630 <term><varname>buildFlags</varname> / <varname>buildFlagsArray</varname></term>
631 <listitem><para>Additional flags passed to
632 <command>make</command>. Like <varname>makeFlags</varname> and
633 <varname>makeFlagsArray</varname>, but only used by the build
634 phase.</para></listitem>
635 </varlistentry>
636
637 <varlistentry>
638 <term><varname>preBuild</varname></term>
639 <listitem><para>Hook executed at the start of the build
640 phase.</para></listitem>
641 </varlistentry>
642
643 <varlistentry>
644 <term><varname>postBuild</varname></term>
645 <listitem><para>Hook executed at the end of the build
646 phase.</para></listitem>
647 </varlistentry>
648
649</variablelist>
650
651
652<para>
653You can set flags for <command>make</command> through the
654<varname>makeFlags</varname> variable.</para>
655
656<para>Before and after running <command>make</command>, the hooks
657<varname>preBuild</varname> and <varname>postBuild</varname> are
658called, respectively.</para>
659
660</section>
661
662
663<section xml:id="ssec-check-phase"><title>The check phase</title>
664
665<para>The check phase checks whether the package was built correctly
666by running its test suite. The default
667<function>checkPhase</function> calls <command>make check</command>,
668but only if the <varname>doCheck</varname> variable is enabled.</para>
669
670<variablelist>
671 <title>Variables controlling the check phase</title>
672
673 <varlistentry>
674 <term><varname>doCheck</varname></term>
675 <listitem><para>If set to a non-empty string, the check phase is
676 executed, otherwise it is skipped (default). Thus you should set
677
678 <programlisting>
679doCheck = true;</programlisting>
680
681 in the derivation to enable checks.</para></listitem>
682 </varlistentry>
683
684 <varlistentry>
685 <term><varname>makeFlags</varname> /
686 <varname>makeFlagsArray</varname> /
687 <varname>makefile</varname></term>
688 <listitem><para>See the build phase for details.</para></listitem>
689 </varlistentry>
690
691 <varlistentry>
692 <term><varname>checkTarget</varname></term>
693 <listitem><para>The make target that runs the tests. Defaults to
694 <literal>check</literal>.</para></listitem>
695 </varlistentry>
696
697 <varlistentry>
698 <term><varname>checkFlags</varname> / <varname>checkFlagsArray</varname></term>
699 <listitem><para>Additional flags passed to
700 <command>make</command>. Like <varname>makeFlags</varname> and
701 <varname>makeFlagsArray</varname>, but only used by the check
702 phase.</para></listitem>
703 </varlistentry>
704
705 <varlistentry>
706 <term><varname>preCheck</varname></term>
707 <listitem><para>Hook executed at the start of the check
708 phase.</para></listitem>
709 </varlistentry>
710
711 <varlistentry>
712 <term><varname>postCheck</varname></term>
713 <listitem><para>Hook executed at the end of the check
714 phase.</para></listitem>
715 </varlistentry>
716
717</variablelist>
718
719
720</section>
721
722
723<section xml:id="ssec-install-phase"><title>The install phase</title>
724
725<para>The install phase is responsible for installing the package in
726the Nix store under <envar>out</envar>. The default
727<function>installPhase</function> creates the directory
728<literal>$out</literal> and calls <command>make
729install</command>.</para>
730
731<variablelist>
732 <title>Variables controlling the install phase</title>
733
734 <varlistentry>
735 <term><varname>makeFlags</varname> /
736 <varname>makeFlagsArray</varname> /
737 <varname>makefile</varname></term>
738 <listitem><para>See the build phase for details.</para></listitem>
739 </varlistentry>
740
741 <varlistentry>
742 <term><varname>installTargets</varname></term>
743 <listitem><para>The make targets that perform the installation.
744 Defaults to <literal>install</literal>. Example:
745
746<programlisting>
747installTargets = "install-bin install-doc";</programlisting>
748
749 </para></listitem>
750 </varlistentry>
751
752 <varlistentry>
753 <term><varname>installFlags</varname> / <varname>installFlagsArray</varname></term>
754 <listitem><para>Additional flags passed to
755 <command>make</command>. Like <varname>makeFlags</varname> and
756 <varname>makeFlagsArray</varname>, but only used by the install
757 phase.</para></listitem>
758 </varlistentry>
759
760 <varlistentry>
761 <term><varname>preInstall</varname></term>
762 <listitem><para>Hook executed at the start of the install
763 phase.</para></listitem>
764 </varlistentry>
765
766 <varlistentry>
767 <term><varname>postInstall</varname></term>
768 <listitem><para>Hook executed at the end of the install
769 phase.</para></listitem>
770 </varlistentry>
771
772</variablelist>
773
774
775</section>
776
777
778<section xml:id="ssec-fixup-phase"><title>The fixup phase</title>
779
780<para>The fixup phase performs some (Nix-specific) post-processing
781actions on the files installed under <filename>$out</filename> by the
782install phase. The default <function>fixupPhase</function> does the
783following:
784
785<itemizedlist>
786
787 <listitem><para>It moves the <filename>man/</filename>,
788 <filename>doc/</filename> and <filename>info/</filename>
789 subdirectories of <envar>$out</envar> to
790 <filename>share/</filename>.</para></listitem>
791
792 <listitem><para>It strips libraries and executables of debug
793 information.</para></listitem>
794
795 <listitem><para>On Linux, it applies the <command>patchelf</command>
796 command to ELF executables and libraries to remove unused
797 directories from the <literal>RPATH</literal> in order to prevent
798 unnecessary runtime dependencies.</para></listitem>
799
800 <listitem><para>It rewrites the interpreter paths of shell scripts
801 to paths found in <envar>PATH</envar>. E.g.,
802 <filename>/usr/bin/perl</filename> will be rewritten to
803 <filename>/nix/store/<replaceable>some-perl</replaceable>/bin/perl</filename>
804 found in <envar>PATH</envar>.</para></listitem>
805
806</itemizedlist>
807
808</para>
809
810<variablelist>
811 <title>Variables controlling the fixup phase</title>
812
813 <varlistentry>
814 <term><varname>dontStrip</varname></term>
815 <listitem><para>If set, libraries and executables are not
816 stripped. By default, they are.</para></listitem>
817 </varlistentry>
818
819 <varlistentry>
820 <term><varname>dontMoveSbin</varname></term>
821 <listitem><para>If set, files in <filename>$out/sbin</filename> are not moved
822 to <filename>$out/bin</filename>. By default, they are.</para></listitem>
823 </varlistentry>
824
825 <varlistentry>
826 <term><varname>stripAllList</varname></term>
827 <listitem><para>List of directories to search for libraries and
828 executables from which <emphasis>all</emphasis> symbols should be
829 stripped. By default, it’s empty. Stripping all symbols is
830 risky, since it may remove not just debug symbols but also ELF
831 information necessary for normal execution.</para></listitem>
832 </varlistentry>
833
834 <varlistentry>
835 <term><varname>stripAllFlags</varname></term>
836 <listitem><para>Flags passed to the <command>strip</command>
837 command applied to the files in the directories listed in
838 <varname>stripAllList</varname>. Defaults to <option>-s</option>
839 (i.e. <option>--strip-all</option>).</para></listitem>
840 </varlistentry>
841
842 <varlistentry>
843 <term><varname>stripDebugList</varname></term>
844 <listitem><para>List of directories to search for libraries and
845 executables from which only debugging-related symbols should be
846 stripped. It defaults to <literal>lib bin
847 sbin</literal>.</para></listitem>
848 </varlistentry>
849
850 <varlistentry>
851 <term><varname>stripDebugFlags</varname></term>
852 <listitem><para>Flags passed to the <command>strip</command>
853 command applied to the files in the directories listed in
854 <varname>stripDebugList</varname>. Defaults to
855 <option>-S</option>
856 (i.e. <option>--strip-debug</option>).</para></listitem>
857 </varlistentry>
858
859 <varlistentry>
860 <term><varname>dontPatchELF</varname></term>
861 <listitem><para>If set, the <command>patchelf</command> command is
862 not used to remove unnecessary <literal>RPATH</literal> entries.
863 Only applies to Linux.</para></listitem>
864 </varlistentry>
865
866 <varlistentry>
867 <term><varname>dontPatchShebangs</varname></term>
868 <listitem><para>If set, scripts starting with
869 <literal>#!</literal> do not have their interpreter paths
870 rewritten to paths in the Nix store.</para></listitem>
871 </varlistentry>
872
873 <varlistentry>
874 <term><varname>forceShare</varname></term>
875 <listitem><para>The list of directories that must be moved from
876 <filename>$out</filename> to <filename>$out/share</filename>.
877 Defaults to <literal>man doc info</literal>.</para></listitem>
878 </varlistentry>
879
880 <varlistentry>
881 <term><varname>setupHook</varname></term>
882 <listitem><para>A package can export a <link
883 linkend="ssec-setup-hooks">setup hook</link> by setting this
884 variable. The setup hook, if defined, is copied to
885 <filename>$out/nix-support/setup-hook</filename>. Environment
886 variables are then substituted in it using <function
887 linkend="fun-substituteAll">substituteAll</function>.</para></listitem>
888 </varlistentry>
889
890 <varlistentry>
891 <term><varname>preFixup</varname></term>
892 <listitem><para>Hook executed at the start of the fixup
893 phase.</para></listitem>
894 </varlistentry>
895
896 <varlistentry>
897 <term><varname>postFixup</varname></term>
898 <listitem><para>Hook executed at the end of the fixup
899 phase.</para></listitem>
900 </varlistentry>
901
902 <varlistentry>
903 <term><varname>separateDebugInfo</varname></term>
904 <listitem><para>If set to <literal>true</literal>, the standard
905 environment will enable debug information in C/C++ builds. After
906 installation, the debug information will be separated from the
907 executables and stored in the output named
908 <literal>debug</literal>. (This output is enabled automatically;
909 you don’t need to set the <varname>outputs</varname> attribute
910 explicitly.) To be precise, the debug information is stored in
911 <filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>,
912 where <replaceable>XXYYYY…</replaceable> is the <replaceable>build
913 ID</replaceable> of the binary — a SHA-1 hash of the contents of
914 the binary. Debuggers like GDB use the build ID to look up the
915 separated debug information.</para>
916
917 <para>For example, with GDB, you can add
918
919<programlisting>
920set debug-file-directory ~/.nix-profile/lib/debug
921</programlisting>
922
923 to <filename>~/.gdbinit</filename>. GDB will then be able to find
924 debug information installed via <literal>nix-env
925 -i</literal>.</para>
926
927 </listitem>
928 </varlistentry>
929
930</variablelist>
931
932</section>
933
934
935<section xml:id="ssec-distribution-phase"><title>The distribution
936phase</title>
937
938<para>The distribution phase is intended to produce a source
939distribution of the package. The default
940<function>distPhase</function> first calls <command>make
941dist</command>, then it copies the resulting source tarballs to
942<filename>$out/tarballs/</filename>. This phase is only executed if
943the attribute <varname>doDist</varname> is set.</para>
944
945<variablelist>
946 <title>Variables controlling the distribution phase</title>
947
948 <varlistentry>
949 <term><varname>distTarget</varname></term>
950 <listitem><para>The make target that produces the distribution.
951 Defaults to <literal>dist</literal>.</para></listitem>
952 </varlistentry>
953
954 <varlistentry>
955 <term><varname>distFlags</varname> / <varname>distFlagsArray</varname></term>
956 <listitem><para>Additional flags passed to
957 <command>make</command>.</para></listitem>
958 </varlistentry>
959
960 <varlistentry>
961 <term><varname>tarballs</varname></term>
962 <listitem><para>The names of the source distribution files to be
963 copied to <filename>$out/tarballs/</filename>. It can contain
964 shell wildcards. The default is
965 <filename>*.tar.gz</filename>.</para></listitem>
966 </varlistentry>
967
968 <varlistentry>
969 <term><varname>dontCopyDist</varname></term>
970 <listitem><para>If set, no files are copied to
971 <filename>$out/tarballs/</filename>.</para></listitem>
972 </varlistentry>
973
974 <varlistentry>
975 <term><varname>preDist</varname></term>
976 <listitem><para>Hook executed at the start of the distribution
977 phase.</para></listitem>
978 </varlistentry>
979
980 <varlistentry>
981 <term><varname>postDist</varname></term>
982 <listitem><para>Hook executed at the end of the distribution
983 phase.</para></listitem>
984 </varlistentry>
985
986</variablelist>
987
988
989</section>
990
991
992</section>
993
994
995<section xml:id="ssec-stdenv-functions"><title>Shell functions</title>
996
997<para>The standard environment provides a number of useful
998functions.</para>
999
1000<variablelist>
1001
1002
1003 <varlistentry xml:id='fun-substitute'>
1004 <term><function>substitute</function>
1005 <replaceable>infile</replaceable>
1006 <replaceable>outfile</replaceable>
1007 <replaceable>subs</replaceable></term>
1008
1009 <listitem>
1010 <para>Performs string substitution on the contents of
1011 <replaceable>infile</replaceable>, writing the result to
1012 <replaceable>outfile</replaceable>. The substitutions in
1013 <replaceable>subs</replaceable> are of the following form:
1014
1015 <variablelist>
1016 <varlistentry>
1017 <term><option>--replace</option>
1018 <replaceable>s1</replaceable>
1019 <replaceable>s2</replaceable></term>
1020 <listitem><para>Replace every occurence of the string
1021 <replaceable>s1</replaceable> by
1022 <replaceable>s2</replaceable>.</para></listitem>
1023 </varlistentry>
1024
1025 <varlistentry>
1026 <term><option>--subst-var</option>
1027 <replaceable>varName</replaceable></term>
1028 <listitem><para>Replace every occurence of
1029 <literal>@<replaceable>varName</replaceable>@</literal> by
1030 the contents of the environment variable
1031 <replaceable>varName</replaceable>. This is useful for
1032 generating files from templates, using
1033 <literal>@<replaceable>...</replaceable>@</literal> in the
1034 template as placeholders.</para></listitem>
1035 </varlistentry>
1036
1037 <varlistentry>
1038 <term><option>--subst-var-by</option>
1039 <replaceable>varName</replaceable>
1040 <replaceable>s</replaceable></term>
1041 <listitem><para>Replace every occurence of
1042 <literal>@<replaceable>varName</replaceable>@</literal> by
1043 the string <replaceable>s</replaceable>.</para></listitem>
1044 </varlistentry>
1045
1046 </variablelist>
1047
1048 </para>
1049
1050 <para>Example:
1051
1052<programlisting>
1053substitute ./foo.in ./foo.out \
1054 --replace /usr/bin/bar $bar/bin/bar \
1055 --replace "a string containing spaces" "some other text" \
1056 --subst-var someVar
1057</programlisting>
1058
1059 </para>
1060
1061 <para><function>substitute</function> is implemented using the
1062 <command
1063 xlink:href="http://replace.richardlloyd.org.uk/">replace</command>
1064 command. Unlike with the <command>sed</command> command, you
1065 don’t have to worry about escaping special characters. It
1066 supports performing substitutions on binary files (such as
1067 executables), though there you’ll probably want to make sure
1068 that the replacement string is as long as the replaced
1069 string.</para>
1070
1071 </listitem>
1072 </varlistentry>
1073
1074
1075 <varlistentry xml:id='fun-substituteInPlace'>
1076 <term><function>substituteInPlace</function>
1077 <replaceable>file</replaceable>
1078 <replaceable>subs</replaceable></term>
1079 <listitem><para>Like <function>substitute</function>, but performs
1080 the substitutions in place on the file
1081 <replaceable>file</replaceable>.</para></listitem>
1082 </varlistentry>
1083
1084
1085 <varlistentry xml:id='fun-substituteAll'>
1086 <term><function>substituteAll</function>
1087 <replaceable>infile</replaceable>
1088 <replaceable>outfile</replaceable></term>
1089 <listitem><para>Replaces every occurence of
1090 <literal>@<replaceable>varName</replaceable>@</literal>, where
1091 <replaceable>varName</replaceable> is any environment variable, in
1092 <replaceable>infile</replaceable>, writing the result to
1093 <replaceable>outfile</replaceable>. For instance, if
1094 <replaceable>infile</replaceable> has the contents
1095
1096<programlisting>
1097#! @bash@/bin/sh
1098PATH=@coreutils@/bin
1099echo @foo@
1100</programlisting>
1101
1102 and the environment contains
1103 <literal>bash=/nix/store/bmwp0q28cf21...-bash-3.2-p39</literal>
1104 and
1105 <literal>coreutils=/nix/store/68afga4khv0w...-coreutils-6.12</literal>,
1106 but does not contain the variable <varname>foo</varname>, then the
1107 output will be
1108
1109<programlisting>
1110#! /nix/store/bmwp0q28cf21...-bash-3.2-p39/bin/sh
1111PATH=/nix/store/68afga4khv0w...-coreutils-6.12/bin
1112echo @foo@
1113</programlisting>
1114
1115 That is, no substitution is performed for undefined variables.</para></listitem>
1116 </varlistentry>
1117
1118
1119 <varlistentry xml:id='fun-substituteAllInPlace'>
1120 <term><function>substituteAllInPlace</function>
1121 <replaceable>file</replaceable></term>
1122 <listitem><para>Like <function>substituteAll</function>, but performs
1123 the substitutions in place on the file
1124 <replaceable>file</replaceable>.</para></listitem>
1125 </varlistentry>
1126
1127
1128 <varlistentry xml:id='fun-stripHash'>
1129 <term><function>stripHash</function>
1130 <replaceable>path</replaceable></term>
1131 <listitem><para>Strips the directory and hash part of a store
1132 path, and prints (on standard output) only the name part. For
1133 instance, <literal>stripHash
1134 /nix/store/68afga4khv0w...-coreutils-6.12</literal> print
1135 <literal>coreutils-6.12</literal>.</para></listitem>
1136 </varlistentry>
1137
1138
1139</variablelist>
1140
1141</section>
1142
1143
1144<section xml:id="ssec-setup-hooks"><title>Package setup hooks</title>
1145
1146<para>The following packages provide a setup hook:
1147
1148<variablelist>
1149
1150 <varlistentry>
1151 <term>GCC wrapper</term>
1152 <listitem><para>Adds the <filename>include</filename> subdirectory
1153 of each build input to the <envar>NIX_CFLAGS_COMPILE</envar>
1154 environment variable, and the <filename>lib</filename> and
1155 <filename>lib64</filename> subdirectories to
1156 <envar>NIX_LDFLAGS</envar>.</para></listitem>
1157 </varlistentry>
1158
1159 <varlistentry>
1160 <term>Perl</term>
1161 <listitem><para>Adds the <filename>lib/site_perl</filename> subdirectory
1162 of each build input to the <envar>PERL5LIB</envar>
1163 environment variable.</para></listitem>
1164 </varlistentry>
1165
1166 <varlistentry>
1167 <term>Python</term>
1168 <listitem><para>Adds the
1169 <filename>lib/${python.libPrefix}/site-packages</filename> subdirectory of
1170 each build input to the <envar>PYTHONPATH</envar> environment
1171 variable.</para></listitem>
1172 </varlistentry>
1173
1174 <varlistentry>
1175 <term>pkg-config</term>
1176 <listitem><para>Adds the <filename>lib/pkgconfig</filename> and
1177 <filename>share/pkgconfig</filename> subdirectories of each
1178 build input to the <envar>PKG_CONFIG_PATH</envar> environment
1179 variable.</para></listitem>
1180 </varlistentry>
1181
1182 <varlistentry>
1183 <term>Automake</term>
1184 <listitem><para>Adds the <filename>share/aclocal</filename>
1185 subdirectory of each build input to the <envar>ACLOCAL_PATH</envar>
1186 environment variable.</para></listitem>
1187 </varlistentry>
1188
1189 <varlistentry>
1190 <term>libxml2</term>
1191 <listitem><para>Adds every file named
1192 <filename>catalog.xml</filename> found under the
1193 <filename>xml/dtd</filename> and <filename>xml/xsl</filename>
1194 subdirectories of each build input to the
1195 <envar>XML_CATALOG_FILES</envar> environment
1196 variable.</para></listitem>
1197 </varlistentry>
1198
1199 <varlistentry>
1200 <term>teTeX / TeX Live</term>
1201 <listitem><para>Adds the <filename>share/texmf-nix</filename>
1202 subdirectory of each build input to the <envar>TEXINPUTS</envar>
1203 environment variable.</para></listitem>
1204 </varlistentry>
1205
1206 <varlistentry>
1207 <term>Qt 4</term>
1208 <listitem><para>Sets the <envar>QTDIR</envar> environment variable
1209 to Qt’s path.</para></listitem>
1210 </varlistentry>
1211
1212 <varlistentry>
1213 <term>gdk-pixbuf</term>
1214 <listitem><para>Exports <envar>GDK_PIXBUF_MODULE_FILE</envar>
1215 environment variable the the builder. Add librsvg package
1216 to <varname>buildInputs</varname> to get svg support.</para></listitem>
1217 </varlistentry>
1218
1219 <varlistentry>
1220 <term>GHC</term>
1221 <listitem><para>Creates a temporary package database and registers
1222 every Haskell build input in it (TODO: how?).</para></listitem>
1223 </varlistentry>
1224
1225 <varlistentry>
1226 <term>GStreamer</term>
1227 <listitem><para>Adds the
1228 GStreamer plugins subdirectory of
1229 each build input to the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> or
1230 <envar>GST_PLUGIN_SYSTEM_PATH</envar> environment variable.</para></listitem>
1231 </varlistentry>
1232
1233</variablelist>
1234
1235</para>
1236
1237</section>
1238
1239
1240<section xml:id="sec-purity-in-nixpkgs"><title>Purity in Nixpkgs</title>
1241
1242<para>[measures taken to prevent dependencies on packages outside the
1243store, and what you can do to prevent them]</para>
1244
1245<para>GCC doesn't search in locations such as
1246<filename>/usr/include</filename>. In fact, attempts to add such
1247directories through the <option>-I</option> flag are filtered out.
1248Likewise, the linker (from GNU binutils) doesn't search in standard
1249locations such as <filename>/usr/lib</filename>. Programs built on
1250Linux are linked against a GNU C Library that likewise doesn't search
1251in the default system locations.</para>
1252
1253</section>
1254
1255
1256</chapter>
1257