diff --git a/doc/manual.xml b/doc/manual.xml
index 2ef9516afc1..c4f1128ea77 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -32,4 +32,4 @@
-
\ No newline at end of file
+
diff --git a/doc/outline.txt b/doc/outline.txt
index 78ba0411501..a7dfc3bdc86 100644
--- a/doc/outline.txt
+++ b/doc/outline.txt
@@ -43,6 +43,8 @@
- Stdenv bootstrap; how to update the Linux bootstrap binaries
+ - Specific platform notes (Linux, Native, Cygwin, Mingw)
+
- Support for specific languages
diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index d99cdb4dd69..105026f530f 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -4,7 +4,359 @@
The Standard Environment
+
+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 ./configure; make; make install build
+interface, you don’t need to write a build script at all; the standard
+environment does everything automatically. If
+stdenv doesn’t do what you need automatically, you
+can easily customise or override the various build phases.
+
+
+Using stdenv
+
+To build a package with the standard environment, you use the
+function stdenv.mkDerivation, instead of the
+primitive built-in function derivation, e.g.
+
+
+stdenv.mkDerivation {
+ name = "libfoo-1.2.3";
+ src = fetchurl {
+ url = http://example.org/libfoo-1.2.3.tar.bz2;
+ md5 = "e1ec107956b6ddcb0b8b0679367e9ac9";
+ };
+}
+
+(stdenv needs to be in scope, so if you write this
+in a separate Nix expression from
+pkgs/all-packages.nix, you need to pass it as a
+function argument.) Specifying a name and a
+src 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 buildInputs attribute:
+
+
+stdenv.mkDerivation {
+ name = "libfoo-1.2.3";
+ ...
+ buildInputs = [libbar perl ncurses];
+}
+
+This attribute ensures that the bin
+subdirectories of these packages appear in the PATH
+environment variable during the build, that their
+include subdirectories are searched by the C
+compiler, and so on. (See for
+details.)
+
+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 phases, all of
+which can be overriden or modified individually: unpacking the
+sources, applying patches, configuring, building, and installing.
+(There are some others; see .)
+For instance, a package that doesn’t supply a makefile but instead has
+to be compiled “manually” could be handled like this:
+
+
+stdenv.mkDerivation {
+ name = "fnord-4.5";
+ ...
+ buildPhase = ''
+ gcc foo.c -o foo
+ '';
+ installPhase = ''
+ ensureDir $out/bin
+ cp foo $out/bin
+ '';
+}
+
+(Note the use of ''-style string literals, which
+are very convenient for large multi-line script fragments because they
+don’t need escaping of " and \,
+and because indentation is intelligently removed.)
+
+There are many other attributes to customise the build. These
+are listed in .
+
+While the standard environment provides a generic builder, you
+can still supply your own build script:
+
+
+stdenv.mkDerivation {
+ name = "libfoo-1.2.3";
+ ...
+ builder = ./builder.sh;
+}
+
+where the builder can do anything it wants, but typically starts with
+
+
+source $stdenv/setup
+
+
+to let stdenv set up the environment (e.g., process
+the buildInputs). If you want, you can still use
+stdenv’s generic builder:
+
+
+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
+
+
+
+
+
+
+
+Tools provided by stdenv
+
+The standard environment provides the following packages:
+
+
+
+ The GNU C Compiler, configured with C and C++
+ support.
+
+ GNU coreutils (contains a few dozen standard Unix
+ commands).
+
+ GNU findutils (contains
+ find).
+
+ GNU diffutils (contains diff,
+ cmp).
+
+ GNU sed.
+
+ GNU grep.
+
+ GNU awk.
+
+ GNU tar.
+
+ gzip and
+ bzip2.
+
+ GNU Make. It has been patched to provide
+ nested output that can be fed into the
+ nix-log2xml command and
+ log2html stylesheet to create a structured,
+ readable output of the build steps performed by
+ Make.
+
+ Bash. This is the shell used for all builders in
+ the Nix Packages collection. Not using /bin/sh
+ removes a large source of portability problems.
+
+ The patch
+ command.
+
+
+
+
+
+On Linux, stdenv also includes the
+patchelf utility.
+
+
+
+
+Build phases
+
+The generic builder has a number of phases.
+Each phase can be overriden in its entirety either by setting the
+environment variable
+namePhase to a string
+containing some shell commands to be executed, or by redefining the
+shell function
+namePhase. The former
+is convenient to override a phase from the derivation, while the
+latter is convenient from a build script.
+
+The phases are:
+
+
+
+
+
+ unpackPhase unpacks the source files
+ listed in the src environment variable to the
+ current directory. It supports tar files,
+ optionally compressed with gzip or
+ bzip2; Zip files (but note that the
+ unzip 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 findUnpacker hook. This hook should set
+ the variable unpackCmd to contain the command
+ to be executed to unpack the file.
+
+ After running unpackPhase, the generic
+ builder changes the current directory to the directory created by
+ unpacking the sources. If there are multiple source directories,
+ you should set sourceRoot to the name of the
+ intended directory.
+
+ It also calls the hook postUnpack after
+ unpacking.
+
+
+
+ patchPhase calls the
+ patch command with the
+ option (overridable via patchFlags) for each patch
+ file listed in the patches
+ variable.
+
+
+
+ configurePhase runs the script called
+ configure in the current directory with a
+ set to the output path. You can add
+ additional flags through the configureFlags
+ variable. If configure does not exist,
+ nothing happens.
+
+ Before and after running configure, the
+ hooks preConfigure and
+ postConfigure are called, respectively.
+
+
+
+
+
+ buildPhase calls
+ make. You can set flags for
+ make through the makeFlags
+ variable.
+
+ Before and after running make, the hooks
+ preBuild and postBuild are
+ called, respectively.
+
+
+
+ checkPhase calls make
+ check, but only if the doCheck variable
+ is set to 1. Additional flags can be set through
+ the checkFlags variable.
+
+
+
+ installPhase calls make
+ install. Additional flags can be set through the
+ installFlags variable.
+
+ Before and after running make install,
+ the hooks preInstall and
+ postInstall are called, respectively.
+
+
+
+
+ fixupPhase cleans up the
+ installed files in various ways:
+
+
+
+ It moves the man/,
+ doc/ and info/
+ subdirectories of $out to
+ share/.
+
+ It strips libraries and executables of debug
+ information.
+
+ On Linux, it applies the
+ patchelf command to ELF executables and
+ libraries to remove unused directories from the
+ RPATH in order to prevent unnecessary
+ dependencies.
+
+ It rewrites the interpreter paths of shell
+ scripts to paths found in PATH. E.g.,
+ /usr/bin/perl will be rewritten to
+ /nix/store/some-perl/bin/perl
+ found in PATH.
+
+
+
+
+
+
+
+
+ distPhase calls make
+ dist, but only if the doDist variable
+ is set to 1. Additional flags can be set
+ through the distFlags variable. The resulting
+ tarball is copied to the /tarballs
+ subdirectory of the output path.
+
+ Before and after running make dist, the
+ hooks preDist and postDist
+ are called, respectively.
+
+
+
+
+
+
+
+You can change the order in which phases are executed, or add
+new phases, by setting the phases variable. The
+default is patchPhase configurePhase buildPhase checkPhase
+installPhase distPhase.
+
+
+
+
+Attributes
+
+
+
+
+Package setup hooks
+
+
+
+
+
+
+Purity in Nixpkgs
+
+[measures taken to prevent dependencies on packages outside the
+store, and what you can do to prevent them]
+
+GCC doesn't search in locations such as
+/usr/include. In fact, attempts to add such
+directories through the flag are filtered out.
+Likewise, the linker (from GNU binutils) doesn't search in standard
+locations such as /usr/lib. Programs built on
+Linux are linked against a GNU C Library that likewise doesn't search
+in the default system locations.
+
+
+
+