Merge pull request #167670 from messemar/incremental-builds

incremental builds: add derivation override functions

2 files changed, 37 insertions, 0 deletions

diff --git a/doc/build-helpers/special.md b/doc/build-helpers/special.md
index f88648207fdcd..265c2da92bf18 100644
--- a/doc/build-helpers/special.md
+++ b/doc/build-helpers/special.md
@@ -7,4 +7,5 @@ special/fhs-environments.section.md
 special/makesetuphook.section.md
 special/mkshell.section.md
 special/vm-tools.section.md
+special/checkpoint-build.section.md
 ```
diff --git a/doc/build-helpers/special/checkpoint-build.section.md b/doc/build-helpers/special/checkpoint-build.section.md
new file mode 100644
index 0000000000000..5f01e699b9477
--- /dev/null
+++ b/doc/build-helpers/special/checkpoint-build.section.md
@@ -0,0 +1,36 @@
+# pkgs.checkpointBuildTools  {#sec-checkpoint-build}
+
+`pkgs.checkpointBuildTools` provides a way to build derivations incrementally. It consists of two functions to make checkpoint builds using Nix possible.
+
+For hermeticity, Nix derivations do not allow any state to carry over between builds, making a transparent incremental build within a derivation impossible.
+
+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.
+
+To change a normal derivation to a checkpoint based build, these steps must be taken:
+  - apply `prepareCheckpointBuild` on the desired derivation
+    e.g.:
+```nix
+checkpointArtifacts = (pkgs.checkpointBuildTools.prepareCheckpointBuild pkgs.virtualbox);
+```
+  - change something you want in the sources of the package. (e.g. using a source override)
+```nix
+changedVBox = pkgs.virtualbox.overrideAttrs (old: {
+  src = path/to/vbox/sources;
+}
+```
+  - use `mkCheckpointedBuild changedVBox buildOutput`
+  - enjoy shorter build times
+
+## Example {#sec-checkpoint-build-example}
+```nix
+{ pkgs ? import <nixpkgs> {} }: with (pkgs) checkpointBuildTools;
+let
+  helloCheckpoint = checkpointBuildTools.prepareCheckpointBuild pkgs.hello;
+  changedHello = pkgs.hello.overrideAttrs (_: {
+    doCheck = false;
+    patchPhase = ''
+      sed -i 's/Hello, world!/Hello, Nix!/g' src/hello.c
+    '';
+  });
+in checkpointBuildTools.mkCheckpointBuild changedHello helloCheckpoint
+```