docs: document how to override mkShell/stdenv for devShell (#709)

ipetkov · Sep 25, 2024 · 5c57ab3 · 5c57ab3
1 parent d3797a7
commit 5c57ab3
Showing 1 changed file with 19 additions and 0 deletions.
diff --git a/docs/API.md b/docs/API.md
@@ -917,6 +917,25 @@ craneLib.devShell {
 }
 ```
 
+Note that it is possible to override the underlying `mkShell` (for example to
+customize the build environment further) like so:
+
+```nix
+let
+  moldDevShell = craneLib.devShell.override {
+    # For example, use the mold linker
+    mkShell = pkgs.mkShell.override {
+      stdenv = pkgs.stdenvAdapters.useMoldLinker pkgs.stdenv;
+    };
+  };
+in
+moldDevShell {
+  packages = [
+    # etc...
+  ];
+}
+```
+
 ### `craneLib.downloadCargoPackage`
 
 `downloadCargoPackage :: set -> drv`