cmake: Usage, Options & Common CI Errors
cmake generates native build files from a CMakeLists.txt, then drives the build.
cmake is the cross-platform build generator for C/C++. The modern -S/-B and --build flow avoids most pitfalls; the failures left are missing dependencies and generator/cache mismatches.
What it does
cmake reads CMakeLists.txt, configures the project (finds compilers and dependencies, evaluates options), and generates build files for a chosen generator (Make, Ninja, MSBuild). A second invocation with --build runs the actual compile.
Common usage
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
cmake --build build --target test
cmake -S . -B build -G Ninja
cmake --install build --prefix /usr/localOptions
| Flag | What it does |
|---|---|
| -S <dir> -B <dir> | Source dir and (separate) build dir |
| -D NAME=VALUE | Set a cache variable (e.g. CMAKE_BUILD_TYPE) |
| -G <generator> | Choose the build system (Ninja, Make...) |
| --build <dir> | Run the generated build |
| --target <t> | Build a specific target |
| --install <dir> | Run the install step |
Common errors in CI
CMake Error: Could not find a package configuration file provided by "X" - a dependency is missing or CMAKE_PREFIX_PATH does not point at it; install the -dev package or set the path. "does not appear to contain CMakeLists.txt" means -S points at the wrong directory. "The CMAKE_C_COMPILER is not set" means no compiler is installed. Reusing a build dir created with a different generator triggers a cache mismatch - delete build/ or use a fresh -B dir in CI.