1 files changed, 38 insertions, 3 deletions
diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/builders/packages/cataclysm-dda.section.md
index ae2ee56a010..bfeacb47fef 100644
--- a/doc/builders/packages/cataclysm-dda.section.md
+++ b/doc/builders/packages/cataclysm-dda.section.md
@@ -1,6 +1,6 @@
-# Cataclysm: Dark Days Ahead
+# Cataclysm: Dark Days Ahead {#cataclysm-dark-days-ahead}
 
-## How to install Cataclysm DDA
+## How to install Cataclysm DDA {#how-to-install-cataclysm-dda}
 
 To install the latest stable release of Cataclysm DDA to your profile, execute
 `nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build
@@ -34,7 +34,42 @@ cataclysm-dda.override {
 }
 ```
 
-## Customizing with mods
+## Important note for overriding packages {#important-note-for-overriding-packages}
+
+After applying `overrideAttrs`, you need to fix `passthru.pkgs` and
+`passthru.withMods` attributes either manually or by using `attachPkgs`:
+
+```nix
+let
+  # You enabled parallel building.
+  myCDDA = cataclysm-dda-git.overrideAttrs (_: {
+    enableParallelBuilding = true;
+  });
+
+  # Unfortunately, this refers to the package before overriding and
+  # parallel building is still disabled.
+  badExample = myCDDA.withMods (_: []);
+
+  inherit (cataclysmDDA) attachPkgs pkgs wrapCDDA;
+
+  # You can fix it by hand
+  goodExample1 = myCDDA.overrideAttrs (old: {
+    passthru = old.passthru // {
+      pkgs = pkgs.override { build = goodExample1; };
+      withMods = wrapCDDA goodExample1;
+    };
+  });
+
+  # or by using a helper function `attachPkgs`.
+  goodExample2 = attachPkgs pkgs myCDDA;
+in
+
+# badExample                     # parallel building disabled
+# goodExample1.withMods (_: [])  # parallel building enabled
+goodExample2.withMods (_: [])    # parallel building enabled
+```
+
+## Customizing with mods {#customizing-with-mods}
 
 To install Cataclysm DDA with mods of your choice, you can use `withMods`
 attribute: