In CMake, how does a single-config generator such as Ninja differ from multi-config generators like Ninja Multi-Config, Visual Studio or Xcode?
answer
- one tree per config vs one tree
- choose at configure or at build
- CMAKE_CONFIGURATION_TYPES
- build-<Config>.ninja files
- GENERATOR_IS_MULTI_CONFIG
basics
~20 sA 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.
solid answer
~40 sWith `Ninja` or `Unix Makefiles`, one build directory holds exactly one configuration, chosen when CMake configures it, so Debug and Release need two directories. `Ninja Multi-Config` (CMake 3.17+), the Visual Studio generators and `Xcode` generate all configurations listed in `CMAKE_CONFIGURATION_TYPES` into one directory; you choose one when building with `cmake --build build --config Release` or in the IDE, and outputs go to per-configuration subdirectories such as `Release/`. Ninja Multi-Config writes one `build-<Config>.ninja` per configuration plus a default `build.ninja`. Project code detects the kind with `get_property(... GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)` and must never assume one configuration is active while CMake runs, which is why per-configuration settings are written as generator expressions rather than `if()` tests.
code
console · 9 lines$ cmake -S . -B build -G "Ninja Multi-Config"
-- gen=Ninja Multi-Config multi=1 types=Debug;Release;RelWithDebInfo
$ ls build
CMakeCache.txt CMakeFiles Debug RelWithDebInfo Release
build-Debug.ninja build-RelWithDebInfo.ninja build-Release.ninja
build.ninja cmake_install.cmake
$ cmake --build build --config Release
[1/2] Building CXX object CMakeFiles/core.dir/Release/core.cpp.o
[2/2] Linking CXX static library Release/libcore.ago deeper
Recall which generators are single-config (Ninja, Makefiles) and which are multi-config (Ninja Multi-Config, Visual Studio, Xcode).
Explain when the configuration is chosen in each model, what --config does, and how the build tree is laid out with per-configuration directories.
Write CMake that works under both models: no configuration tests in if(), no hard-coded output paths, and GENERATOR_IS_MULTI_CONFIG only where the difference is real.
Weigh one multi-config tree for IDE users against per-configuration single-config trees for CI, and make sure the project's CMake supports both without forks.
## Two models of a build tree A **configuration** is a named set of build settings such as `Debug` or `Release`. CMake generators fall into two groups by how many configurations one build tree holds. | | Single-config | Multi-config | |---|---|---| | Generators | `Unix Makefiles`, `Ninja`, other Makefile generators | `Ninja Multi-Config`, Visual Studio generators, `Xcode` | | Configurations per build tree | exactly one | every entry of `CMAKE_CONFIGURATION_TYPES` | | When the configuration is chosen | at configure time | at build time | | Debug plus Release | two build directories | one build directory | | `GENERATOR_IS_MULTI_CONFIG` | false | true | How the single configuration of a single-config tree is chosen, and what each configuration's flags are, belong to the material on build configurations. This lesson is about the generator side: what the tree looks like and what project code may assume. ## What a multi-config tree looks like Configuring with `-G "Ninja Multi-Config"` in CMake 4.4.4 produces: - `build-Debug.ninja`, `build-Release.ninja` and `build-RelWithDebInfo.ninja`, one per configuration; - a `build.ninja` that uses `CMAKE_DEFAULT_BUILD_TYPE`, or the first entry of `CMAKE_CONFIGURATION_TYPES` when that is unset; - per-configuration output directories, so `cmake --build build --config Release` writes `build/Release/libcore.a` while Debug output goes to `build/Debug/`. For Ninja Multi-Config the default `CMAKE_CONFIGURATION_TYPES` is `Debug;Release;RelWithDebInfo`; for the other multi-config generators the default list is generator-specific. Visual Studio puts the same idea into a solution whose configuration drop-down lists each entry, and Xcode into schemes. ## Picking the configuration at build time 1. `cmake --build build --config Release` builds the Release configuration; with Ninja Multi-Config it uses `build-Release.ninja`. 2. `cmake --build build` without `--config` uses `build.ninja` for Ninja Multi-Config, and the native tool's own default configuration for the Visual Studio and Xcode generators. 3. `ninja -f build-Debug.ninja` runs Ninja directly on one configuration's file. `cmake --install build --config Release` and `ctest --test-dir build -C Release` take the configuration in the same way, because a multi-config tree holds several sets of binaries. ## What project code must not assume While CMake runs `CMakeLists.txt`, a multi-config generator has **no current configuration**: every configuration is generated at once. Consequences: - A test like `if(CMAKE_BUILD_TYPE STREQUAL "Debug")` sees an empty or irrelevant value; multi-config generators use `CMAKE_CONFIGURATION_TYPES` and ignore `CMAKE_BUILD_TYPE`. - Paths to built files differ per configuration, so hard-coding `${CMAKE_BINARY_DIR}/libcore.a` breaks; generator expressions such as `$<TARGET_FILE:core>` and `$<CONFIG>` are evaluated per configuration at generate time. - Code that genuinely needs to branch on the generator kind reads the global property: ```cmake get_property(is_multi GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG) if(is_multi) message(STATUS "configurations: ${CMAKE_CONFIGURATION_TYPES}") endif() ``` ## Porting a single-config project A project that has only ever been built with `Ninja` often breaks the first time someone opens it with Visual Studio or Xcode. The usual repairs, in order: 1. Replace configuration tests in `if()` with generator expressions such as `$<$<CONFIG:Debug>:...>`, which the generator evaluates once per configuration. 2. Replace hard-coded output paths with target names or `$<TARGET_FILE:...>`, because outputs move into `Debug/`, `Release/` and similar subdirectories. 3. Pass the configuration to every later step: `cmake --build build --config Release`, `cmake --install build --config Release` and `ctest --test-dir build -C Release`. A multi-config tree holds several builds, and each tool needs to know which one you mean. 4. Only where the difference cannot be expressed per configuration, branch on `GENERATOR_IS_MULTI_CONFIG`, for example to set `CMAKE_CONFIGURATION_TYPES` to a narrower list. After these changes the project usually builds under both models, which is also a good test that no file assumes one active configuration. ## Choosing between the two - **Single-config Ninja or Makefiles** suit CI jobs that build one configuration per job and developers who keep `build-debug/` and `build-release/` side by side. - **Multi-config generators** suit IDE users who flip between Debug and Release without reconfiguring, and builds that need several configurations from one configure step. Ninja Multi-Config also has a cross-config mode (`CMAKE_CROSS_CONFIGS`) in which one configuration's build file can build another configuration's targets, such as `exe:Debug` from `build-Release.ninja`. A project written with targets and generator expressions works unchanged under both models; a project that branches on `CMAKE_BUILD_TYPE` in `if()` works only under one of them.
- With Ninja Multi-Config, which configuration does a plain cmake --build build use?It runs `build.ninja`, which uses `CMAKE_DEFAULT_BUILD_TYPE` if it is set and otherwise the first entry of `CMAKE_CONFIGURATION_TYPES`, which is `Debug` with the default list `Debug;Release;RelWithDebInfo`. Passing `--config Release` makes `cmake --build` use `build-Release.ninja` instead.
- Why does a custom command that hard-codes ${CMAKE_BINARY_DIR}/tool break under a Visual Studio generator?Multi-config generators put each configuration's outputs in their own subdirectory, so the executable is at `Debug/tool.exe` or `Release/tool.exe` under the target's binary directory, never at the bare path. Naming the target as the command, or using `$<TARGET_FILE:tool>`, lets CMake resolve the path per configuration at generate time.
- A Ninja Multi-Config build compiles every configuration each time by default
- A Visual Studio build directory holds only the configuration chosen at configure time
- if(CMAKE_BUILD_TYPE STREQUAL Debug) works the same under every generator
- Multi-config generators put Debug and Release binaries in the same directory
- You need a separate build directory per configuration even with Xcode