doc/build-helpers/special/checkpoint-build.section.md

   1 # pkgs.checkpointBuildTools  {#sec-checkpoint-build}
   2
   3 `pkgs.checkpointBuildTools` provides a way to build derivations incrementally. It consists of two functions to make checkpoint builds using Nix possible.
   4
   5 For hermeticity, Nix derivations do not allow any state to be carried over between builds, making a transparent incremental build within a derivation impossible.
   6
   7 However, we can tell Nix explicitly what the previous build state was, by representing that previous state as a derivation output. This allows the passed build state to be used for an incremental build.
   8
   9 To change a normal derivation to a checkpoint based build, these steps must be taken:
  10   - apply `prepareCheckpointBuild` on the desired derivation, e.g.
  11 ```nix
  12 {
  13   checkpointArtifacts = (pkgs.checkpointBuildTools.prepareCheckpointBuild pkgs.virtualbox);
  14 }
  15 ```
  16   - change something you want in the sources of the package, e.g. use a source override:
  17 ```nix
  18 {
  19   changedVBox = pkgs.virtualbox.overrideAttrs (old: {
  20     src = path/to/vbox/sources;
  21   });
  22 }
  23 ```
  24   - use `mkCheckpointBuild changedVBox checkpointArtifacts`
  25   - enjoy shorter build times
  26
  27 ## Example {#sec-checkpoint-build-example}
  28 ```nix
  29 { pkgs ? import <nixpkgs> {} }:
  30 let
  31   inherit (pkgs.checkpointBuildTools)
  32     prepareCheckpointBuild
  33     mkCheckpointBuild
  34     ;
  35   helloCheckpoint = prepareCheckpointBuild pkgs.hello;
  36   changedHello = pkgs.hello.overrideAttrs (_: {
  37     doCheck = false;
  38     patchPhase = ''
  39       sed -i 's/Hello, world!/Hello, Nix!/g' src/hello.c
  40     '';
  41   });
  42 in mkCheckpointBuild changedHello helloCheckpoint
  43 ```