diff options
author | Bryan Lai <bryanlais@gmail.com> | 2024-01-07 18:57:04 +0800 |
---|---|---|
committer | Bryan Lai <bryanlais@gmail.com> | 2024-01-09 01:34:21 +0800 |
commit | d7253bea6d7366987acce31c2c2355ffbdf389b4 (patch) | |
tree | ce72accc96bab163d9b017c71a7fbb331ab5c3a1 /doc/build-helpers/special | |
parent | 5f3aad00ffc0a769a1ccc5b3b521221aa5e5d809 (diff) |
doc: polish the docs of `checkpointBuildTools`
... following suggestions from @phip1611 and @infinisil.
Diffstat (limited to 'doc/build-helpers/special')
-rw-r--r-- | doc/build-helpers/special/checkpoint-build.section.md | 21 |
1 files changed, 12 insertions, 9 deletions
diff --git a/doc/build-helpers/special/checkpoint-build.section.md b/doc/build-helpers/special/checkpoint-build.section.md index 676f04aa7a4e..f60afe801ed4 100644 --- a/doc/build-helpers/special/checkpoint-build.section.md +++ b/doc/build-helpers/special/checkpoint-build.section.md @@ -2,35 +2,38 @@ `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. +For hermeticity, Nix derivations do not allow any state to be carried 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.: + - 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) + - change something you want in the sources of the package, e.g. use a source override: ```nix changedVBox = pkgs.virtualbox.overrideAttrs (old: { src = path/to/vbox/sources; -} +}); ``` - - use `mkCheckpointBuild changedVBox incrementalBuildArtifacts` + - use `mkCheckpointBuild changedVBox checkpointArtifacts` - enjoy shorter build times ## Example {#sec-checkpoint-build-example} ```nix -{ pkgs ? import <nixpkgs> {} }: with (pkgs) checkpointBuildTools; +{ pkgs ? import <nixpkgs> {} }: let - helloCheckpoint = checkpointBuildTools.prepareCheckpointBuild pkgs.hello; + inherit (pkgs.checkpointBuildTools) + prepareCheckpointBuild + mkCheckpointBuild + ; + helloCheckpoint = 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 +in mkCheckpointBuild changedHello helloCheckpoint ``` |