# 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.