80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# 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.
|