diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 39c5c3d34fe5..26abf34620b5 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -180,8 +180,13 @@ genericBuild
Phases The generic builder has a number of phases. -Each phase can be overriden in its entirety either by setting the -environment variable +Package builds are split into phases to make it easier to override +specific parts of the build (e.g., unpacking the sources or installing +the binaries). Furthermore, it allows a nicer presentation of build +logs in the Nix build farm. + +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 @@ -504,7 +509,73 @@ script) if it exists.
The build phase -buildPhase calls make. +The build phase is responsible for actually building the package +(e.g. compiling it). The default buildPhase +simply calls make if a file named +Makefile, makefile or +GNUmakefile exists in the current directory (or +the makefile is explicitly set); otherwise it does +nothing. + + + Variables controlling the build phase + + + makefile + The file name of the Makefile. + + + + makeFlags + Additional flags passed to + make. These flags are also used by the default + install and check phase. For setting make flags specific to the + build phase, use buildFlags (see + below). + + + + makeFlagsArray + A shell array containing additional arguments + passed to make. You must use this instead of + makeFlags if the arguments contain + spaces, e.g. + + +makeFlagsArray=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar") + + + Note that shell arrays cannot be passed through environment + variables, so you cannot set makeFlagsArray in + a derivation attribute (because those are passed through + environment variables): you have to define them in shell + code. + + + + buildFlags / buildFlagsArray + Additional flags passed to + make. Like makeFlags and + makeFlagsArray, but only used by the build + phase. + + + + preBuild + Hook executed at the start of the build + phase. + + + + postBuild + Hook executed at the end of the build + phase. + + + + + + You can set flags for make through the makeFlags variable. @@ -517,32 +588,126 @@ 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 check phase checks whether the package was built correctly +by running its test suite. The default +checkPhase calls make check, +but only if the doCheck variable is enabled. + + + Variables controlling the check phase + + + doCheck + If set to a non-empty string, the check phase is + executed, otherwise it is skipped (default). Thus you should set + + +doCheck = true; + + in the derivation to enable checks. + + + + makeFlags / + makeFlagsArray / + makefile + See the build phase for details. + + + + checkTarget + The make target that runs the tests. Defaults to + check. + + + + checkFlags / checkFlagsArray + Additional flags passed to + make. Like makeFlags and + makeFlagsArray, but only used by the check + phase. + + + + preCheck + Hook executed at the start of the check + phase. + + + + postCheck + Hook executed at the end of the check + phase. + + + +
The install phase -installPhase calls make -install. Additional flags can be set through the -installFlags variable. +The install phase is responsible for installing the package in +the Nix store under out. The default +installPhase creates the directory +$out and calls make +install. + + + Variables controlling the check phase + + + makeFlags / + makeFlagsArray / + makefile + See the build phase for details. + + + + installTargets + The make targets that perform the installation. + Defaults to install. Example: + + +installTargets = "install-bin install-doc"; + + + + + + installFlags / installFlagsArray + Additional flags passed to + make. Like makeFlags and + makeFlagsArray, but only used by the install + phase. + + + + preInstall + Hook executed at the start of the install + phase. + + + + postInstall + Hook executed at the end of the install + phase. + + + -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: - +The fixup phase performs some (Nix-specific) post-processing +actions on the files installed under $out by the +install phase. The default fixupPhase does the +following: + It moves the man/, @@ -556,7 +721,7 @@ various ways: 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. + unnecessary runtime dependencies. It rewrites the interpreter paths of shell scripts to paths found in PATH. E.g., @@ -568,21 +733,139 @@ various ways: + + Variables controlling the check phase + + + dontStrip + If set, libraries and executables are not + stripped. By default, they are. + + + + stripAllList + List of directories to search for libraries and + executables from which all symbols should be + stripped. By default, it’s empty. Stripping all symbols is + risky, since it may remove not just debug symbols but also ELF + information necessary for normal execution. + + + + stripAllFlags + Flags passed to the strip + command applied to the files in the directories listed in + stripAllList. Defaults to + (i.e. ). + + + + stripDebugList + List of directories to search for libraries and + executables from which only debugging-related symbols should be + stripped. It defaults to lib bin + sbin. + + + + stripDebugFlags + Flags passed to the strip + command applied to the files in the directories listed in + stripDebugList. Defaults to + + (i.e. ). + + + + dontPatchELF + If set, the patchelf command is + not used to remove unnecessary RPATH entries. + Only applies to Linux. + + + + dontPatchShebangs + If set, scripts starting with + #! do not have their interpreter paths + rewritten to paths in the Nix store. + + + + forceShare + The list of directories that must be moved from + $out to $out/share. + Defaults to man doc info. + + + + preFixup + Hook executed at the start of the fixup + phase. + + + + postFixup + Hook executed at the end of the fixup + phase. + + + +
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. +The distribution phase is intended to produce a source +distribution of the package. The default +distPhase first calls make +dist, then it copies the resulting source tarballs to +$out/tarballs/. This phase is only executed if +the doDist is not set. + + + Variables controlling the distribution phase + + + distTarget + The make target that produces the distribution. + Defaults to dist. + + + + distFlags / distFlagsArray + Additional flags passed to + make. + + + + tarballs + The names of the source distribution files to be + copied to $out/tarballs/. It can contain + shell wildcards. The default is + *.tar.gz. + + + + dontCopyDist + If set, no files are copied to + $out/tarballs/. + + + + preDist + Hook executed at the start of the distribution + phase. + + + + postDist + Hook executed at the end of the distribution + phase. + + + -Before and after running make dist, the hooks -preDist and postDist are called, -respectively.