From fc2e3fac619288868c4e0b019a8c561ea6885777 Mon Sep 17 00:00:00 2001 From: Martin Messer Date: Mon, 27 Jun 2022 14:03:10 +0200 Subject: [PATCH] doc: add section about checkpointed build --- doc/build-helpers/special.md | 1 + .../special/incremental-build.section.md | 28 +++++++++++++++++++ pkgs/test/incrementalBuild/default.nix | 10 +++---- pkgs/top-level/all-packages.nix | 2 +- 4 files changed, 35 insertions(+), 6 deletions(-) create mode 100644 doc/build-helpers/special/incremental-build.section.md diff --git a/doc/build-helpers/special.md b/doc/build-helpers/special.md index f88648207fdc..baf40a261e81 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/incremental-build.section.md ``` diff --git a/doc/build-helpers/special/incremental-build.section.md b/doc/build-helpers/special/incremental-build.section.md new file mode 100644 index 000000000000..f8e81ddeffc5 --- /dev/null +++ b/doc/build-helpers/special/incremental-build.section.md @@ -0,0 +1,28 @@ +# pkgs.buildIncremental.* {#sec-incremental-build} + +`pkgs.buildIncremental` provides a way to build derivations incrementally. It consists of two functions to make incremental 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 build a derivation incrementally, the following steps needs to be fullfilled: + * - run prepareIncrementalBuild on the desired derivation + * e.G `incrementalBuildArtifacts = (pkgs.buildIncremental.prepareIncrementalBuild pkgs.virtualbox);` + * - change something you want in the sources of the package( e.G using source override) + * changedVBox = pkgs.virtuabox.overrideAttrs (old: { + * src = path/to/vbox/sources; + * } + * - use `mkIncrementalBuild changedVBox buildOutput` + * enjoy shorter build times + +As Nix has no builtin support for the detection of the previous built derivation, a base version needs to be declared. +To create the outputs later used as base version for incremental builds, the function `pkgs.buildIncremental.prepareIncrementalBuild` is used. +The function takes the original derivation as an argument and transforms the output to a base version for an incremental build. +While doing so, the original output is not created and the installation phase is overwritten to produce the incremental build artifacts. + +When the built artifacts of the base version of the derivation are created, the code can be modified and changes are built using the `pkgs.buildIncremental.mkIncrementalBuild` function. +The `pkgs.buildIncremental.mkIncrementalBuild` function detects the changes in the code and places the output of the base version derivation within the build folder. +Then, the build tool is able to detect the changes and makes the decision of which parts of the derivation needs to be recompiled and produces the output, as expected in the derivation, without incremental build support. + + diff --git a/pkgs/test/incrementalBuild/default.nix b/pkgs/test/incrementalBuild/default.nix index c11c9835ccbf..b962befbfbac 100644 --- a/pkgs/test/incrementalBuild/default.nix +++ b/pkgs/test/incrementalBuild/default.nix @@ -1,6 +1,6 @@ -{ hello, buildIncremental, runCommandNoCC, texinfo, stdenv, rsync }: +{ hello, incrementalBuildTools, runCommandNoCC, texinfo, stdenv, rsync }: let - baseHelloArtifacts = buildIncremental.prepareIncrementalBuild hello; + baseHelloArtifacts = incrementalBuildTools.prepareIncrementalBuild hello; patchedHello = hello.overrideAttrs (old: { buildInputs = [ texinfo ]; src = runCommandNoCC "patch-hello-src" { } '' @@ -10,7 +10,7 @@ let patch -p1 < ${./hello.patch} ''; }); - incrementalBuiltHello = buildIncremental.mkIncrementalBuild patchedHello baseHelloArtifacts; + incrementalBuiltHello = incrementalBuildTools.mkIncrementalBuild patchedHello baseHelloArtifacts; incrementalBuiltHelloWithCheck = incrementalBuiltHello.overrideAttrs (old: { doCheck = true; @@ -20,7 +20,7 @@ let ''; }); - baseHelloRemoveFileArtifacts = buildIncremental.prepareIncrementalBuild (hello.overrideAttrs (old: { + baseHelloRemoveFileArtifacts = incrementalBuildTools.prepareIncrementalBuild (hello.overrideAttrs (old: { patches = [ ./hello-additionalFile.patch ]; })); @@ -41,7 +41,7 @@ let ''; }); - incrementalBuiltHelloWithRemovedFile = buildIncremental.mkIncrementalBuild patchedHelloRemoveFile baseHelloRemoveFileArtifacts; + incrementalBuiltHelloWithRemovedFile = incrementalBuildTools.mkIncrementalBuild patchedHelloRemoveFile baseHelloRemoveFileArtifacts; in stdenv.mkDerivation { name = "patched-hello-returns-correct-output"; diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix index 9ff07d888b7f..4ad119789512 100644 --- a/pkgs/top-level/all-packages.nix +++ b/pkgs/top-level/all-packages.nix @@ -429,7 +429,7 @@ with pkgs; camunda-modeler = callPackage ../applications/misc/camunda-modeler { }; - inncrementalBuildTools = callPackage ../build-support/build-incremental.nix {}; + incrementalBuildTools = callPackage ../build-support/build-incremental.nix {}; caroline = callPackage ../development/libraries/caroline { };