Derivations

A Nix derivation is a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths. Simply put, it describes a set of steps to take some input and produce some output in a deterministic manner.

Derivations are extremely powerful and a core part of Nix utility and provide the core platform for how packaging is done in NixOS. The low-level derivation function is extremely simple, and can become repetitive to define package constructs with, so Nixpkgs hoists the standard environment (colloquially referred to as the stdenv), which provides a sparse set of compilation tools and a derivation construct that avoids the low-level details and provides abstractions to simplify packaging.

Getting Started

Derivations take an input and produce an output through a series of steps. For most packages, the inputs refer to the source files, the steps refer to the compilation process, and the outputs refer to finalized executable binaries. This sequence of events can be well described within a standard environment.

src

This attribute points towards the inputs used within the derivation. This can be source code, but it can also be a pre-build binary. Usually depending on what the source is, a special series of steps is done to ensure its correctness in a Nix environment.

This usually is downloaded via a fetcher, but it can also be a local path:

stdenv.mkDerivation {

  src = ./relative-path/to/src;
  # OR
  src = fetchFromGitHub {
    owner = "torvalds";
    repo = "linux";
    rev = "refs/tags/v6.11";

    hash = "...";
  };
}

out

Unlike src, this is not an attribute but rather an environment variable which points to the finalized location of the derivation's contents. Anything placed within $out will then be part of the final derivation. Usually this follows an FHS-inspired like structure, where $out/bin contains binaries, $out/lib contains shared objects, $out/include contains headers, and so forth. These paths will become part of the derivation and are the resulting entries within the /nix/store.

This step is handled largely by the installPhase, which you'll understand more in Phases, and is described within the derivation as a series of bash commands to execute:

stdenv.mkDerivation {
  src = ...;

  installPhase = ''
    mkdir -p $out/bin

    install -Dm755 -t $out/bin ./my-binary
  '';
}