doc/stdenv.xml

   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
   9 provides a environment for building Unix packages that does a lot of
  10 common build tasks automatically.  In fact, for Unix packages that use
  11 the standard <literal>./configure; make; make install</literal> build
  12 interface, you don’t need to write a build script at all; the standard
  13 environment does everything automatically.  If
  14 <literal>stdenv</literal> doesn’t do what you need automatically, you
  15 can easily customise or override the various build phases.</para>
  16
  17
  18 <section><title>Using <literal>stdenv</literal></title>
  19
  20 <para>To build a package with the standard environment, you use the
  21 function <varname>stdenv.mkDerivation</varname>, instead of the
  22 primitive built-in function <varname>derivation</varname>, e.g.
  23
  24 <programlisting>
  25 stdenv.mkDerivation {
  26   name = "libfoo-1.2.3";
  27   src = fetchurl {
  28     url = http://example.org/libfoo-1.2.3.tar.bz2;
  29     md5 = "e1ec107956b6ddcb0b8b0679367e9ac9";
  30   };
  31 }</programlisting>
  32
  33 (<varname>stdenv</varname> needs to be in scope, so if you write this
  34 in a separate Nix expression from
  35 <filename>pkgs/all-packages.nix</filename>, you need to pass it as a
  36 function argument.)  Specifying a <varname>name</varname> and a
  37 <varname>src</varname> is the absolute minimum you need to do.  Many
  38 packages have dependencies that are not provided in the standard
  39 environment.  It’s usually sufficient to specify those dependencies in
  40 the <varname>buildInputs</varname> attribute:
  41
  42 <programlisting>
  43 stdenv.mkDerivation {
  44   name = "libfoo-1.2.3";
  45   ...
  46   buildInputs = [libbar perl ncurses];
  47 }</programlisting>
  48
  49 This attribute ensures that the <filename>bin</filename>
  50 subdirectories of these packages appear in the <envar>PATH</envar>
  51 environment variable during the build, that their
  52 <filename>include</filename> subdirectories are searched by the C
  53 compiler, and so on.  (See <xref linkend="ssec-setup-hooks"/> for
  54 details.)</para>
  55
  56 <para>Often it is necessary to override or modify some aspect of the
  57 build.  To make this easier, the standard environment breaks the
  58 package build into a number of <emphasis>phases</emphasis>, all of
  59 which can be overriden or modified individually: unpacking the
  60 sources, applying patches, configuring, building, and installing.
  61 (There are some others; see <xref linkend="ssec-stdenv-phases"/>.)
  62 For instance, a package that doesn’t supply a makefile but instead has
  63 to be compiled “manually” could be handled like this:
  64
  65 <programlisting>
  66 stdenv.mkDerivation {
  67   name = "fnord-4.5";
  68   ...
  69   buildPhase = ''
  70     gcc foo.c -o foo
  71   '';
  72   installPhase = ''
  73     ensureDir $out/bin
  74     cp foo $out/bin
  75   '';
  76 }</programlisting>
  77
  78 (Note the use of <literal>''</literal>-style string literals, which
  79 are very convenient for large multi-line script fragments because they
  80 don’t need escaping of <literal>"</literal> and <literal>\</literal>,
  81 and because indentation is intelligently removed.)</para>
  82
  83 <para>There are many other attributes to customise the build.  These
  84 are listed in <xref linkend="ssec-stdenv-attributes"/>.</para>
  85
  86 <para>While the standard environment provides a generic builder, you
  87 can still supply your own build script:
  88
  89 <programlisting>
  90 stdenv.mkDerivation {
  91   name = "libfoo-1.2.3";
  92   ...
  93   builder = ./builder.sh;
  94 }</programlisting>
  95
  96 where the builder can do anything it wants, but typically starts with
  97
  98 <programlisting>
  99 source $stdenv/setup
 100 </programlisting>
 101
 102 to let <literal>stdenv</literal> set up the environment (e.g., process
 103 the <varname>buildInputs</varname>).  If you want, you can still use
 104 <literal>stdenv</literal>’s generic builder:
 105
 106 <programlisting>
 107 source $stdenv/setup
 108
 109 buildPhase() {
 110   echo "... this is my custom build phase ..."
 111   gcc foo.c -o foo
 112 }
 113
 114 installPhase() {
 115   ensureDir $out/bin
 116   cp foo $out/bin
 117 }
 118
 119 genericBuild
 120 </programlisting>
 121
 122 </para>
 123
 124 </section>
 125
 126
 127 <section><title>Tools provided by <literal>stdenv</literal></title>
 128
 129 <para>The standard environment provides the following packages:
 130
 131 <itemizedlist>
 132
 133   <listitem><para>The GNU C Compiler, configured with C and C++
 134   support.</para></listitem>
 135
 136   <listitem><para>GNU coreutils (contains a few dozen standard Unix
 137   commands).</para></listitem>
 138
 139   <listitem><para>GNU findutils (contains
 140   <command>find</command>).</para></listitem>
 141
 142   <listitem><para>GNU diffutils (contains <command>diff</command>,
 143   <command>cmp</command>).</para></listitem>
 144
 145   <listitem><para>GNU <command>sed</command>.</para></listitem>
 146
 147   <listitem><para>GNU <command>grep</command>.</para></listitem>
 148
 149   <listitem><para>GNU <command>awk</command>.</para></listitem>
 150
 151   <listitem><para>GNU <command>tar</command>.</para></listitem>
 152
 153   <listitem><para><command>gzip</command> and
 154   <command>bzip2</command>.</para></listitem>
 155
 156   <listitem><para>GNU Make.  It has been patched to provide
 157   <quote>nested</quote> output that can be fed into the
 158   <command>nix-log2xml</command> command and
 159   <command>log2html</command> stylesheet to create a structured,
 160   readable output of the build steps performed by
 161   Make.</para></listitem>
 162
 163   <listitem><para>Bash.  This is the shell used for all builders in
 164   the Nix Packages collection.  Not using <command>/bin/sh</command>
 165   removes a large source of portability problems.</para></listitem>
 166
 167   <listitem><para>The <command>patch</command>
 168   command.</para></listitem>
 169
 170 </itemizedlist>
 171
 172 </para>
 173
 174 <para>On Linux, <literal>stdenv</literal> also includes the
 175 <command>patchelf</command> utility.</para>
 176
 177 </section>
 178
 179
 180 <section xml:id="ssec-stdenv-attributes"><title>Attributes</title>
 181
 182 <variablelist>
 183   <title>Variables affecting <literal>stdenv</literal>
 184   initialisation</title>
 185
 186   <varlistentry>
 187     <term><varname>NIX_DEBUG</varname></term>
 188     <listitem><para>If set, <literal>stdenv</literal> will print some
 189     debug information during the build.  In particular, the
 190     <command>gcc</command> and <command>ld</command> wrapper scripts
 191     will print out the complete command line passed to the wrapped
 192     tools.</para></listitem>
 193   </varlistentry>
 194
 195   <varlistentry>
 196     <term><varname>buildInputs</varname></term>
 197     <listitem><para>A list of dependencies used by
 198     <literal>stdenv</literal> to set up the environment for the build.
 199     For each dependency <replaceable>dir</replaceable>, the directory
 200     <filename><replaceable>dir</replaceable>/bin</filename>, if it
 201     exists, is added to the <envar>PATH</envar> environment variable.
 202     Other environment variables are also set up via a pluggable
 203     mechanism.  For instance, if <varname>buildInputs</varname>
 204     contains Perl, then the <filename>lib/site_perl</filename>
 205     subdirectory of each input is added to the <envar>PERL5LIB</envar>
 206     environment variable.  See <xref linkend="ssec-setup-hooks"/> for
 207     details.</para></listitem>
 208   </varlistentry>
 209
 210   <varlistentry>
 211     <term><varname>propagatedBuildInputs</varname></term>
 212     <listitem><para>Like <varname>buildInputs</varname>, but these
 213     dependencies are <emphasis>propagated</emphasis>: that is, the
 214     dependencies listed here are added to the
 215     <varname>buildInputs</varname> of any package that uses
 216     <emphasis>this</emphasis> package as a dependency.  So if package
 217     Y has <literal>propagatedBuildInputs = [X]</literal>, and package
 218     Z has <literal>buildInputs = [Y]</literal>, then package X will
 219     appear in Z’s build environment automatically.</para></listitem>
 220   </varlistentry>
 221
 222
 223 </variablelist>
 224
 225 </section>
 226
 227
 228 <section xml:id="ssec-stdenv-phases"><title>Phases</title>
 229
 230 <para>The generic builder has a number of <emphasis>phases</emphasis>.
 231 Package builds are split into phases to make it easier to override
 232 specific parts of the build (e.g., unpacking the sources or installing
 233 the binaries).  Furthermore, it allows a nicer presentation of build
 234 logs in the Nix build farm.</para>
 235
 236 <para>Each phase can be overriden in its entirety either by setting
 237 the environment variable
 238 <varname><replaceable>name</replaceable>Phase</varname> to a string
 239 containing some shell commands to be executed, or by redefining the
 240 shell function
 241 <varname><replaceable>name</replaceable>Phase</varname>.  The former
 242 is convenient to override a phase from the derivation, while the
 243 latter is convenient from a build script.</para>
 244
 245
 246 <section><title>Controlling phases</title>
 247
 248 <para>There are a number of variables that control what phases are
 249 executed and in what order:
 250
 251 <variablelist>
 252   <title>Variables affecting phase control</title>
 253
 254   <varlistentry>
 255     <term><varname>phases</varname></term>
 256     <listitem>
 257       <para>Specifies the phases.  You can change the order in which
 258       phases are executed, or add new phases, by setting this
 259       variable.  If it’s not set, the default value is used, which is
 260       <literal>$prePhases unpackPhase patchPhase $preConfigurePhases
 261       configurePhase $preBuildPhases buildPhase checkPhase
 262       $preInstallPhases installPhase fixupPhase $preDistPhases
 263       distPhase $postPhases</literal>.
 264       </para>
 265
 266       <para>Usually, if you just want to add a few phases, it’s more
 267       convenient to set one of the variables below (such as
 268       <varname>preInstallPhases</varname>), as you then don’t specify
 269       all the normal phases.</para>
 270     </listitem>
 271   </varlistentry>
 272
 273   <varlistentry>
 274     <term><varname>prePhases</varname></term>
 275     <listitem>
 276       <para>Additional phases executed before any of the default phases.</para>
 277     </listitem>
 278   </varlistentry>
 279
 280   <varlistentry>
 281     <term><varname>preConfigurePhases</varname></term>
 282     <listitem>
 283       <para>Additional phases executed just before the configure phase.</para>
 284     </listitem>
 285   </varlistentry>
 286
 287   <varlistentry>
 288     <term><varname>preBuildPhases</varname></term>
 289     <listitem>
 290       <para>Additional phases executed just before the build phase.</para>
 291     </listitem>
 292   </varlistentry>
 293
 294   <varlistentry>
 295     <term><varname>preInstallPhases</varname></term>
 296     <listitem>
 297       <para>Additional phases executed just before the install phase.</para>
 298     </listitem>
 299   </varlistentry>
 300
 301   <varlistentry>
 302     <term><varname>preDistPhases</varname></term>
 303     <listitem>
 304       <para>Additional phases executed just before the distribution phase.</para>
 305     </listitem>
 306   </varlistentry>
 307
 308   <varlistentry>
 309     <term><varname>postPhases</varname></term>
 310     <listitem>
 311       <para>Additional phases executed after any of the default
 312       phases.</para>
 313     </listitem>
 314   </varlistentry>
 315
 316 </variablelist>
 317
 318 </para>
 319
 320 </section>
 321
 322
 323 <section><title>The unpack phase</title>
 324
 325 <para>The unpack phase is responsible for unpacking the source code of
 326 the package.  The default implementation of
 327 <function>unpackPhase</function> unpacks the source files listed in
 328 the <envar>src</envar> environment variable to the current directory.
 329 It supports the following files by default:
 330
 331 <variablelist>
 332
 333   <varlistentry>
 334     <term>Tar files</term>
 335     <listitem><para>These can optionally be compressed using
 336     <command>gzip</command> (<filename>.tar.gz</filename>,
 337     <filename>.tgz</filename> or <filename>.tar.Z</filename>) or
 338     <command>bzip2</command> (<filename>.tar.bz2</filename> or
 339     <filename>.tbz2</filename>).</para></listitem>
 340   </varlistentry>
 341
 342   <varlistentry>
 343     <term>Zip files</term>
 344     <listitem><para>Zip files are unpacked using
 345     <command>unzip</command>.  However, <command>unzip</command> is
 346     not in the standard environment, so you should add it to
 347     <varname>buildInputs</varname> yourself.</para></listitem>
 348   </varlistentry>
 349
 350   <varlistentry>
 351     <term>Directories in the Nix store</term>
 352     <listitem><para>These are simply copied to the current directory.
 353     The hash part of the file name is stripped,
 354     e.g. <filename>/nix/store/1wydxgby13cz...-my-sources</filename>
 355     would be copied to
 356     <filename>my-sources</filename>.</para></listitem>
 357   </varlistentry>
 358
 359 </variablelist>
 360
 361 Additional file types can be supported by setting the
 362 <varname>unpackCmd</varname> variable (see below).</para>
 363
 364 <para></para>
 365
 366 <variablelist>
 367   <title>Variables controlling the unpack phase</title>
 368
 369   <varlistentry>
 370     <term><varname>srcs</varname> / <varname>src</varname></term>
 371     <listitem><para>The list of source files or directories to be
 372     unpacked or copied.  One of these must be set.</para></listitem>
 373   </varlistentry>
 374
 375   <varlistentry>
 376     <term><varname>sourceRoot</varname></term>
 377     <listitem><para>After running <function>unpackPhase</function>,
 378     the generic builder changes the current directory to the directory
 379     created by unpacking the sources.  If there are multiple source
 380     directories, you should set <varname>sourceRoot</varname> to the
 381     name of the intended directory.</para></listitem>
 382   </varlistentry>
 383
 384   <varlistentry>
 385     <term><varname>setSourceRoot</varname></term>
 386     <listitem><para>Alternatively to setting
 387     <varname>sourceRoot</varname>, you can set
 388     <varname>setSourceRoot</varname> to a shell command to be
 389     evaluated by the unpack phase after the sources have been
 390     unpacked.  This command must set
 391     <varname>sourceRoot</varname>.</para></listitem>
 392   </varlistentry>
 393
 394   <varlistentry>
 395     <term><varname>preUnpack</varname></term>
 396     <listitem><para>Hook executed at the start of the unpack
 397     phase.</para></listitem>
 398   </varlistentry>
 399
 400   <varlistentry>
 401     <term><varname>postUnpack</varname></term>
 402     <listitem><para>Hook executed at the end of the unpack
 403     phase.</para></listitem>
 404   </varlistentry>
 405
 406   <varlistentry>
 407     <term><varname>dontMakeSourcesWritable</varname></term>
 408     <listitem><para>If set to <literal>1</literal>, the unpacked
 409     sources are <emphasis>not</emphasis> made
 410     writable.  By default, they are made writable to prevent problems
 411     with read-only sources.  For example, copied store directories
 412     would be read-only without this.</para></listitem>
 413   </varlistentry>
 414
 415   <varlistentry>
 416     <term><varname>unpackCmd</varname></term>
 417     <listitem><para>The unpack phase evaluates the string
 418     <literal>$unpackCmd</literal> for any unrecognised file.  The path
 419     to the current source file is contained in the
 420     <varname>curSrc</varname> variable.</para></listitem>
 421   </varlistentry>
 422
 423 </variablelist>
 424
 425 </section>
 426
 427
 428 <section><title>The patch phase</title>
 429
 430 <para>The patch phase applies the list of patches defined in the
 431 <varname>patches</varname> variable.</para>
 432
 433 <variablelist>
 434   <title>Variables controlling the patch phase</title>
 435
 436   <varlistentry>
 437     <term><varname>patches</varname></term>
 438     <listitem><para>The list of patches.  They must be in the format
 439     accepted by the <command>patch</command> command, and may
 440     optionally be compressed using <command>gzip</command>
 441     (<filename>.gz</filename>) or <command>bzip2</command>
 442     (<filename>.bz2</filename>).</para></listitem>
 443   </varlistentry>
 444
 445   <varlistentry>
 446     <term><varname>patchFlags</varname></term>
 447     <listitem><para>Flags to be passed to <command>patch</command>.
 448     If not set, the argument <option>-p1</option> is used, which
 449     causes the leading directory component to be stripped from the
 450     file names in each patch.</para></listitem>
 451   </varlistentry>
 452
 453   <varlistentry>
 454     <term><varname>prePatch</varname></term>
 455     <listitem><para>Hook executed at the start of the patch
 456     phase.</para></listitem>
 457   </varlistentry>
 458
 459   <varlistentry>
 460     <term><varname>postPatch</varname></term>
 461     <listitem><para>Hook executed at the end of the patch
 462     phase.</para></listitem>
 463   </varlistentry>
 464
 465 </variablelist>
 466
 467 </section>
 468
 469
 470 <section><title>The configure phase</title>
 471
 472 <para>The configure phase prepares the source tree for building.  The
 473 default <function>unpackPhase</function> runs
 474 <filename>./configure</filename> (typically an Autoconf-generated
 475 script) if it exists.</para>
 476
 477 <variablelist>
 478   <title>Variables controlling the configure phase</title>
 479
 480   <varlistentry>
 481     <term><varname>configureScript</varname></term>
 482     <listitem><para>The name of the configure script.  It defaults to
 483     <filename>./configure</filename> if it exists; otherwise, the
 484     configure phase is skipped.  This can actually be a command (like
 485     <literal>perl ./Configure.pl</literal>).</para></listitem>
 486   </varlistentry>
 487
 488   <varlistentry>
 489     <term><varname>configureFlags</varname></term>
 490     <listitem><para>Additional arguments passed to the configure
 491     script.</para></listitem>
 492   </varlistentry>
 493
 494   <varlistentry>
 495     <term><varname>configureFlagsArray</varname></term>
 496     <listitem><para>A shell array containing additional arguments
 497     passed to the configure script.  You must use this instead of
 498     <varname>configureFlags</varname> if the arguments contain
 499     spaces.</para></listitem>
 500   </varlistentry>
 501
 502   <varlistentry>
 503     <term><varname>dontAddPrefix</varname></term>
 504     <listitem><para>By default, the flag
 505     <literal>--prefix=$prefix</literal> is added to the configure
 506     flags.  If this is undesirable, set this variable to a non-empty
 507     value.</para></listitem>
 508   </varlistentry>
 509
 510   <varlistentry>
 511     <term><varname>prefix</varname></term>
 512     <listitem><para>The prefix under which the package must be
 513     installed, passed via the <option>--prefix</option> option to the
 514     configure script.  It defaults to
 515     <option>$out</option>.</para></listitem>
 516   </varlistentry>
 517
 518   <varlistentry>
 519     <term><varname>dontAddDisableDepTrack</varname></term>
 520     <listitem><para>By default, the flag
 521     <literal>--disable-dependency-tracking</literal> is added to the
 522     configure flags to speed up Automake-based builds.  If this is
 523     undesirable, set this variable to a non-empty
 524     value.</para></listitem>
 525   </varlistentry>
 526
 527   <varlistentry>
 528     <term><varname>dontFixLibtool</varname></term>
 529     <listitem><para>By default, the configure phase applies some
 530     special hackery to all files called <filename>ltmain.sh</filename>
 531     before running the configure script in order to improve the purity
 532     of Libtool-based packages<footnote><para>It clears the
 533     <varname>sys_lib_<replaceable>*</replaceable>search_path</varname>
 534     variables in the Libtool script to prevent Libtool from using
 535     libraries in <filename>/usr/lib</filename> and
 536     such.</para></footnote>.  If this is undesirable, set this
 537     variable to a non-empty value.</para></listitem>
 538   </varlistentry>
 539
 540   <varlistentry>
 541     <term><varname>preConfigure</varname></term>
 542     <listitem><para>Hook executed at the start of the configure
 543     phase.</para></listitem>
 544   </varlistentry>
 545
 546   <varlistentry>
 547     <term><varname>postConfigure</varname></term>
 548     <listitem><para>Hook executed at the end of the configure
 549     phase.</para></listitem>
 550   </varlistentry>
 551
 552 </variablelist>
 553
 554
 555 </section>
 556
 557
 558 <section><title>The build phase</title>
 559
 560 <para>The build phase is responsible for actually building the package
 561 (e.g. compiling it).  The default <function>buildPhase</function>
 562 simply calls <command>make</command> if a file named
 563 <filename>Makefile</filename>, <filename>makefile</filename> or
 564 <filename>GNUmakefile</filename> exists in the current directory (or
 565 the <varname>makefile</varname> is explicitly set); otherwise it does
 566 nothing.</para>
 567
 568 <variablelist>
 569   <title>Variables controlling the build phase</title>
 570
 571   <varlistentry>
 572     <term><varname>makefile</varname></term>
 573     <listitem><para>The file name of the Makefile.</para></listitem>
 574   </varlistentry>
 575
 576   <varlistentry>
 577     <term><varname>makeFlags</varname></term>
 578     <listitem><para>Additional flags passed to
 579     <command>make</command>.  These flags are also used by the default
 580     install and check phase.  For setting make flags specific to the
 581     build phase, use <varname>buildFlags</varname> (see
 582     below).</para></listitem>
 583   </varlistentry>
 584
 585   <varlistentry>
 586     <term><varname>makeFlagsArray</varname></term>
 587     <listitem><para>A shell array containing additional arguments
 588     passed to <command>make</command>.  You must use this instead of
 589     <varname>makeFlags</varname> if the arguments contain
 590     spaces, e.g.
 591
 592 <programlisting>
 593 makeFlagsArray=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar")
 594 </programlisting>
 595
 596     Note that shell arrays cannot be passed through environment
 597     variables, so you cannot set <varname>makeFlagsArray</varname> in
 598     a derivation attribute (because those are passed through
 599     environment variables): you have to define them in shell
 600     code.</para></listitem>
 601   </varlistentry>
 602
 603   <varlistentry>
 604     <term><varname>buildFlags</varname> / <varname>buildFlagsArray</varname></term>
 605     <listitem><para>Additional flags passed to
 606     <command>make</command>.  Like <varname>makeFlags</varname> and
 607     <varname>makeFlagsArray</varname>, but only used by the build
 608     phase.</para></listitem>
 609   </varlistentry>
 610
 611   <varlistentry>
 612     <term><varname>preBuild</varname></term>
 613     <listitem><para>Hook executed at the start of the build
 614     phase.</para></listitem>
 615   </varlistentry>
 616
 617   <varlistentry>
 618     <term><varname>postBuild</varname></term>
 619     <listitem><para>Hook executed at the end of the build
 620     phase.</para></listitem>
 621   </varlistentry>
 622
 623 </variablelist>
 624
 625
 626 <para>
 627 You can set flags for <command>make</command> through the
 628 <varname>makeFlags</varname> variable.</para>
 629
 630 <para>Before and after running <command>make</command>, the hooks
 631 <varname>preBuild</varname> and <varname>postBuild</varname> are
 632 called, respectively.</para>
 633
 634 </section>
 635
 636
 637 <section><title>The check phase</title>
 638
 639 <para>The check phase checks whether the package was built correctly
 640 by running its test suite.  The default
 641 <function>checkPhase</function> calls <command>make check</command>,
 642 but only if the <varname>doCheck</varname> variable is enabled.</para>
 643
 644 <variablelist>
 645   <title>Variables controlling the check phase</title>
 646
 647   <varlistentry>
 648     <term><varname>doCheck</varname></term>
 649     <listitem><para>If set to a non-empty string, the check phase is
 650     executed, otherwise it is skipped (default).  Thus you should set
 651
 652     <programlisting>
 653 doCheck = true;</programlisting>
 654
 655     in the derivation to enable checks.</para></listitem>
 656   </varlistentry>
 657
 658   <varlistentry>
 659     <term><varname>makeFlags</varname> /
 660     <varname>makeFlagsArray</varname> /
 661     <varname>makefile</varname></term>
 662     <listitem><para>See the build phase for details.</para></listitem>
 663   </varlistentry>
 664
 665   <varlistentry>
 666     <term><varname>checkTarget</varname></term>
 667     <listitem><para>The make target that runs the tests.  Defaults to
 668     <literal>check</literal>.</para></listitem>
 669   </varlistentry>
 670
 671   <varlistentry>
 672     <term><varname>checkFlags</varname> / <varname>checkFlagsArray</varname></term>
 673     <listitem><para>Additional flags passed to
 674     <command>make</command>.  Like <varname>makeFlags</varname> and
 675     <varname>makeFlagsArray</varname>, but only used by the check
 676     phase.</para></listitem>
 677   </varlistentry>
 678
 679   <varlistentry>
 680     <term><varname>preCheck</varname></term>
 681     <listitem><para>Hook executed at the start of the check
 682     phase.</para></listitem>
 683   </varlistentry>
 684
 685   <varlistentry>
 686     <term><varname>postCheck</varname></term>
 687     <listitem><para>Hook executed at the end of the check
 688     phase.</para></listitem>
 689   </varlistentry>
 690
 691 </variablelist>
 692
 693
 694 </section>
 695
 696
 697 <section><title>The install phase</title>
 698
 699 <para>The install phase is responsible for installing the package in
 700 the Nix store under <envar>out</envar>.  The default
 701 <function>installPhase</function> creates the directory
 702 <literal>$out</literal> and calls <command>make
 703 install</command>.</para>
 704
 705 <variablelist>
 706   <title>Variables controlling the check phase</title>
 707
 708   <varlistentry>
 709     <term><varname>makeFlags</varname> /
 710     <varname>makeFlagsArray</varname> /
 711     <varname>makefile</varname></term>
 712     <listitem><para>See the build phase for details.</para></listitem>
 713   </varlistentry>
 714
 715   <varlistentry>
 716     <term><varname>installTargets</varname></term>
 717     <listitem><para>The make targets that perform the installation.
 718     Defaults to <literal>install</literal>.  Example:
 719
 720 <programlisting>
 721 installTargets = "install-bin install-doc";</programlisting>
 722
 723     </para></listitem>
 724   </varlistentry>
 725
 726   <varlistentry>
 727     <term><varname>installFlags</varname> / <varname>installFlagsArray</varname></term>
 728     <listitem><para>Additional flags passed to
 729     <command>make</command>.  Like <varname>makeFlags</varname> and
 730     <varname>makeFlagsArray</varname>, but only used by the install
 731     phase.</para></listitem>
 732   </varlistentry>
 733
 734   <varlistentry>
 735     <term><varname>preInstall</varname></term>
 736     <listitem><para>Hook executed at the start of the install
 737     phase.</para></listitem>
 738   </varlistentry>
 739
 740   <varlistentry>
 741     <term><varname>postInstall</varname></term>
 742     <listitem><para>Hook executed at the end of the install
 743     phase.</para></listitem>
 744   </varlistentry>
 745
 746 </variablelist>
 747
 748
 749 </section>
 750
 751
 752 <section><title>The fixup phase</title>
 753
 754 <para>The fixup phase performs some (Nix-specific) post-processing
 755 actions on the files installed under <filename>$out</filename> by the
 756 install phase.  The default <function>fixupPhase</function> does the
 757 following:
 758
 759 <itemizedlist>
 760
 761   <listitem><para>It moves the <filename>man/</filename>,
 762   <filename>doc/</filename> and <filename>info/</filename>
 763   subdirectories of <envar>$out</envar> to
 764   <filename>share/</filename>.</para></listitem>
 765
 766   <listitem><para>It strips libraries and executables of debug
 767   information.</para></listitem>
 768
 769   <listitem><para>On Linux, it applies the <command>patchelf</command>
 770   command to ELF executables and libraries to remove unused
 771   directories from the <literal>RPATH</literal> in order to prevent
 772   unnecessary runtime dependencies.</para></listitem>
 773
 774   <listitem><para>It rewrites the interpreter paths of shell scripts
 775   to paths found in <envar>PATH</envar>.  E.g.,
 776   <filename>/usr/bin/perl</filename> will be rewritten to
 777   <filename>/nix/store/<replaceable>some-perl</replaceable>/bin/perl</filename>
 778   found in <envar>PATH</envar>.</para></listitem>
 779
 780 </itemizedlist>
 781
 782 </para>
 783
 784 <variablelist>
 785   <title>Variables controlling the check phase</title>
 786
 787   <varlistentry>
 788     <term><varname>dontStrip</varname></term>
 789     <listitem><para>If set, libraries and executables are not
 790     stripped.  By default, they are.</para></listitem>
 791   </varlistentry>
 792
 793   <varlistentry>
 794     <term><varname>stripAllList</varname></term>
 795     <listitem><para>List of directories to search for libraries and
 796     executables from which <emphasis>all</emphasis> symbols should be
 797     stripped.  By default, it’s empty.  Stripping all symbols is
 798     risky, since it may remove not just debug symbols but also ELF
 799     information necessary for normal execution.</para></listitem>
 800   </varlistentry>
 801
 802   <varlistentry>
 803     <term><varname>stripAllFlags</varname></term>
 804     <listitem><para>Flags passed to the <command>strip</command>
 805     command applied to the files in the directories listed in
 806     <varname>stripAllList</varname>.  Defaults to <option>-s</option>
 807     (i.e. <option>--strip-all</option>).</para></listitem>
 808   </varlistentry>
 809
 810   <varlistentry>
 811     <term><varname>stripDebugList</varname></term>
 812     <listitem><para>List of directories to search for libraries and
 813     executables from which only debugging-related symbols should be
 814     stripped.  It defaults to <literal>lib bin
 815     sbin</literal>.</para></listitem>
 816   </varlistentry>
 817
 818   <varlistentry>
 819     <term><varname>stripDebugFlags</varname></term>
 820     <listitem><para>Flags passed to the <command>strip</command>
 821     command applied to the files in the directories listed in
 822     <varname>stripDebugList</varname>.  Defaults to
 823     <option>-S</option>
 824     (i.e. <option>--strip-debug</option>).</para></listitem>
 825   </varlistentry>
 826
 827   <varlistentry>
 828     <term><varname>dontPatchELF</varname></term>
 829     <listitem><para>If set, the <command>patchelf</command> command is
 830     not used to remove unnecessary <literal>RPATH</literal> entries.
 831     Only applies to Linux.</para></listitem>
 832   </varlistentry>
 833
 834   <varlistentry>
 835     <term><varname>dontPatchShebangs</varname></term>
 836     <listitem><para>If set, scripts starting with
 837     <literal>#!</literal> do not have their interpreter paths
 838     rewritten to paths in the Nix store.</para></listitem>
 839   </varlistentry>
 840
 841   <varlistentry>
 842     <term><varname>forceShare</varname></term>
 843     <listitem><para>The list of directories that must be moved from
 844     <filename>$out</filename> to <filename>$out/share</filename>.
 845     Defaults to <literal>man doc info</literal>.</para></listitem>
 846   </varlistentry>
 847
 848   <varlistentry>
 849     <term><varname>setupHook</varname></term>
 850     <listitem><para>A package can export a <link
 851     linkend="ssec-setup-hooks">setup hook</link> by setting this
 852     variable.  The setup hook, if defined, is copied to
 853     <filename>$out/nix-support/setup-hook</filename>.  Environment
 854     variables are then substituted in it using <function
 855     linkend="fun-substituteAll">substituteAll</function>.</para></listitem>
 856   </varlistentry>
 857
 858   <varlistentry>
 859     <term><varname>preFixup</varname></term>
 860     <listitem><para>Hook executed at the start of the fixup
 861     phase.</para></listitem>
 862   </varlistentry>
 863
 864   <varlistentry>
 865     <term><varname>postFixup</varname></term>
 866     <listitem><para>Hook executed at the end of the fixup
 867     phase.</para></listitem>
 868   </varlistentry>
 869
 870 </variablelist>
 871
 872 </section>
 873
 874
 875 <section><title>The distribution phase</title>
 876
 877 <para>The distribution phase is intended to produce a source
 878 distribution of the package.  The default
 879 <function>distPhase</function> first calls <command>make
 880 dist</command>, then it copies the resulting source tarballs to
 881 <filename>$out/tarballs/</filename>.  This phase is only executed if
 882 the attribute <varname>doDist</varname> is not set.</para>
 883
 884 <variablelist>
 885   <title>Variables controlling the distribution phase</title>
 886
 887   <varlistentry>
 888     <term><varname>distTarget</varname></term>
 889     <listitem><para>The make target that produces the distribution.
 890     Defaults to <literal>dist</literal>.</para></listitem>
 891   </varlistentry>
 892
 893   <varlistentry>
 894     <term><varname>distFlags</varname> / <varname>distFlagsArray</varname></term>
 895     <listitem><para>Additional flags passed to
 896     <command>make</command>.</para></listitem>
 897   </varlistentry>
 898
 899   <varlistentry>
 900     <term><varname>tarballs</varname></term>
 901     <listitem><para>The names of the source distribution files to be
 902     copied to <filename>$out/tarballs/</filename>.  It can contain
 903     shell wildcards.  The default is
 904     <filename>*.tar.gz</filename>.</para></listitem>
 905   </varlistentry>
 906
 907   <varlistentry>
 908     <term><varname>dontCopyDist</varname></term>
 909     <listitem><para>If set, no files are copied to
 910     <filename>$out/tarballs/</filename>.</para></listitem>
 911   </varlistentry>
 912
 913   <varlistentry>
 914     <term><varname>preDist</varname></term>
 915     <listitem><para>Hook executed at the start of the distribution
 916     phase.</para></listitem>
 917   </varlistentry>
 918
 919   <varlistentry>
 920     <term><varname>postDist</varname></term>
 921     <listitem><para>Hook executed at the end of the distribution
 922     phase.</para></listitem>
 923   </varlistentry>
 924
 925 </variablelist>
 926
 927
 928 </section>
 929
 930
 931 </section>
 932
 933
 934 <section xml:id="ssec-stdenv-functions"><title>Shell functions</title>
 935
 936 <para>The standard environment provides a number of useful
 937 functions.</para>
 938
 939 <variablelist>
 940
 941
 942   <varlistentry xml:id='fun-ensureDir'>
 943     <term><function>ensureDir</function> <replaceable>args</replaceable></term>
 944     <listitem><para>Creates the specified directories, including all
 945     necessary parent directories, if they do not already
 946     exist.</para></listitem>
 947   </varlistentry>
 948
 949
 950   <varlistentry xml:id='fun-substitute'>
 951     <term><function>substitute</function>
 952     <replaceable>infile</replaceable>
 953     <replaceable>outfile</replaceable>
 954     <replaceable>subs</replaceable></term>
 955
 956     <listitem>
 957       <para>Performs string substitution on the contents of
 958       <replaceable>infile</replaceable>, writing the result to
 959       <replaceable>outfile</replaceable>.  The substitutions in
 960       <replaceable>subs</replaceable> are of the following form:
 961
 962         <variablelist>
 963           <varlistentry>
 964             <term><option>--replace</option>
 965             <replaceable>s1</replaceable>
 966             <replaceable>s2</replaceable></term>
 967             <listitem><para>Replace every occurence of the string
 968             <replaceable>s1</replaceable> by
 969             <replaceable>s2</replaceable>.</para></listitem>
 970           </varlistentry>
 971
 972           <varlistentry>
 973             <term><option>--subst-var</option>
 974             <replaceable>varName</replaceable></term>
 975             <listitem><para>Replace every occurence of
 976             <literal>@<replaceable>varName</replaceable>@</literal> by
 977             the contents of the environment variable
 978             <replaceable>varName</replaceable>.  This is useful for
 979             generating files from templates, using
 980             <literal>@<replaceable>...</replaceable>@</literal> in the
 981             template as placeholders.</para></listitem>
 982           </varlistentry>
 983
 984           <varlistentry>
 985             <term><option>--subst-var-by</option>
 986             <replaceable>varName</replaceable>
 987             <replaceable>s</replaceable></term>
 988             <listitem><para>Replace every occurence of
 989             <literal>@<replaceable>varName</replaceable>@</literal> by
 990             the string <replaceable>s</replaceable>.</para></listitem>
 991           </varlistentry>
 992
 993         </variablelist>
 994
 995       </para>
 996
 997       <para>Example:
 998
 999 <programlisting>
1000 substitute ./foo.in ./foo.out \
1001     --replace /usr/bin/bar $bar/bin/bar \
1002     --replace "a string containing spaces" "some other text" \
1003     --subst-var someVar
1004 </programlisting>
1005
1006       </para>
1007
1008       <para><function>substitute</function> is implemented using the
1009       <command
1010       xlink:href="http://replace.richardlloyd.org.uk/">replace</command>
1011       command.  Unlike with the <command>sed</command> command, you
1012       don’t have to worry about escaping special characters.  It
1013       supports performing substitutions on binary files (such as
1014       executables), though there you’ll probably want to make sure
1015       that the replacement string is as long as the replaced
1016       string.</para>
1017
1018     </listitem>
1019   </varlistentry>
1020
1021
1022   <varlistentry xml:id='fun-substituteInPlace'>
1023     <term><function>substituteInPlace</function>
1024     <replaceable>file</replaceable>
1025     <replaceable>subs</replaceable></term>
1026     <listitem><para>Like <function>substitute</function>, but performs
1027     the substitutions in place on the file
1028     <replaceable>file</replaceable>.</para></listitem>
1029   </varlistentry>
1030
1031
1032   <varlistentry xml:id='fun-substituteAll'>
1033     <term><function>substituteAll</function>
1034     <replaceable>infile</replaceable>
1035     <replaceable>outfile</replaceable></term>
1036     <listitem><para>Replaces every occurence of
1037     <literal>@<replaceable>varName</replaceable>@</literal>, where
1038     <replaceable>varName</replaceable> is any environment variable, in
1039     <replaceable>infile</replaceable>, writing the result to
1040     <replaceable>outfile</replaceable>.  For instance, if
1041     <replaceable>infile</replaceable> has the contents
1042
1043 <programlisting>
1044 #! @bash@/bin/sh
1045 PATH=@coreutils@/bin
1046 echo @foo@
1047 </programlisting>
1048
1049     and the environment contains
1050     <literal>bash=/nix/store/bmwp0q28cf21...-bash-3.2-p39</literal>
1051     and
1052     <literal>coreutils=/nix/store/68afga4khv0w...-coreutils-6.12</literal>,
1053     but does not contain the variable <varname>foo</varname>, then the
1054     output will be
1055
1056 <programlisting>
1057 #! /nix/store/bmwp0q28cf21...-bash-3.2-p39/bin/sh
1058 PATH=/nix/store/68afga4khv0w...-coreutils-6.12/bin
1059 echo @foo@
1060 </programlisting>
1061
1062     That is, no substitution is performed for undefined variables.</para></listitem>
1063   </varlistentry>
1064
1065
1066   <varlistentry xml:id='fun-stripHash'>
1067     <term><function>stripHash</function>
1068     <replaceable>path</replaceable></term>
1069     <listitem><para>Strips the directory and hash part of a store
1070     path, and prints (on standard output) only the name part.  For
1071     instance, <literal>stripHash
1072     /nix/store/68afga4khv0w...-coreutils-6.12</literal> print
1073     <literal>coreutils-6.12</literal>.</para></listitem>
1074   </varlistentry>
1075
1076
1077 </variablelist>
1078
1079 </section>
1080
1081
1082 <section xml:id="ssec-setup-hooks"><title>Package setup hooks</title>
1083
1084 <para>The following packages provide a setup hook:
1085
1086 <variablelist>
1087
1088   <varlistentry>
1089     <term>GCC wrapper</term>
1090     <listitem><para>Adds the <filename>include</filename> subdirectory
1091     of each build input to the <envar>NIX_CFLAGS_COMPILE</envar>
1092     environment variable, and the <filename>lib</filename> and
1093     <filename>lib64</filename> subdirectories to
1094     <envar>NIX_LDFLAGS</envar>.</para></listitem>
1095   </varlistentry>
1096
1097   <varlistentry>
1098     <term>Perl</term>
1099     <listitem><para>Adds the <filename>lib/site_perl</filename> subdirectory
1100     of each build input to the <envar>PERL5LIB</envar>
1101     environment variable.</para></listitem>
1102   </varlistentry>
1103
1104   <varlistentry>
1105     <term>Python</term>
1106     <listitem><para>Adds the
1107     <filename>lib/python2.5/site-packages</filename> subdirectory of
1108     each build input to the <envar>PYTHONPATH</envar> environment
1109     variable.</para>
1110
1111     <note><para>This should be generalised: the Python version
1112     shouldn’t be hard-coded.</para></note></listitem>
1113   </varlistentry>
1114
1115   <varlistentry>
1116     <term>pkg-config</term>
1117     <listitem><para>Adds the <filename>lib/pkgconfig</filename> and
1118     <filename>share/pkgconfig</filename> subdirectories of each
1119     build input to the <envar>PKG_CONFIG_PATH</envar> environment
1120     variable.</para></listitem>
1121   </varlistentry>
1122
1123   <varlistentry>
1124     <term>Automake</term>
1125     <listitem><para>Adds the <filename>share/aclocal</filename>
1126     subdirectory of each build input to the <envar>ACLOCAL_PATH</envar>
1127     environment variable.</para></listitem>
1128   </varlistentry>
1129
1130   <varlistentry>
1131     <term>libxml2</term>
1132     <listitem><para>Adds every file named
1133     <filename>catalog.xml</filename> found under the
1134     <filename>xml/dtd</filename> and <filename>xml/xsl</filename>
1135     subdirectories of each build input to the
1136     <envar>XML_CATALOG_FILES</envar> environment
1137     variable.</para></listitem>
1138   </varlistentry>
1139
1140   <varlistentry>
1141     <term>teTeX / TeX Live</term>
1142     <listitem><para>Adds the <filename>share/texmf-nix</filename>
1143     subdirectory of each build input to the <envar>TEXINPUTS</envar>
1144     environment variable.</para></listitem>
1145   </varlistentry>
1146
1147   <varlistentry>
1148     <term>Qt</term>
1149     <listitem><para>Sets the <envar>QTDIR</envar> environment variable
1150     to Qt’s path.</para></listitem>
1151   </varlistentry>
1152
1153   <varlistentry>
1154     <term>GHC</term>
1155     <listitem><para>Creates a temporary package database and registers
1156     every Haskell build input in it (TODO: how?).</para></listitem>
1157   </varlistentry>
1158
1159 </variablelist>
1160
1161 </para>
1162
1163 </section>
1164
1165
1166 <section><title>Purity in Nixpkgs</title>
1167
1168 <para>[measures taken to prevent dependencies on packages outside the
1169 store, and what you can do to prevent them]</para>
1170
1171 <para>GCC doesn't search in locations such as
1172 <filename>/usr/include</filename>.  In fact, attempts to add such
1173 directories through the <option>-I</option> flag are filtered out.
1174 Likewise, the linker (from GNU binutils) doesn't search in standard
1175 locations such as <filename>/usr/lib</filename>.  Programs built on
1176 Linux are linked against a GNU C Library that likewise doesn't search
1177 in the default system locations.</para>
1178
1179 </section>
1180
1181
1182 </chapter>
1183