From 61e3d088495ddc45a266554e4e16044260415906 Mon Sep 17 00:00:00 2001
From: daniel-c-harvey <the.real.daniel.harvey@gmail.com>
Date: Thu, 23 Jul 2026 14:58:26 -0400
Subject: [PATCH] docs: add CMake command cheat sheet

---
 docs/cmake-cheatsheet.md | 79 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 docs/cmake-cheatsheet.md

diff --git a/docs/cmake-cheatsheet.md b/docs/cmake-cheatsheet.md
new file mode 100644
index 0000000..36dd3c5
--- /dev/null
+++ b/docs/cmake-cheatsheet.md
@@ -0,0 +1,79 @@
+# CMake Cheat Sheet
+
+## Core loop (the three commands you'll use 95% of the time)
+
+```bash
+cmake -B build -S .        # Configure: generate build system into ./build from source at .
+cmake --build build        # Build all targets
+ctest --test-dir build     # Run tests
+```
+
+## Configure
+
+```bash
+cmake -B build -S .                                  # Standard out-of-source configure
+cmake -B build -S . -G "Ninja"                       # Pick a generator (Ninja is fast; default on Win is VS)
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug         # Single-config generators (Ninja, Makefiles)
+cmake -B build -S . -DFOO=ON                         # Set a cache variable / project option
+cmake --fresh -B build -S .                          # Wipe the cache, reconfigure from scratch (CMake >=3.24)
+rm -rf build                                         # The nuclear "clean configure" — delete and start over
+```
+
+Configure only needs re-running when you change `CMakeLists.txt` or toolchain/options. CMake also
+auto-reconfigures on `--build` if it detects `CMakeLists.txt` changed.
+
+## Build
+
+```bash
+cmake --build build                              # Build everything
+cmake --build build --target bank_model_tests   # Build one target
+cmake --build build -j                          # Parallel (all cores)
+cmake --build build -j 8                        # Parallel, 8 jobs
+cmake --build build --config Debug              # Multi-config generators (VS/Xcode) — config chosen HERE, not at configure
+cmake --build build --clean-first               # Clean then build
+cmake --build build --verbose                   # Show the actual compiler command lines
+```
+
+**Debug vs Release gotcha:**
+- Single-config (Ninja, Make): set `-DCMAKE_BUILD_TYPE=` at **configure** time.
+- Multi-config (Visual Studio, Xcode): set `--config` at **build** time. `CMAKE_BUILD_TYPE` is ignored.
+
+## Test (CTest)
+
+```bash
+ctest --test-dir build                      # Run all tests
+ctest --test-dir build -V                   # Verbose (show test output)
+ctest --test-dir build --output-on-failure  # Show output only for failures  <- most useful default
+ctest --test-dir build -R peaks             # Run tests matching regex "peaks"
+ctest --test-dir build -R bank_model_tests  # Run one named test
+ctest --test-dir build -E slow              # Exclude tests matching regex
+ctest --test-dir build -j 8                 # Parallel test execution
+ctest --test-dir build --rerun-failed       # Re-run only what failed last time
+ctest --test-dir build -C Debug             # Multi-config: pick which config's tests to run
+```
+
+## Inspect / debug the build itself
+
+```bash
+cmake -B build -S . -L                      # List cache variables (non-advanced)
+cmake -B build -S . -LAH                    # List ALL cache vars + help strings
+cmake --build build --target help           # List available targets (Makefile/Ninja generators)
+cmake -B build -S . --trace-expand          # Trace CMakeLists.txt execution (noisy but revealing)
+ccmake build                                # Curses UI to browse/edit the cache (if installed)
+```
+
+## Install / reload (ReaSampler)
+
+There is no hot-reload for the extension. After building `reaper_reasampler`, copy the binary into
+REAPER's `UserPlugins/` folder (Options -> Show REAPER resource path) and restart REAPER. Extensions
+load at startup only. The `cmake --install` step isn't wired for the DAW drop — it's a manual copy.
+
+## Mental model
+
+- **Two phases:** *configure* (run CMakeLists.txt -> generate a native build system) and *build*
+  (run that build system). Most confusion comes from not knowing which phase a flag belongs to.
+- **Cache:** `build/CMakeCache.txt` remembers every `-D` you set. Setting it once sticks. This is
+  why stale builds happen — and why `rm -rf build` or `--fresh` fixes so much.
+- **Out-of-source:** everything generated lives in `build/`, nothing pollutes the source tree.
+  `build/` is disposable by design.
+- **`-D` sets cache variables:** `-DCMAKE_BUILD_TYPE=Debug`, `-DBUILD_TESTING=OFF`, etc.