cmake --build: Drive the Build Generator
cmake --build <dir> invokes the underlying generator (Ninja, Make, MSBuild) to compile a project, so your CI script stays generator-agnostic.
Instead of calling ninja or make directly, cmake --build wraps them with one portable command. That keeps the same CI step working across Linux, macOS, and Windows.
What it does
cmake --build runs the generator that the configure step produced, in the given build directory. It forwards parallelism and target selection to that generator, so one command works whether the backend is Ninja, Make, or MSBuild.
Common usage
cmake --build build
cmake --build build --target install
cmake --build build --config Release -j 4
cmake --build build --target mytest --parallelOptions
| Flag | What it does |
|---|---|
| --build <dir> | The configured build directory to build |
| --target <name> | Build a specific target instead of the default (all) |
| --config <cfg> | Multi-config generators only: Release, Debug, etc. |
| -j <N> / --parallel <N> | Build with N parallel jobs (CMake 3.12+) |
| --clean-first | Clean before building |
| -v / --verbose | Show the actual compiler command lines |
In CI
Use -j matched to the runner core count (e.g. --parallel $(nproc)) to cut wall time. On multi-config generators (Visual Studio, Xcode) --config selects the build type at build time, not configure time, so it must be passed here.
Common errors in CI
"Error: could not load cache" means the build dir was never configured (run cmake -S -B first). On multi-config generators, missing artifacts often mean you forgot --config Release. A build that silently uses one core usually lacks -j; add --parallel. Compiler errors surface from the underlying generator, so run with -v to see the exact command.