nixpkgs/doc/stdenv.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="chap-stdenv">

<title>The Standard Environment</title>


<para>The standard build environment in the Nix Packages collection
provides a environment for building Unix packages that does a lot of
common build tasks automatically.  In fact, for Unix packages that use
the standard <literal>./configure; make; make install</literal> build
interface, you don’t need to write a build script at all; the standard
environment does everything automatically.  If
<literal>stdenv</literal> doesn’t do what you need automatically, you
can easily customise or override the various build phases.</para>


<section><title>Using <literal>stdenv</literal></title>

<para>To build a package with the standard environment, you use the
function <varname>stdenv.mkDerivation</varname>, instead of the
primitive built-in function <varname>derivation</varname>, e.g.

<programlisting>
stdenv.mkDerivation {
  name = "libfoo-1.2.3";
  src = fetchurl {
    url = http://example.org/libfoo-1.2.3.tar.bz2;
    md5 = "e1ec107956b6ddcb0b8b0679367e9ac9";
  };
}</programlisting>

(<varname>stdenv</varname> needs to be in scope, so if you write this
in a separate Nix expression from
<filename>pkgs/all-packages.nix</filename>, you need to pass it as a
function argument.)  Specifying a <varname>name</varname> and a
<varname>src</varname> is the absolute minimum you need to do.  Many
packages have dependencies that are not provided in the standard
environment.  It’s usually sufficient to specify those dependencies in
the <varname>buildInputs</varname> attribute:

<programlisting>
stdenv.mkDerivation {
  name = "libfoo-1.2.3";
  ...
  buildInputs = [libbar perl ncurses];
}</programlisting>

This attribute ensures that the <filename>bin</filename>
subdirectories of these packages appear in the <envar>PATH</envar>
environment variable during the build, that their
<filename>include</filename> subdirectories are searched by the C
compiler, and so on.  (See <xref linkend="ssec-setup-hooks"/> for
details.)</para>

<para>Often it is necessary to override or modify some aspect of the
build.  To make this easier, the standard environment breaks the
package build into a number of <emphasis>phases</emphasis>, all of
which can be overriden or modified individually: unpacking the
sources, applying patches, configuring, building, and installing.
(There are some others; see <xref linkend="ssec-stdenv-phases"/>.)
For instance, a package that doesn’t supply a makefile but instead has
to be compiled “manually” could be handled like this:

<programlisting>
stdenv.mkDerivation {
  name = "fnord-4.5";
  ...
  buildPhase = ''
    gcc foo.c -o foo
  '';
  installPhase = ''
    ensureDir $out/bin
    cp foo $out/bin
  '';
}</programlisting>

(Note the use of <literal>''</literal>-style string literals, which
are very convenient for large multi-line script fragments because they
don’t need escaping of <literal>"</literal> and <literal>\</literal>,
and because indentation is intelligently removed.)</para>

<para>There are many other attributes to customise the build.  These
are listed in <xref linkend="ssec-stdenv-attributes"/>.</para>

<para>While the standard environment provides a generic builder, you
can still supply your own build script:

<programlisting>
stdenv.mkDerivation {
  name = "libfoo-1.2.3";
  ...
  builder = ./builder.sh;
}</programlisting>

where the builder can do anything it wants, but typically starts with

<programlisting>
source $stdenv/setup
</programlisting>

to let <literal>stdenv</literal> set up the environment (e.g., process
the <varname>buildInputs</varname>).  If you want, you can still use
<literal>stdenv</literal>’s generic builder:

<programlisting>
source $stdenv/setup

buildPhase() {
  echo "... this is my custom build phase ..."
  gcc foo.c -o foo
}

installPhase() {
  ensureDir $out/bin
  cp foo $out/bin
}

genericBuild
</programlisting>

</para>

</section>


<section><title>Tools provided by <literal>stdenv</literal></title>

<para>The standard environment provides the following packages:

<itemizedlist>

  <listitem><para>The GNU C Compiler, configured with C and C++
  support.</para></listitem>

  <listitem><para>GNU coreutils (contains a few dozen standard Unix
  commands).</para></listitem>

  <listitem><para>GNU findutils (contains
  <command>find</command>).</para></listitem>

  <listitem><para>GNU diffutils (contains <command>diff</command>,
  <command>cmp</command>).</para></listitem>

  <listitem><para>GNU <command>sed</command>.</para></listitem>

  <listitem><para>GNU <command>grep</command>.</para></listitem>

  <listitem><para>GNU <command>awk</command>.</para></listitem>

  <listitem><para>GNU <command>tar</command>.</para></listitem>

  <listitem><para><command>gzip</command> and
  <command>bzip2</command>.</para></listitem>

  <listitem><para>GNU Make.  It has been patched to provide
  <quote>nested</quote> output that can be fed into the
  <command>nix-log2xml</command> command and
  <command>log2html</command> stylesheet to create a structured,
  readable output of the build steps performed by
  Make.</para></listitem>

  <listitem><para>Bash.  This is the shell used for all builders in
  the Nix Packages collection.  Not using <command>/bin/sh</command>
  removes a large source of portability problems.</para></listitem>

  <listitem><para>The <command>patch</command>
  command.</para></listitem>

</itemizedlist>

</para>

<para>On Linux, <literal>stdenv</literal> also includes the
<command>patchelf</command> utility.</para>

</section>


<section xml:id="ssec-stdenv-phases"><title>Phases</title>

<para>The generic builder has a number of <emphasis>phases</emphasis>.
Each phase can be overriden in its entirety either by setting the
environment variable
<varname><replaceable>name</replaceable>Phase</varname> to a string
containing some shell commands to be executed, or by redefining the
shell function
<varname><replaceable>name</replaceable>Phase</varname>.  The former
is convenient to override a phase from the derivation, while the
latter is convenient from a build script.</para>


<section><title>Controlling phases</title>

<para>There are a number of variables that control what phases are
executed and in what order:

<variablelist>
  <title>Variables affecting phase control</title>

  <varlistentry>
    <term><varname>phases</varname></term>
    <listitem>
      <para>Specifies the phases.  You can change the order in which
      phases are executed, or add new phases, by setting this
      variable.  If it’s not set, the default value is used, which is
      <literal>$prePhases unpackPhase patchPhase $preConfigurePhases
      configurePhase $preBuildPhases buildPhase checkPhase
      $preInstallPhases installPhase fixupPhase $preDistPhases
      distPhase $postPhases</literal>.
      </para>
      
      <para>Usually, if you just want to add a few phases, it’s more
      convenient to set one of the variables below (such as
      <varname>preInstallPhases</varname>), as you then don’t specify
      all the normal phases.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>prePhases</varname></term>
    <listitem>
      <para>Additional phases executed before any of the default phases.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>preConfigurePhases</varname></term>
    <listitem>
      <para>Additional phases executed just before the configure phase.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>preBuildPhases</varname></term>
    <listitem>
      <para>Additional phases executed just before the build phase.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>preInstallPhases</varname></term>
    <listitem>
      <para>Additional phases executed just before the install phase.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>preDistPhases</varname></term>
    <listitem>
      <para>Additional phases executed just before the distribution phase.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>postPhases</varname></term>
    <listitem>
      <para>Additional phases executed after any of the default
      phases.</para>
    </listitem>
  </varlistentry>

</variablelist>

</para>

</section>


<section><title>The unpack phase</title>

<para>The unpack phase is responsible for unpacking the source code of
the package.  The default implementation of
<function>unpackPhase</function> unpacks the source files listed in
the <envar>src</envar> environment variable to the current directory.
It supports the following files by default:

<variablelist>

  <varlistentry>
    <term>Tar files</term>
    <listitem><para>These can optionally be compressed using
    <command>gzip</command> (<filename>.tar.gz</filename>,
    <filename>.tgz</filename> or <filename>.tar.Z</filename>) or
    <command>bzip2</command> (<filename>.tar.bz2</filename> or
    <filename>.tbz2</filename>).</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Zip files</term>
    <listitem><para>Zip files are unpacked using
    <command>unzip</command>.  However, <command>unzip</command> is
    not in the standard environment, so you should add it to
    <varname>buildInputs</varname> yourself.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Directories in the Nix store</term>
    <listitem><para>These are simply copied to the current directory.
    The hash part of the file name is stripped,
    e.g. <filename>/nix/store/1wydxgby13cz...-my-sources</filename>
    would be copied to
    <filename>my-sources</filename>.</para></listitem>
  </varlistentry>

</variablelist>

Additional file types can be supported by setting the
<varname>unpackCmd</varname> variable (see below).</para>

<para></para>

<variablelist>
  <title>Variables controlling the unpack phase</title>

  <varlistentry>
    <term><varname>srcs</varname> / <varname>src</varname></term>
    <listitem><para>The list of source files or directories to be
    unpacked or copied.  One of these must be set.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>sourceRoot</varname></term>
    <listitem><para>After running <function>unpackPhase</function>,
    the generic builder changes the current directory to the directory
    created by unpacking the sources.  If there are multiple source
    directories, you should set <varname>sourceRoot</varname> to the
    name of the intended directory.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>setSourceRoot</varname></term>
    <listitem><para>Alternatively to setting
    <varname>sourceRoot</varname>, you can set
    <varname>setSourceRoot</varname> to a shell command to be
    evaluated by the unpack phase after the sources have been
    unpacked.  This command must set
    <varname>sourceRoot</varname>.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>preUnpack</varname></term>
    <listitem><para>Hook executed at the start of the unpack
    phase.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>postUnpack</varname></term>
    <listitem><para>Hook executed at the end of the unpack
    phase.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>dontMakeSourcesWritable</varname></term>
    <listitem><para>If set to <literal>1</literal>, the unpacked
    sources are <emphasis>not</emphasis> made
    writable.  By default, they are made writable to prevent problems
    with read-only sources.  For example, copied store directories
    would be read-only without this.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>unpackCmd</varname></term>
    <listitem><para>The unpack phase evaluates the string
    <literal>$unpackCmd</literal> for any unrecognised file.  The path
    to the current source file is contained in the
    <varname>curSrc</varname> variable.</para></listitem>
  </varlistentry>

</variablelist>

</section>


<section><title>The patch phase</title>

<para>The patch phase applies the list of patches defined in the
<varname>patches</varname> variable.</para>

<variablelist>
  <title>Variables controlling the patch phase</title>

  <varlistentry>
    <term><varname>patches</varname></term>
    <listitem><para>The list of patches.  They must be in the format
    accepted by the <command>patch</command> command, and may
    optionally be compressed using <command>gzip</command>
    (<filename>.gz</filename>) or <command>bzip2</command>
    (<filename>.bz2</filename>).</para></listitem>
  </varlistentry>  

  <varlistentry>
    <term><varname>patchFlags</varname></term>
    <listitem><para>Flags to be passed to <command>patch</command>.
    If not set, the argument <option>-p1</option> is used, which
    causes the leading directory component to be stripped from the
    file names in each patch.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>prePatch</varname></term>
    <listitem><para>Hook executed at the start of the patch
    phase.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>postPatch</varname></term>
    <listitem><para>Hook executed at the end of the patch
    phase.</para></listitem>
  </varlistentry>

</variablelist>

</section>


<section><title>The configure phase</title>

<para>The configure phase prepares the source tree for building.  The
default <function>unpackPhase</function> runs
<filename>./configure</filename> (typically an Autoconf-generated
script) if it exists.</para>

<variablelist>
  <title>Variables controlling the configure phase</title>

  <varlistentry>
    <term><varname>configureScript</varname></term>
    <listitem><para>The name of the configure script.  It defaults to
    <filename>./configure</filename> if it exists; otherwise, the
    configure phase is skipped.  This can actually be a command (like
    <literal>perl ./Configure.pl</literal>).</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>configureFlags</varname></term>
    <listitem><para>Additional arguments passed to the configure
    script.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>configureFlagsArray</varname></term>
    <listitem><para>A shell array containing additional arguments
    passed to the configure script.  You must use this instead of
    <varname>configureFlags</varname> if the arguments contain
    spaces.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>dontAddPrefix</varname></term>
    <listitem><para>By default, the flag
    <literal>--prefix=$prefix</literal> is added to the configure
    flags.  If this is undesirable, set this variable to a non-empty
    value.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>prefix</varname></term>
    <listitem><para>The prefix under which the package must be
    installed, passed via the <option>--prefix</option> option to the
    configure script.  It defaults to
    <option>$out</option>.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>dontAddDisableDepTrack</varname></term>
    <listitem><para>By default, the flag
    <literal>--disable-dependency-tracking</literal> is added to the
    configure flags to speed up Automake-based builds.  If this is
    undesirable, set this variable to a non-empty
    value.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>dontFixLibtool</varname></term>
    <listitem><para>By default, the configure phase applies some
    special hackery to all files called <filename>ltmain.sh</filename>
    before running the configure script in order to improve the purity
    of Libtool-based packages<footnote><para>It clears the
    <varname>sys_lib_<replaceable>*</replaceable>search_path</varname>
    variables in the Libtool script to prevent Libtool from using
    libraries in <filename>/usr/lib</filename> and
    such.</para></footnote>.  If this is undesirable, set this
    variable to a non-empty value.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>preConfigure</varname></term>
    <listitem><para>Hook executed at the start of the configure
    phase.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>postConfigure</varname></term>
    <listitem><para>Hook executed at the end of the configure
    phase.</para></listitem>
  </varlistentry>

</variablelist>


</section>


<section><title>The build phase</title>

<para><function>buildPhase</function> calls <command>make</command>.
You can set flags for <command>make</command> through the
<varname>makeFlags</varname> variable.</para>

<para>Before and after running <command>make</command>, the hooks
<varname>preBuild</varname> and <varname>postBuild</varname> are
called, respectively.</para>

</section>


<section><title>The check phase</title>

<para><function>checkPhase</function> calls <command>make
check</command>, but only if the <varname>doCheck</varname> variable
is set to <literal>1</literal>.  Additional flags can be set through
the <varname>checkFlags</varname> variable.</para>
  
</section>


<section><title>The install phase</title>

<para><function>installPhase</function> calls <command>make
install</command>.  Additional flags can be set through the
<varname>installFlags</varname> variable.</para>

<para>Before and after running <command>make install</command>, the
hooks <varname>preInstall</varname> and <varname>postInstall</varname>
are called, respectively.</para>

</section>


<section><title>The fixup phase</title>

<para><function>fixupPhase</function> cleans up the installed files in
various ways:
    
<itemizedlist>
      
  <listitem><para>It moves the <filename>man/</filename>,
  <filename>doc/</filename> and <filename>info/</filename>
  subdirectories of <envar>$out</envar> to
  <filename>share/</filename>.</para></listitem>
      
  <listitem><para>It strips libraries and executables of debug
  information.</para></listitem>

  <listitem><para>On Linux, it applies the <command>patchelf</command>
  command to ELF executables and libraries to remove unused
  directories from the <literal>RPATH</literal> in order to prevent
  unnecessary dependencies.</para></listitem>

  <listitem><para>It rewrites the interpreter paths of shell scripts
  to paths found in <envar>PATH</envar>.  E.g.,
  <filename>/usr/bin/perl</filename> will be rewritten to
  <filename>/nix/store/<replaceable>some-perl</replaceable>/bin/perl</filename>
  found in <envar>PATH</envar>.</para></listitem>

</itemizedlist>

</para>

</section>


<section><title>The distribution phase</title>

<para><function>distPhase</function> calls <command>make
dist</command>, but only if the <varname>doDist</varname> variable is
set to <literal>1</literal>.  Additional flags can be set through the
<varname>distFlags</varname> variable.  The resulting tarball is
copied to the <filename>/tarballs</filename> subdirectory of the
output path.</para>

<para>Before and after running <command>make dist</command>, the hooks
<varname>preDist</varname> and <varname>postDist</varname> are called,
respectively.</para>

</section>


</section>


<section xml:id="ssec-stdenv-attributes"><title>Attributes</title>

<para></para>

</section>


<section xml:id="ssec-setup-hooks"><title>Package setup hooks</title>

<para></para>

</section>


<section><title>Purity in Nixpkgs</title>

<para>[measures taken to prevent dependencies on packages outside the
store, and what you can do to prevent them]</para>

<para>GCC doesn't search in locations such as
<filename>/usr/include</filename>.  In fact, attempts to add such
directories through the <option>-I</option> flag are filtered out.
Likewise, the linker (from GNU binutils) doesn't search in standard
locations such as <filename>/usr/lib</filename>.  Programs built on
Linux are linked against a GNU C Library that likewise doesn't search
in the default system locations.</para>

</section>


</chapter>