From c967e66ec74570e620495863f211486f26ac492f Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 27 Aug 2008 17:34:11 +0000 Subject: [PATCH] * Documented some phases in more detail. svn path=/nixpkgs/trunk/; revision=12752 --- doc/stdenv.xml | 512 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 387 insertions(+), 125 deletions(-) diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 105026f530f5..39c5c3d34fe5 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -177,7 +177,7 @@ genericBuild -
Build phases +
Phases The generic builder has a number of phases. Each phase can be overriden in its entirety either by setting the @@ -189,141 +189,403 @@ shell function is convenient to override a phase from the derivation, while the latter is convenient from a build script. -The phases are: +
Controlling phases + +There are a number of variables that control what phases are +executed and in what order: + + + Variables affecting phase control + + + phases + + 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 + $prePhases unpackPhase patchPhase $preConfigurePhases + configurePhase $preBuildPhases buildPhase checkPhase + $preInstallPhases installPhase fixupPhase $preDistPhases + distPhase $postPhases. + + + Usually, if you just want to add a few phases, it’s more + convenient to set one of the variables below (such as + preInstallPhases), as you then don’t specify + all the normal phases. + + + + + prePhases + + Additional phases executed before any of the default phases. + + + + + preConfigurePhases + + Additional phases executed just before the configure phase. + + + + + preBuildPhases + + Additional phases executed just before the build phase. + + + + + preInstallPhases + + Additional phases executed just before the install phase. + + + + + preDistPhases + + Additional phases executed just before the distribution phase. + + + + + postPhases + + Additional phases executed after any of the default + phases. + + + + + + + +
+ + +
The unpack phase + +The unpack phase is responsible for unpacking the source code of +the package. The default implementation of +unpackPhase unpacks the source files listed in +the src environment variable to the current directory. +It supports the following files by default: + + + + + Tar files + These can optionally be compressed using + gzip (.tar.gz, + .tgz or .tar.Z) or + bzip2 (.tar.bz2 or + .tbz2). + + + + Zip files + Zip files are unpacked using + unzip. However, unzip is + not in the standard environment, so you should add it to + buildInputs yourself. + + + + Directories in the Nix store + These are simply copied to the current directory. + The hash part of the file name is stripped, + e.g. /nix/store/1wydxgby13cz...-my-sources + would be copied to + my-sources. + + + + +Additional file types can be supported by setting the +unpackCmd variable (see below). + + + + + Variables controlling the unpack phase + + + srcs / src + The list of source files or directories to be + unpacked or copied. One of these must be set. + + + + sourceRoot + 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. + + + + setSourceRoot + Alternatively to setting + sourceRoot, you can set + setSourceRoot to a shell command to be + evaluated by the unpack phase after the sources have been + unpacked. This command must set + sourceRoot. + + + + preUnpack + Hook executed at the start of the unpack + phase. + + + + postUnpack + Hook executed at the end of the unpack + phase. + + + + dontMakeSourcesWritable + If set to 1, the unpacked + sources are not 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. + + + + unpackCmd + The unpack phase evaluates the string + $unpackCmd for any unrecognised file. The path + to the current source file is contained in the + curSrc variable. + + + + +
+ + +
The patch phase + +The patch phase applies the list of patches defined in the +patches variable. + + + Variables controlling the patch phase + + + patches + The list of patches. They must be in the format + accepted by the patch command, and may + optionally be compressed using gzip + (.gz) or bzip2 + (.bz2). + + + + patchFlags + Flags to be passed to patch. + If not set, the argument is used, which + causes the leading directory component to be stripped from the + file names in each patch. + + + + prePatch + Hook executed at the start of the patch + phase. + + + + postPatch + Hook executed at the end of the patch + phase. + + + + +
+ + +
The configure phase + +The configure phase prepares the source tree for building. The +default unpackPhase runs +./configure (typically an Autoconf-generated +script) if it exists. + + + Variables controlling the configure phase + + + configureScript + The name of the configure script. It defaults to + ./configure if it exists; otherwise, the + configure phase is skipped. This can actually be a command (like + perl ./Configure.pl). + + + + configureFlags + Additional arguments passed to the configure + script. + + + + configureFlagsArray + A shell array containing additional arguments + passed to the configure script. You must use this instead of + configureFlags if the arguments contain + spaces. + + + + dontAddPrefix + By default, the flag + --prefix=$prefix is added to the configure + flags. If this is undesirable, set this variable to a non-empty + value. + + + + prefix + The prefix under which the package must be + installed, passed via the option to the + configure script. It defaults to + . + + + + dontAddDisableDepTrack + By default, the flag + --disable-dependency-tracking is added to the + configure flags to speed up Automake-based builds. If this is + undesirable, set this variable to a non-empty + value. + + + + dontFixLibtool + By default, the configure phase applies some + special hackery to all files called ltmain.sh + before running the configure script in order to improve the purity + of Libtool-based packagesIt clears the + sys_lib_*search_path + variables in the Libtool script to prevent Libtool from using + libraries in /usr/lib and + such.. If this is undesirable, set this + variable to a non-empty value. + + + + preConfigure + Hook executed at the start of the configure + phase. + + + + postConfigure + Hook executed at the end of the configure + phase. + + + + + +
+ + +
The build phase + +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. + +
+ + +
The check phase + +checkPhase calls make +check, but only if the doCheck variable +is set to 1. Additional flags can be set through +the checkFlags variable. + +
+ + +
The install phase + +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. + +
+ + +
The fixup phase + +fixupPhase cleans up the installed files in +various ways: + - - - - 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 moves the man/, + doc/ and info/ + subdirectories of $out to + share/. - It strips libraries and executables of debug - information. + 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. + 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. - - + 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. -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. +
+ + +
The distribution phase + +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. + +
+