* Documented the standard environment, including the generic builder.

1 files changed, 250 insertions, 1 deletions

diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 546c0efb3d3d..d1ded020eb71 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -1285,7 +1285,256 @@ character, or inline/multi-line, enclosed within <literal>/*
 
 <sect1 id='sec-standard-environment'><title>The standard environment</title>
 
-<para>TODO</para>
+<para>The standard build environment in the Nix Packages collection
+provides a basic environment for building Unix packages.  It consists
+of the following components:
+
+<itemizedlist>
+
+  <listitem><para>The GNU C Compiler, configured with C and C++
+  support.  On Linux, the compiler has been patched to provide greater
+  <quote>purity</quote> assurance.  For instance, the compiler 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></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>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>Patch.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>The standard environment is used by passing it as an input
+called <envar>stdenv</envar> to the derivation, and then doing
+
+<programlisting>
+. $stdenv/setup</programlisting>
+
+at the top of the builder.</para>
+
+<para>Apart from adding the aforementioned commands to the
+<envar>PATH</envar>, <filename>setup</filename> also does the
+following:
+
+<itemizedlist>
+
+  <listitem><para>All input components specified in the
+  <envar>buildInputs</envar> environment variable have their
+  <filename>/bin</filename> subdirectory added to <envar>PATH</envar>,
+  their <filename>/include</filename> subdirectory added to the C/C++
+  header file search path, and their <filename>/lib</filename>
+  subdirectory added to the linker search path.  This can be extended.
+  For instance, when the <command>pkgconfig</command> component is
+  used, the subdirectory <filename>/lib/pkgconfig</filename> of each
+  input is added to the <envar>PKG_CONFIG_PATH</envar> environment
+  variable.</para></listitem>
+
+  <listitem><para>The environment variable
+  <envar>NIX_CFLAGS_STRIP</envar> is set so that the compiler strips
+  debug information from object files.  This can be disabled by
+  setting <envar>NIX_STRIP_DEBUG</envar> to
+  <literal>0</literal>.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>The <filename>setup</filename> script also exports a function
+called <function>genericBuilder</function> that knows how to build
+typical Autoconf-style components.  It can be customised to perform
+builds for any type of component.  It is advisable to use
+<function>genericBuild</function> since it provides facilities that
+are almost always useful such as unpacking of sources, patching of
+sources, nested logging, etc.</para>
+
+<para>The operation of the generic builder can be modified in many
+places by setting certain variables.  These <emphasis>hook
+variables</emphasis> are typically set to the name of some shell
+function defined by you.  For instance, to perform some additional
+steps after <command>make install</command> you would set the
+<varname>postInstall</varname> variable:
+
+<programlisting>
+postInstall=myPostInstall
+
+myPostInstall() {
+    mkdir $out/share/extra
+    cp extrafiles/* $out/share/extra
+}</programlisting>
+
+</para>
+
+<para>The generic builder has a number of <emphasis>phases</emphasis>,
+each of which can be override in its entirety by setting the indicated
+variable.  The phases are:
+
+<itemizedlist>
+
+  <listitem>
+
+    <para><function>unpackPhase</function>: unpacks the source files
+    listed in the <envar>src</envar> environment variable to the
+    current directory.  It supports <filename>tar</filename> files,
+    optionally compressed with <command>gzip</command> or
+    <command>bzip2</command>; Zip files (but note that the
+    <command>unzip</command> command is not a part of the standard
+    environment; you should add it as a build input yourself); and
+    unpacked source trees (i.e., directories; they are copied
+    verbatim).  You can add support for other file types by setting
+    the <varname>findUnpacker</varname> hook.  This hook should set an
+    the variable <varname>unpackCmd</varname> to contain the command
+    to be executed to unpack the file.</para>
+
+    <para>After unpacking all source files,
+    <function>unpackPhase</function> 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>
+
+    <para>It also calls the hook <varname>postUnpack</varname> after
+    unpacking.</para>
+
+  </listitem>
+
+  <listitem><para><function>patchPhase</function> calls the
+  <command>patch</command> command with the <option>-p1</option>
+  option for each patch file listed in the <envar>patches</envar>
+  variable.</para></listitem>
+
+  <listitem>
+
+    <para><function>configurePhase</function> runs the script called
+    <filename>configure</filename> in the current directory with a
+    <option>--prefix</option> set to the output path.  You can add
+    additional flag through the <varname>configureFlags</varname>
+    variable.  If <filename>configure</filename> does not exist,
+    nothing happens.</para>
+
+    <para>Before and after running <filename>configure</filename>, the
+    hooks <varname>preConfigure</varname> and
+    <varname>postConfigure</varname> are called, respectively.</para>
+
+  </listitem>
+
+  <listitem>
+
+    <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>
+    
+  </listitem>
+
+  <listitem><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></listitem>
+
+  <listitem>
+
+    <para><function>installPhase</function> calls <command>make
+    install</command>.  Additional flags can be set through the
+    <varname>installFlags</varname> variable.  It also strips any
+    static libraries in the output path of debug information unless
+    <varname>dontStrip</varname> is set to
+    <literal>1</literal>.</para>
+
+    <para>Before and after running <command>make install</command>,
+    the hooks <varname>preInstall</varname> and
+    <varname>postInstall</varname> are called, respectively.</para>
+
+  </listitem>
+
+  <listitem>
+
+    <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>
+    
+  </listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>You can change the order in which phases are executed, or add
+new phases, by setting the <varname>phases</varname> variable.  The
+default is <literal>patchPhase configurePhase buildPhase checkPhase
+installPhase distPhase</literal>.</para>
+
+<para>At the beginning of each phase, the set of all shell variables
+is written to the file <filename>env-vars</filename> at the top-level
+build directory.  This is useful for debugging: it allows you to
+recreate the environment in which a build was performed.  For
+instance, if a build fails, then assuming you used the
+<option>-K</option> flag, you can go to the output directory and
+<quote>switch</quote> to the environment of the builder:
+
+<screen>
+$ nix-build -K ./foo.nix
+... fails, keeping build directory `/tmp/nix-1234-0'
+
+$ cd /tmp/nix-1234-0
+
+$ source env-vars
+
+<lineannotation>(edit some files...)</lineannotation>
+
+$ make
+
+<lineannotation>(execution continues with the same GCC, make, etc.)</lineannotation></screen>
+
+</para>
+
+<para>The definitive, up-to-date documentation of the generic builder
+is the source itself, which resides in
+<filename>pkgs/stdenv/generic/setup.sh</filename>.</para>
 
 </sect1>