Learning Nix - Nixpkgs standard environment

25/04/2023

Explaining the build process with nixpkgs.stdenv

In the previous post, we saw the basic syntax of Nix and learned about derivations.

The built-in function derivation makes it possible to define a derivation, given at least a name, a system and an executable to build the package.

In practice however, you still need the builder logic, for instance: unpack the source, then ./configure; make; make install. For a lot of packages, this builder logic will be similar, hence the stdenv package.

The setup.sh script

Most of the logic necessary to build and install autotools packages is inside this script.

First, it clears the PATH and fills it with a couple of useful tools ¹, such as the GNU coreutils, tar, make, grep, etc.

Then, it defines the following bash functions:

• unpackPhase: Unpack the source files (specified by the src or srcs environment variables) into the current directory. The src may refer either to a directory (which will be copied) or a compressed file (e.g. .tar.gz) which will be extracted.
• patchPhase: Apply patches (if any) using the unix patch utility. Patches are provided by the patches list.
• configurePhase: Prepare the sources tree or building. By default, this can call ./configure with a bunch of flags.
• buildPhase: Actually compile the package, if a Makefile can be found, otherwise does nothing.
• installPhase: Install the packages under $out (typically /nix/store/<package-hash>/out). By default, creates the $out directory and call make install.
• fixupPhase: Perform Nix-specific post-processing actions on the files installed under $out. For instance, prevent unnecessary runtime dependencies with the patchelf command, or patch shebangs in shell scripts to use Nix store packages. See the doc for more info.

Finally, it defines the genericBuild function which calls all these phases successively, plus any pre/post hooks defined for each phase ².

This script is an output of the stdenv derivation, which means that you can use it to reproduce the build environment, and debug your package step-by-step manually.

• simply run source $stdenv/setup in an env where stdenv is defined
  • this can be a derivation coming from mkDerivation (which seems to add it automatically)
  • this can simply be a derivation where stdenv is defined as an attr
  • this is what default-builder.sh, the builder defined by default by mkDerivation, does (in the nix-build command)
  • this is also what is done (more or less?? depending on the –pure option?) by nix-shell

The stdenv.mkDerivation function

In practice, most packages do not directly use the derivation function but rather the mkDerivation function, defined in the stdenv package.

This wrapper around the builtin derivation conveniently sets some attributes of the output derivation:

• It sets stdenv derivation to use the system stdenv derivation
• It sets builder to stdenv.shell, which is set to bash by default
• It sets args to ["-e" ./default-builder.sh] by default, which basically does source $stdenv/setup && genericBuild (see source code). Another build script can be configured by calling mkDerivation with builder = ./my-builder.sh for instance. ⚠️ This is not the builder derivation attribute !
• It adds a overrideAttrs attribute to the derivation produced (cf Overrides section below).
• It makes it possible to call it with or without args?

Also, it sets the name and system attributes (using provided pname/version or name, and stdenv.buildPlatform.system).