skip to content

Generators and Toolchains

A generator picks Ninja, Makefiles, Visual Studio or Xcode output, and a toolchain file points CMake at a cross compiler and sysroot. Asked whenever a build targets another platform.

on this pageshow

explore

questions

4

In CMake, what does a generator do, how do you choose one with -G, and why does a build directory keep only one?

level: juniorimportance: must knowfreq 62%

answer

  1. CMake writes files, another tool builds
  2. -G at first configure
  3. CMAKE_GENERATOR environment variable
  4. recorded in CMakeCache.txt
  5. cmake --build drives any tool

basics

~20 s

A CMake generator writes the native build system: Makefiles, build.ninja, a Visual Studio solution or an Xcode project. You pick it with -G when a build directory is first configured; the choice is recorded there, so another generator needs another or a fresh directory.

solid answer

~40 s

CMake does not compile anything itself: the configure step reads `CMakeLists.txt` and a **generator** writes input for a native build tool. `-G Ninja`, `-G "Unix Makefiles"`, `-G "Visual Studio 17 2022"` and `-G Xcode` are typical choices; without `-G`, CMake uses the `CMAKE_GENERATOR` environment variable and otherwise a built-in default that `cmake --help` marks with a `*` (Unix Makefiles on Linux and macOS). The choice is stored in the build tree's `CMakeCache.txt`, and re-running with another `-G` fails with "Does not match the generator used previously", so you use a second build directory or reconfigure with `--fresh`. Because builds are out-of-source, one checkout can hold `build-ninja/` and `build-vs/` side by side, and `cmake --build <dir>` runs whichever tool that directory was generated for.

code

console · 7 lines
console
$ cmake -S . -B build -G Ninja
$ cmake -S . -B build -G "Unix Makefiles"
CMake Error: Error: generator : Unix Makefiles
Does not match the generator used previously: Ninja
Either remove the CMakeCache.txt file and CMakeFiles directory or choose a different binary directory.
$ cmake -S . -B build-make -G "Unix Makefiles"
$ cmake --build build-make

go deeper

for a junior

Know that CMake only generates build files, that -G picks the generator on the first configure, and that you build with cmake --build afterwards.

for a middle

Explain where the choice is recorded, why a second -G on the same directory fails, and how the environment variable and --fresh fit in.

for a senior

Keep build scripts generator-agnostic with cmake --build, and give each generator or platform its own build directory so trees never share a stale cache.

for a principal

Decide which generator a team standardises on per platform, weighing build speed, IDE integration and multi-config needs, and encode it once rather than in every developer's shell.

## Configure, generate, build CMake is a **build system generator**. Running `cmake -S . -B build` has two phases: 1. **Configure**: CMake runs the project's `CMakeLists.txt`, detects the compilers and fills the cache (`build/CMakeCache.txt`). 2. **Generate**: a **generator** turns the resulting targets into files that a native build tool understands. The compiling and linking happen later, when that native tool runs. The generator is therefore the bridge between the project description and the tool that does the work. ## The generators you meet | Generator (`-G` value) | Writes | Build tool | Configurations per build tree | |---|---|---|---| | `Unix Makefiles` | `Makefile` | `make` | one | | `Ninja` | `build.ninja` | `ninja` | one | | `Ninja Multi-Config` | `build-<Config>.ninja` per configuration | `ninja` | several | | `Visual Studio 17 2022`, `Visual Studio 18 2026` | `.sln` and `.vcxproj` files | MSBuild or the IDE | several | | `Xcode` | `.xcodeproj` | `xcodebuild` or the IDE | several | The CMake manual groups them as **command-line build tool generators** (Makefiles, Ninja, FASTBuild) and **IDE build tool generators** (Visual Studio, Xcode, Green Hills MULTI). A command-line generator expects CMake to be launched from an environment already set up for the compiler; an IDE generator lets the IDE configure its own environment. `cmake --help` lists the generators available on the current platform, so a Visual Studio generator never appears on Linux. ## Choosing one The generator is selected once, when a build tree is created: - `-G <name>` on the command line names it explicitly. - If `-G` is absent, the `CMAKE_GENERATOR` environment variable (CMake 3.15+) supplies the default. - Otherwise CMake falls back to a built-in default; `cmake --help` marks it with `*`, and on Linux and macOS it is `Unix Makefiles`. - A configure preset can also name the generator; presets are covered in the material on presets and policies. The selection lands in the `CMAKE_GENERATOR` variable, which project code should only read, never set. ## One build tree, one generator The generated files, the cache and the detected compilers all belong to one generator, so CMake refuses to mix them. Re-running an existing Ninja build directory with `-G "Unix Makefiles"` stops with: ```plaintext CMake Error: Error: generator : Unix Makefiles Does not match the generator used previously: Ninja Either remove the CMakeCache.txt file and CMakeFiles directory or choose a different binary directory. ``` The fixes: - **Use another build directory.** Out-of-source builds make this cheap: `build-ninja/` and `build-vs/` can sit next to one source tree. - **Reconfigure with `--fresh`** (CMake 3.24+), which discards the existing cache as if the tree were new; files the old generator wrote may still sit in the directory, so a clean directory is tidier. Setting `CMAKE_GENERATOR` in the environment after the tree exists changes nothing either: later runs reuse the generator recorded in the cache. ## Building without naming the tool `cmake --build build` asks the generator's tool to build the tree, whether that is `make`, `ninja` or MSBuild. Options such as `--target`, `--parallel` and, for multi-config generators, `--config` are translated for that tool. Scripts and CI jobs that use `cmake --build` keep working when someone switches the build directory from Makefiles to Ninja, while a script that calls `make` directly breaks. ## Names, versions and options Generator names are exact strings, quoted when they contain spaces. The Visual Studio generators carry the IDE version and year (`Visual Studio 17 2022`, and `Visual Studio 18 2026` since CMake 4.2), and they take two further options that only some generators support: - `-A <platform>` sets `CMAKE_GENERATOR_PLATFORM`, the target architecture such as `x64`, `Win32` or `ARM64`; without it, Visual Studio 2019 and later generators target the host's architecture (older ones defaulted to `Win32`). - `-T <toolset>` sets `CMAKE_GENERATOR_TOOLSET`, for example a different MSVC toolset or `ClangCL`; `Xcode` and `Green Hills MULTI` also accept a toolset. Like the generator itself, both are fixed once a tree is configured. The "extra generators" such as `CodeBlocks - Ninja`, which add an IDE project beside a Ninja or Makefile build, are deprecated since CMake 3.27; the CMake documentation points IDEs at its file API instead. ## Why the choice matters in practice - **Ninja** is the usual choice for fast incremental command-line builds and is what many IDE integrations drive under the hood. - **Unix Makefiles** is always available on Unix-like systems and needs nothing extra installed. - **Visual Studio** and **Xcode** generators produce real IDE projects for developers who build and debug in those IDEs, and both are multi-config. Which configurations a tree holds (one or several) is the main behavioural difference between generators; how Debug and Release flags are chosen per configuration is covered in the material on build configurations.

  • What does cmake --build give you over running make or ninja yourself?
    `cmake --build <dir>` invokes whatever native tool the directory was generated for and translates common options: `--target`, `--parallel`, `--clean-first` and, for multi-config generators, `--config`. A CI script written against it survives a switch from Makefiles to Ninja or to Visual Studio.
  • How do you make Ninja the default generator for every new build tree on your machine without typing -G each time?
    Set the `CMAKE_GENERATOR` environment variable, for example `export CMAKE_GENERATOR=Ninja`. CMake reads it only when `-G` is absent and only when a build tree is first created; an existing tree keeps the generator in its cache. A configure preset that names a generator is the per-project equivalent.

  • CMake compiles the code itself, so the generator choice is cosmetic
  • You can switch an existing build directory to Ninja by re-running cmake with -G Ninja
  • Exporting CMAKE_GENERATOR changes the generator of an already configured build tree
  • Project CMakeLists.txt should set CMAKE_GENERATOR to pick the generator
  • Build scripts must call make or ninja directly because cmake --build only works with Makefiles
open as a page

In CMake, how does a single-config generator such as Ninja differ from multi-config generators like Ninja Multi-Config, Visual Studio or Xcode?

level: middleimportance: should knowfreq 50%

basics

~20 s

A single-config generator builds one configuration per build tree, fixed at configure time. A multi-config generator writes every configuration in CMAKE_CONFIGURATION_TYPES into one tree, and the configuration is picked at build time with --config or in the IDE.

open as a page

In a CMake cross build for an ARM board, how do CMAKE_SYSROOT and the CMAKE_FIND_ROOT_PATH_MODE_* variables keep find_library and find_program from picking the wrong machine's files?

level: seniorimportance: should knowfreq 40%

basics

~20 s

find_* commands search the re-rooted prefixes (CMAKE_FIND_ROOT_PATH, CMAKE_SYSROOT) and, by default, the host too. Setting the library, include and package modes to ONLY keeps them inside the target roots, and the program mode to NEVER finds build tools on the host.

open as a page

When CMake cross-compiles a project from an x86 workstation for a Linux ARM board, what belongs in the toolchain file, and when does CMake read it?

level: seniorimportance: should knowfreq 55%

basics

~20 s

The toolchain file describes the target: CMAKE_SYSTEM_NAME and CMAKE_SYSTEM_PROCESSOR, the cross compilers, an optional CMAKE_SYSROOT and the find-root modes. It is passed with --toolchain or CMAKE_TOOLCHAIN_FILE when the build tree is first configured, and read before compiler detection.

open as a page