reasampler/docs/cmake-cheatsheet.md

CMake Cheat Sheet

Core loop (the three commands you'll use 95% of the time)

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

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

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)

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

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.