3.4. Phases

The generic builder has a number of phases. 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 overridden 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.

3.4.1. 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.

preFixupPhases

Additional phases executed just before the fixup phase.

preDistPhases

Additional phases executed just before the distribution phase.

postPhases

Additional phases executed after any of the default phases.

3.4.2. 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), bzip2 (.tar.bz2 or .tbz2) or xz (.tar.xz or .tar.lzma).
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.

3.4.3. 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), bzip2 (.bz2) or xz (.xz).
patchFlags: Flags to be passed to patch. If not set, the argument -p1 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.

3.4.4. The configure phase

The configure phase prepares the source tree for building. The default configurePhase 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

A list of strings passed as additional arguments 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 true.

prefix

The prefix under which the package must be installed, passed via the --prefix option to the configure script. It defaults to $out.

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 true.

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 packages ^[1]. If this is undesirable, set this variable to true.

dontDisableStatic

By default, when the configure script has --enable-static, the option --disable-static is added to the configure flags.

If this is undesirable, set this variable to true.

preConfigure

Hook executed at the start of the configure phase.

postConfigure

Hook executed at the end of the configure phase.

3.4.5. The build phase

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

dontBuild

Set to true to skip the build phase.

makefile

The file name of the Makefile.

makeFlags

A list of strings passed as additional flags 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

A list of strings passed as additional flags 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.

Before and after running make, the hooks preBuild and postBuild are called, respectively.

3.4.6. The check phase

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

A list of strings passed as additional flags 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.

3.4.7. The install phase

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 install 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

A list of strings passed as additional flags 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.

3.4.8. The fixup phase

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/, 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 runtime 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.

Variables controlling the fixup phase

dontStrip

If set, libraries and executables are not stripped. By default, they are.

dontMoveSbin

If set, files in $out/sbin are not moved to $out/bin. 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 -s (i.e. --strip-all).

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 -S (i.e. --strip-debug).

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.

setupHook

A package can export a setup hook by setting this variable. The setup hook, if defined, is copied to $out/nix-support/setup-hook. Environment variables are then substituted in it using substituteAll.

preFixup

Hook executed at the start of the fixup phase.

postFixup

Hook executed at the end of the fixup phase.

separateDebugInfo

If set to true, the standard environment will enable debug information in C/C++ builds. After installation, the debug information will be separated from the executables and stored in the output named debug. (This output is enabled automatically; you don’t need to set the outputs attribute explicitly.) To be precise, the debug information is stored in debug/lib/debug/.build-id/XX/YYYY…, where XXYYYY… is the build ID of the binary — a SHA-1 hash of the contents of the binary. Debuggers like GDB use the build ID to look up the separated debug information.

For example, with GDB, you can add

set debug-file-directory ~/.nix-profile/lib/debug

to ~/.gdbinit. GDB will then be able to find debug information installed via nix-env -i.

3.4.9. The distribution phase

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 attribute doDist is 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.

^[1]It clears the sys_lib_*search_path variables in the Libtool script to prevent Libtool from using libraries in /usr/lib and such.