From 418d5e30810240e95eecaddaac549a9e10757a4e Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 19 Jun 2008 16:00:37 +0000 Subject: * More stdenv documentation. Some of it has been moved from the Nix manual. svn path=/nixpkgs/trunk/; revision=12164 --- doc/manual.xml | 2 +- doc/outline.txt | 2 + doc/stdenv.xml | 352 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 355 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/manual.xml b/doc/manual.xml index 2ef9516afc12e..c4f1128ea77e2 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 78ba0411501b0..a7dfc3bdc86c0 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 d99cdb4dd699a..105026f530f5a 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 <literal>stdenv</literal> + +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 <literal>stdenv</literal> + +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. + +
+ + -- cgit 1.4.1