From cdfbdb0b2c0eab92079d1e477a93781d7b9e2cc2 Mon Sep 17 00:00:00 2001
From: Mitsuhiro Nakamura <m.nacamura@gmail.com>
Date: Thu, 12 Nov 2020 12:37:49 +0900
Subject: [PATCH] doc: add usage for `cataclysmDDA.attachPkgs`

---
 .../packages/cataclysm-dda.section.md         | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/builders/packages/cataclysm-dda.section.md
index ae2ee56a010..ae7a05005e7 100644
--- a/doc/builders/packages/cataclysm-dda.section.md
+++ b/doc/builders/packages/cataclysm-dda.section.md
@@ -34,6 +34,41 @@ cataclysm-dda.override {
 }
 ```
 
+## 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
 
 To install Cataclysm DDA with mods of your choice, you can use `withMods`