diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 546c0efb3d..d1ded020eb 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 /* The standard environment -TODO +The standard build environment in the Nix Packages collection +provides a basic environment for building Unix packages. It consists +of the following components: + + + + The GNU C Compiler, configured with C and C++ + support. On Linux, the compiler has been patched to provide greater + purity assurance. For instance, the compiler 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. + + 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 + 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. + + Patch. + + + + + +The standard environment is used by passing it as an input +called stdenv to the derivation, and then doing + + +. $stdenv/setup + +at the top of the builder. + +Apart from adding the aforementioned commands to the +PATH, setup also does the +following: + + + + All input components specified in the + buildInputs environment variable have their + /bin subdirectory added to PATH, + their /include subdirectory added to the C/C++ + header file search path, and their /lib + subdirectory added to the linker search path. This can be extended. + For instance, when the pkgconfig component is + used, the subdirectory /lib/pkgconfig of each + input is added to the PKG_CONFIG_PATH environment + variable. + + The environment variable + NIX_CFLAGS_STRIP is set so that the compiler strips + debug information from object files. This can be disabled by + setting NIX_STRIP_DEBUG to + 0. + + + + + +The setup script also exports a function +called genericBuilder 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 +genericBuild since it provides facilities that +are almost always useful such as unpacking of sources, patching of +sources, nested logging, etc. + +The operation of the generic builder can be modified in many +places by setting certain variables. These hook +variables are typically set to the name of some shell +function defined by you. For instance, to perform some additional +steps after make install you would set the +postInstall variable: + + +postInstall=myPostInstall + +myPostInstall() { + mkdir $out/share/extra + cp extrafiles/* $out/share/extra +} + + + +The generic builder has a number of phases, +each of which can be override in its entirety by setting the indicated +variable. 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 an + the variable unpackCmd to contain the command + to be executed to unpack the file. + + After unpacking all source files, + unpackPhase 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 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 flag 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. It also strips any + static libraries in the output path of debug information unless + dontStrip is set to + 1. + + Before and after running make install, + the hooks preInstall and + postInstall are called, respectively. + + + + + + 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. + +At the beginning of each phase, the set of all shell variables +is written to the file env-vars 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 + flag, you can go to the output directory and +switch to the environment of the builder: + + +$ nix-build -K ./foo.nix +... fails, keeping build directory `/tmp/nix-1234-0' + +$ cd /tmp/nix-1234-0 + +$ source env-vars + +(edit some files...) + +$ make + +(execution continues with the same GCC, make, etc.) + + + +The definitive, up-to-date documentation of the generic builder +is the source itself, which resides in +pkgs/stdenv/generic/setup.sh.