skip to content

Debug and Release Configs

CMAKE_BUILD_TYPE picks Debug or Release in single-config generators, while multi-config ones choose at build time. Interviewers ask how to set the C++ standard and per-config flags properly.

on this pageshow

explore

questions

4

In CMake, what do the Debug, Release, RelWithDebInfo and MinSizeRel build types change, and how does CMAKE_BUILD_TYPE select one?

level: juniorimportance: must knowfreq 70%

answer

  1. four standard configurations
  2. CMAKE_CXX_FLAGS_<CONFIG>
  3. NDEBUG in the release types
  4. empty is not Debug
  5. set once, at configure

basics

~20 s

Each build type adds its own flags from CMAKE_CXX_FLAGS_<CONFIG>: with GCC or Clang, Debug adds -g, Release -O3 -DNDEBUG, RelWithDebInfo -O2 -g -DNDEBUG, MinSizeRel -Os -DNDEBUG. Single-config generators take the type from CMAKE_BUILD_TYPE at configure time; left empty, none of these flags apply.

solid answer

~40 s

CMake defines four standard **configurations**, and each one owns a flag variable `CMAKE_CXX_FLAGS_<CONFIG>` (upper-case name) that is added on top of `CMAKE_CXX_FLAGS`. With GCC and Clang the defaults are `-g` for `Debug`, `-O3 -DNDEBUG` for `Release`, `-O2 -g -DNDEBUG` for `RelWithDebInfo` and `-Os -DNDEBUG` for `MinSizeRel`, so the release types also switch `assert` off. With a single-config generator such as Ninja or Makefiles you pick the type once, at configure time: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release`. If nobody sets it, it takes a toolchain-specific default, which is empty with GCC and Clang on Linux and macOS, and an empty build type is **not** Debug: it adds no configuration flags at all. Multi-config generators ignore `CMAKE_BUILD_TYPE` and choose at build time with `--config`.

code

cmake · 7 lines
cmake
cmake_minimum_required(VERSION 3.25)
project(render CXX)
message(STATUS "BT=[${CMAKE_BUILD_TYPE}]")
foreach(c DEBUG RELEASE RELWITHDEBINFO MINSIZEREL)
  message(STATUS "${c}: [${CMAKE_CXX_FLAGS_${c}}]")
endforeach()
add_executable(render main.cpp)

go deeper

for a junior

Name the four build types, pass -DCMAKE_BUILD_TYPE=Release when configuring, and know that the release types define NDEBUG.

for a middle

Explain the CMAKE_CXX_FLAGS_<CONFIG> variables, the toolchain-specific default, and why an empty build type produces neither an optimized nor a debuggable binary.

for a senior

Make the build type explicit in every script and preset, and read the real compile lines rather than trusting the name of a directory.

for a principal

Decide which configurations a team ships and tests, including any custom ones, and keep their flags defined in one place.

## What a build type is A **build type**, which CMake also calls a **configuration**, is a named set of compiler and linker flags. CMake ships four standard ones: - `Debug`: debug information, no optimization flags. - `Release`: full optimization and assertions disabled. - `RelWithDebInfo`: optimized but still debuggable. - `MinSizeRel`: optimized for size. Projects can define more, such as `Profile` or `Asan`; each configuration then needs its own flag variables. ## The flags behind each type Every configuration has a variable named `CMAKE_<LANG>_FLAGS_<CONFIG>`, where `<CONFIG>` is the configuration name in upper case. For C++ these are cache variables such as `CMAKE_CXX_FLAGS_RELEASE`, initialised from the compiler's defaults when a build tree is created. A CMake 4.4.4 configure with Apple clang, whose defaults come from CMake's GNU-family compiler module, printed: | Configuration | `CMAKE_CXX_FLAGS_<CONFIG>` with GCC or Clang | |---|---| | `Debug` | `-g` | | `Release` | `-O3 -DNDEBUG` | | `RelWithDebInfo` | `-O2 -g -DNDEBUG` | | `MinSizeRel` | `-Os -DNDEBUG` | The compile line is `CMAKE_CXX_FLAGS`, then the flags of the active configuration, then the target's own options. `-DNDEBUG` matters as much as the optimization level: it defines the `NDEBUG` macro, which makes the standard `assert` macro expand to nothing, so a release type never evaluates assertions. Other compilers get their own values, for example MSVC's `/O2` style flags. What each optimization level does to the code belongs to the material on GCC optimization levels. ## Selecting a type with a single-config generator With `Unix Makefiles` or `Ninja`, one build tree holds one configuration: ```console cmake -S . -B build-release -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build build-release ``` 1. `-DCMAKE_BUILD_TYPE=Release` stores the type in the cache when the tree is configured. 2. The `CMAKE_BUILD_TYPE` environment variable (CMake 3.22+) supplies a default only when a new tree is created without an explicit type. 3. Otherwise a **toolchain-specific default** applies: empty with GCC and Clang on Linux and macOS, `Debug` with MSVC and clang-cl on Windows, whose platform modules set `CMAKE_BUILD_TYPE_INIT` to `Debug`, and `RelWithDebInfo` for Android NDK builds. To get both Debug and Release with a single-config generator you configure two directories, such as `build-debug/` and `build-release/`. ## The empty build type The CMake build-system manual warns that an empty `CMAKE_BUILD_TYPE` is commonly mistaken for `Debug`, and it is not. With an empty type the compile line carries only `CMAKE_CXX_FLAGS` and the target's options. A Ninja build of a library with no build type and Apple clang compiled with `-std=gnu++20 -arch arm64` and nothing else: no `-O`, no `-g`, no `-DNDEBUG`. The result is unoptimized code with assertions still active, and no debug information either. Always pass a build type explicitly. ## Multi-config generators choose later Visual Studio, Xcode and `Ninja Multi-Config` generate every configuration listed in `CMAKE_CONFIGURATION_TYPES` and ignore `CMAKE_BUILD_TYPE`; you pick one with `cmake --build build --config Release` or in the IDE. Code that reads `CMAKE_BUILD_TYPE` in `if()` therefore only works for single-config generators; per-configuration settings are written with `$<CONFIG:...>` generator expressions instead. ## Inspecting and overriding the flags Because the per-configuration flags are ordinary cache variables, you can see and change them without touching the project: - `cmake -LA -N build` lists the cached variables, advanced ones included, and shows `CMAKE_CXX_FLAGS_RELEASE` with its current value; `CMakeCache.txt` holds the same. - `-DCMAKE_CXX_FLAGS_RELEASE="-O2 -DNDEBUG"` on the first configure replaces the default for that build tree, which some teams use to ship `-O2` instead of `-O3`. - A toolchain file can seed the defaults through `CMAKE_CXX_FLAGS_RELEASE_INIT` and its siblings, which initialise the cache entry the first time a tree is configured; CMake may prepend or append its own content. - `cmake --build build -v` prints the compile lines, which is the only reliable proof of which flags a configuration really used. Editing these variables with `set()` inside `CMakeLists.txt` is a common mistake: a normal variable shadows the cache entry from that directory down, so the value users see in the cache no longer matches the build. Per-target, per-configuration options belong in `target_compile_options` with a `$<CONFIG:...>` condition instead. ## Case and comparisons Configuration names are case-insensitive where CMake uses them internally, so `$<CONFIG:Debug>` also matches `DEBUG`. Plain string comparisons in `if()` are case-sensitive, and `if(CMAKE_BUILD_TYPE STREQUAL DEBUG)` is false for `Debug`. The flag variables always use the upper-case name: `CMAKE_CXX_FLAGS_RELWITHDEBINFO`, never `CMAKE_CXX_FLAGS_RelWithDebInfo`.

  • Why do release binaries from CMake ignore assert() calls even though nobody wrote -DNDEBUG?
    The default `CMAKE_CXX_FLAGS_RELEASE`, `CMAKE_CXX_FLAGS_RELWITHDEBINFO` and `CMAKE_CXX_FLAGS_MINSIZEREL` for GCC and Clang contain `-DNDEBUG`, and the standard `assert` macro expands to nothing when `NDEBUG` is defined. Only `Debug`, and an empty build type, leave assertions active. A project that wants checks in release builds needs its own check macro rather than `assert`.
  • How do you add a custom Profile build type to a single-config CMake build?
    Pass `-DCMAKE_BUILD_TYPE=Profile` and define the matching flag variables, typically as cache entries: `CMAKE_CXX_FLAGS_PROFILE`, and the linker variables such as `CMAKE_EXE_LINKER_FLAGS_PROFILE` if needed. Without them the configuration exists but adds no flags. For multi-config generators, also add `Profile` to `CMAKE_CONFIGURATION_TYPES`.

  • An empty CMAKE_BUILD_TYPE means CMake builds Debug
  • RelWithDebInfo uses the same flags as Release plus -g
  • Release builds keep assert() checks because NDEBUG must be defined by hand
  • You switch a Ninja build directory from Debug to Release with cmake --build --config Release
  • The flag variable for RelWithDebInfo is CMAKE_CXX_FLAGS_RelWithDebInfo
open as a page

In CMake, how do CMAKE_CXX_STANDARD, CMAKE_CXX_STANDARD_REQUIRED and target_compile_features differ when a project needs C++20?

level: middleimportance: must knowfreq 65%

basics

~20 s

CMAKE_CXX_STANDARD sets the default CXX_STANDARD of targets created afterwards; without CMAKE_CXX_STANDARD_REQUIRED it may decay to an older standard. target_compile_features(lib PUBLIC cxx_std_20) is a per-target minimum that also propagates to consumers and fails if the compiler cannot meet it.

open as a page

A CMake project's shipped release binary turns out unoptimized and still runs its assert() checks; how do you find whether the build type or the generator caused it, and fix it?

level: seniorimportance: should knowfreq 52%

basics

~20 s

Check the compile lines with cmake --build -v: no -O and no -DNDEBUG means no Release flags were used. Either CMAKE_BUILD_TYPE was never set on a single-config generator, or a multi-config generator ignored it and cmake --build without --config built Debug.

open as a page

In CMake, how do you enable interprocedural optimization only for a target's Release configuration, and why call check_ipo_supported first?

level: seniorimportance: nice to knowfreq 32%

basics

~20 s

Include CheckIPOSupported, call check_ipo_supported(RESULT ok), and if ok set the INTERPROCEDURAL_OPTIMIZATION_RELEASE property on the target. Since policy CMP0069, enabling IPO on a compiler CMake has no IPO flags for is an error, so the check keeps unsupported toolchains building.

open as a page