From d7253bea6d7366987acce31c2c2355ffbdf389b4 Mon Sep 17 00:00:00 2001
From: Bryan Lai <bryanlais@gmail.com>
Date: Sun, 7 Jan 2024 18:57:04 +0800
Subject: doc: polish the docs of `checkpointBuildTools`

... following suggestions from @phip1611 and @infinisil.
---
 .../special/checkpoint-build.section.md             | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

(limited to 'doc/build-helpers/special')

diff --git a/doc/build-helpers/special/checkpoint-build.section.md b/doc/build-helpers/special/checkpoint-build.section.md
index 676f04aa7a4eb..f60afe801ed4c 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
 ```
-- 
cgit 1.4.1