cmake -S -B -G: Configure an Out-of-Source Build
cmake -S <source> -B <build> generates a build system in a separate directory, keeping the source tree clean.
The configure step is where CMake reads CMakeLists.txt and emits native build files. In CI you always want an out-of-source build so caching and cleanup are predictable.
What it does
cmake reads the CMakeLists.txt in the source dir (-S), detects the toolchain, and writes build files into the build dir (-B) using the chosen generator (-G). It does not compile anything; that is the separate --build step.
Common usage
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake -S . -B build # default generator (Unix Makefiles on Linux)
cmake -S . -B build -G "Unix Makefiles"Options
| Flag | What it does |
|---|---|
| -S <dir> | Source directory containing the top CMakeLists.txt |
| -B <dir> | Build directory to generate into (created if absent) |
| -G <generator> | Build system to generate: Ninja, "Unix Makefiles", etc. |
| -D <var>=<value> | Set a CMake cache variable (see the -D reference) |
| --toolchain <file> | Use a CMake toolchain file for cross builds |
| --fresh | CMake 3.24+: wipe the cache and reconfigure from scratch |
In CI
Always build out-of-source (-B build) so you can cache the build dir independently and delete it cleanly. Prefer -G Ninja on CI runners for faster, more parallel builds than Make. Install ninja (apt-get install ninja-build) before selecting it.
Common errors in CI
"CMake Error: could not find CMAKE_ROOT" means a broken or partial CMake install. "No CMAKE_CXX_COMPILER could be found" means no C++ compiler is on PATH; install build-essential/g++ first. "CMake Error: The source directory ... does not appear to contain CMakeLists.txt" means -S points at the wrong path. "Generator Ninja not found" means ninja is not installed.