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</variablelist>
903
904</section>
905
906
907<section xml:id="ssec-distribution-phase"><title>The distribution
908phase</title>
909
910<para>The distribution phase is intended to produce a source
911distribution of the package. The default
912<function>distPhase</function> first calls <command>make
913dist</command>, then it copies the resulting source tarballs to
914<filename>$out/tarballs/</filename>. This phase is only executed if
915the attribute <varname>doDist</varname> is set.</para>
916
917<variablelist>
918 <title>Variables controlling the distribution phase</title>
919
920 <varlistentry>
921 <term><varname>distTarget</varname></term>
922 <listitem><para>The make target that produces the distribution.
923 Defaults to <literal>dist</literal>.</para></listitem>
924 </varlistentry>
925
926 <varlistentry>
927 <term><varname>distFlags</varname> / <varname>distFlagsArray</varname></term>
928 <listitem><para>Additional flags passed to
929 <command>make</command>.</para></listitem>
930 </varlistentry>
931
932 <varlistentry>
933 <term><varname>tarballs</varname></term>
934 <listitem><para>The names of the source distribution files to be
935 copied to <filename>$out/tarballs/</filename>. It can contain
936 shell wildcards. The default is
937 <filename>*.tar.gz</filename>.</para></listitem>
938 </varlistentry>
939
940 <varlistentry>
941 <term><varname>dontCopyDist</varname></term>
942 <listitem><para>If set, no files are copied to
943 <filename>$out/tarballs/</filename>.</para></listitem>
944 </varlistentry>
945
946 <varlistentry>
947 <term><varname>preDist</varname></term>
948 <listitem><para>Hook executed at the start of the distribution
949 phase.</para></listitem>
950 </varlistentry>
951
952 <varlistentry>
953 <term><varname>postDist</varname></term>
954 <listitem><para>Hook executed at the end of the distribution
955 phase.</para></listitem>
956 </varlistentry>
957
958</variablelist>
959
960
961</section>
962
963
964</section>
965
966
967<section xml:id="ssec-stdenv-functions"><title>Shell functions</title>
968
969<para>The standard environment provides a number of useful
970functions.</para>
971
972<variablelist>
973
974
975 <varlistentry xml:id='fun-substitute'>
976 <term><function>substitute</function>
977 <replaceable>infile</replaceable>
978 <replaceable>outfile</replaceable>
979 <replaceable>subs</replaceable></term>
980
981 <listitem>
982 <para>Performs string substitution on the contents of
983 <replaceable>infile</replaceable>, writing the result to
984 <replaceable>outfile</replaceable>. The substitutions in
985 <replaceable>subs</replaceable> are of the following form:
986
987 <variablelist>
988 <varlistentry>
989 <term><option>--replace</option>
990 <replaceable>s1</replaceable>
991 <replaceable>s2</replaceable></term>
992 <listitem><para>Replace every occurence of the string
993 <replaceable>s1</replaceable> by
994 <replaceable>s2</replaceable>.</para></listitem>
995 </varlistentry>
996
997 <varlistentry>
998 <term><option>--subst-var</option>
999 <replaceable>varName</replaceable></term>
1000 <listitem><para>Replace every occurence of
1001 <literal>@<replaceable>varName</replaceable>@</literal> by
1002 the contents of the environment variable
1003 <replaceable>varName</replaceable>. This is useful for
1004 generating files from templates, using
1005 <literal>@<replaceable>...</replaceable>@</literal> in the
1006 template as placeholders.</para></listitem>
1007 </varlistentry>
1008
1009 <varlistentry>
1010 <term><option>--subst-var-by</option>
1011 <replaceable>varName</replaceable>
1012 <replaceable>s</replaceable></term>
1013 <listitem><para>Replace every occurence of
1014 <literal>@<replaceable>varName</replaceable>@</literal> by
1015 the string <replaceable>s</replaceable>.</para></listitem>
1016 </varlistentry>
1017
1018 </variablelist>
1019
1020 </para>
1021
1022 <para>Example:
1023
1024<programlisting>
1025substitute ./foo.in ./foo.out \
1026 --replace /usr/bin/bar $bar/bin/bar \
1027 --replace "a string containing spaces" "some other text" \
1028 --subst-var someVar
1029</programlisting>
1030
1031 </para>
1032
1033 <para><function>substitute</function> is implemented using the
1034 <command
1035 xlink:href="http://replace.richardlloyd.org.uk/">replace</command>
1036 command. Unlike with the <command>sed</command> command, you
1037 don’t have to worry about escaping special characters. It
1038 supports performing substitutions on binary files (such as
1039 executables), though there you’ll probably want to make sure
1040 that the replacement string is as long as the replaced
1041 string.</para>
1042
1043 </listitem>
1044 </varlistentry>
1045
1046
1047 <varlistentry xml:id='fun-substituteInPlace'>
1048 <term><function>substituteInPlace</function>
1049 <replaceable>file</replaceable>
1050 <replaceable>subs</replaceable></term>
1051 <listitem><para>Like <function>substitute</function>, but performs
1052 the substitutions in place on the file
1053 <replaceable>file</replaceable>.</para></listitem>
1054 </varlistentry>
1055
1056
1057 <varlistentry xml:id='fun-substituteAll'>
1058 <term><function>substituteAll</function>
1059 <replaceable>infile</replaceable>
1060 <replaceable>outfile</replaceable></term>
1061 <listitem><para>Replaces every occurence of
1062 <literal>@<replaceable>varName</replaceable>@</literal>, where
1063 <replaceable>varName</replaceable> is any environment variable, in
1064 <replaceable>infile</replaceable>, writing the result to
1065 <replaceable>outfile</replaceable>. For instance, if
1066 <replaceable>infile</replaceable> has the contents
1067
1068<programlisting>
1069#! @bash@/bin/sh
1070PATH=@coreutils@/bin
1071echo @foo@
1072</programlisting>
1073
1074 and the environment contains
1075 <literal>bash=/nix/store/bmwp0q28cf21...-bash-3.2-p39</literal>
1076 and
1077 <literal>coreutils=/nix/store/68afga4khv0w...-coreutils-6.12</literal>,
1078 but does not contain the variable <varname>foo</varname>, then the
1079 output will be
1080
1081<programlisting>
1082#! /nix/store/bmwp0q28cf21...-bash-3.2-p39/bin/sh
1083PATH=/nix/store/68afga4khv0w...-coreutils-6.12/bin
1084echo @foo@
1085</programlisting>
1086
1087 That is, no substitution is performed for undefined variables.</para></listitem>
1088 </varlistentry>
1089
1090
1091 <varlistentry xml:id='fun-substituteAllInPlace'>
1092 <term><function>substituteAllInPlace</function>
1093 <replaceable>file</replaceable></term>
1094 <listitem><para>Like <function>substituteAll</function>, but performs
1095 the substitutions in place on the file
1096 <replaceable>file</replaceable>.</para></listitem>
1097 </varlistentry>
1098
1099
1100 <varlistentry xml:id='fun-stripHash'>
1101 <term><function>stripHash</function>
1102 <replaceable>path</replaceable></term>
1103 <listitem><para>Strips the directory and hash part of a store
1104 path, and prints (on standard output) only the name part. For
1105 instance, <literal>stripHash
1106 /nix/store/68afga4khv0w...-coreutils-6.12</literal> print
1107 <literal>coreutils-6.12</literal>.</para></listitem>
1108 </varlistentry>
1109
1110
1111</variablelist>
1112
1113</section>
1114
1115
1116<section xml:id="ssec-setup-hooks"><title>Package setup hooks</title>
1117
1118<para>The following packages provide a setup hook:
1119
1120<variablelist>
1121
1122 <varlistentry>
1123 <term>GCC wrapper</term>
1124 <listitem><para>Adds the <filename>include</filename> subdirectory
1125 of each build input to the <envar>NIX_CFLAGS_COMPILE</envar>
1126 environment variable, and the <filename>lib</filename> and
1127 <filename>lib64</filename> subdirectories to
1128 <envar>NIX_LDFLAGS</envar>.</para></listitem>
1129 </varlistentry>
1130
1131 <varlistentry>
1132 <term>Perl</term>
1133 <listitem><para>Adds the <filename>lib/site_perl</filename> subdirectory
1134 of each build input to the <envar>PERL5LIB</envar>
1135 environment variable.</para></listitem>
1136 </varlistentry>
1137
1138 <varlistentry>
1139 <term>Python</term>
1140 <listitem><para>Adds the
1141 <filename>lib/${python.libPrefix}/site-packages</filename> subdirectory of
1142 each build input to the <envar>PYTHONPATH</envar> environment
1143 variable.</para></listitem>
1144 </varlistentry>
1145
1146 <varlistentry>
1147 <term>pkg-config</term>
1148 <listitem><para>Adds the <filename>lib/pkgconfig</filename> and
1149 <filename>share/pkgconfig</filename> subdirectories of each
1150 build input to the <envar>PKG_CONFIG_PATH</envar> environment
1151 variable.</para></listitem>
1152 </varlistentry>
1153
1154 <varlistentry>
1155 <term>Automake</term>
1156 <listitem><para>Adds the <filename>share/aclocal</filename>
1157 subdirectory of each build input to the <envar>ACLOCAL_PATH</envar>
1158 environment variable.</para></listitem>
1159 </varlistentry>
1160
1161 <varlistentry>
1162 <term>libxml2</term>
1163 <listitem><para>Adds every file named
1164 <filename>catalog.xml</filename> found under the
1165 <filename>xml/dtd</filename> and <filename>xml/xsl</filename>
1166 subdirectories of each build input to the
1167 <envar>XML_CATALOG_FILES</envar> environment
1168 variable.</para></listitem>
1169 </varlistentry>
1170
1171 <varlistentry>
1172 <term>teTeX / TeX Live</term>
1173 <listitem><para>Adds the <filename>share/texmf-nix</filename>
1174 subdirectory of each build input to the <envar>TEXINPUTS</envar>
1175 environment variable.</para></listitem>
1176 </varlistentry>
1177
1178 <varlistentry>
1179 <term>Qt</term>
1180 <listitem><para>Sets the <envar>QTDIR</envar> environment variable
1181 to Qt’s path.</para></listitem>
1182 </varlistentry>
1183
1184 <varlistentry>
1185 <term>gdk-pixbuf</term>
1186 <listitem><para>Exports <envar>GDK_PIXBUF_MODULE_FILE</envar>
1187 environment variable the the builder. Add librsvg package
1188 to <varname>buildInputs</varname> to get svg support.</para></listitem>
1189 </varlistentry>
1190
1191 <varlistentry>
1192 <term>GHC</term>
1193 <listitem><para>Creates a temporary package database and registers
1194 every Haskell build input in it (TODO: how?).</para></listitem>
1195 </varlistentry>
1196
1197 <varlistentry>
1198 <term>GStreamer</term>
1199 <listitem><para>Adds the
1200 GStreamer plugins subdirectory of
1201 each build input to the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> or
1202 <envar>GST_PLUGIN_SYSTEM_PATH</envar> environment variable.</para></listitem>
1203 </varlistentry>
1204
1205</variablelist>
1206
1207</para>
1208
1209</section>
1210
1211
1212<section xml:id="sec-purity-in-nixpkgs"><title>Purity in Nixpkgs</title>
1213
1214<para>[measures taken to prevent dependencies on packages outside the
1215store, and what you can do to prevent them]</para>
1216
1217<para>GCC doesn't search in locations such as
1218<filename>/usr/include</filename>. In fact, attempts to add such
1219directories through the <option>-I</option> flag are filtered out.
1220Likewise, the linker (from GNU binutils) doesn't search in standard
1221locations such as <filename>/usr/lib</filename>. Programs built on
1222Linux are linked against a GNU C Library that likewise doesn't search
1223in the default system locations.</para>
1224
1225</section>
1226
1227
1228</chapter>
1229