skip to content

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%

answer

  1. read the real compile line
  2. empty type on single-config
  3. multi-config ignores the variable
  4. --config at build time
  5. per-config flags, not global ones

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.

solid answer

~40 s

First look at what actually ran: `cmake --build build -v`, or the `compile_commands.json` that `CMAKE_EXPORT_COMPILE_COMMANDS` writes for Makefile and Ninja generators. If the lines lack `-O3 -DNDEBUG`, find which of two causes applies. With **Ninja or Makefiles**, `CMAKE_BUILD_TYPE` was empty (check `CMakeCache.txt`), so no configuration flags were added; fix it with `-DCMAKE_BUILD_TYPE=Release` on a fresh configure. With **Visual Studio, Xcode or Ninja Multi-Config**, `-DCMAKE_BUILD_TYPE=Release` is ignored (CMake warns that it was not used) and `cmake --build build` without `--config` builds the default configuration, typically Debug; fix it with `cmake --build build --config Release` and the same `--config` for install and `ctest -C`. Then make the type impossible to forget: a project default only when none is given, or a preset per configuration.

code

console · 9 lines
console
$ cmake -S . -B build -G "Ninja Multi-Config" -DCMAKE_BUILD_TYPE=Release
CMake Warning (unused-cli):
  Manually-specified variables were not used by the project:

    CMAKE_BUILD_TYPE

$ cmake --build build -v
[2/8] /usr/bin/c++ -DCMAKE_INTDIR=\"Debug\"  -g -std=gnu++20 -arch arm64 ... -c core.cpp
$ cmake --build build --config Release

go deeper

for a junior

Know that release builds need -DCMAKE_BUILD_TYPE=Release for Ninja or Makefiles and --config Release for Visual Studio.

for a middle

Explain why an empty build type adds no flags and why multi-config generators ignore CMAKE_BUILD_TYPE, warning that it was unused.

for a senior

Diagnose from compile lines and the cache which cause applies, fix it at the right step, and add a guarded default or CI check so it cannot recur.

for a principal

Make configuration choice part of the team's build contract, through presets or CI templates, so no release artifact depends on someone remembering a flag.

## Symptoms A profiling run of the shipped binary shows tiny accessor functions as separate calls in the hot loop, and an `assert` fires in production. Both symptoms point the same way: the code was compiled without the Release flags. The standard Release flags for GCC and Clang, `-O3 -DNDEBUG`, would both optimize and turn `assert` into nothing. ## Step 1: read what actually ran Do not trust a directory name such as `build-release/`. Look at the commands: - `cmake --build build -v` prints every compile and link line. - `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` makes Makefile and Ninja generators write `build/compile_commands.json` with one entry per source file. - `grep CMAKE_BUILD_TYPE build/CMakeCache.txt` shows what the tree was configured with. In a CMake 4.4.4 Ninja build with no build type, Apple clang received `-std=gnu++20 -arch arm64` and nothing else: no `-O`, no `-g`, no `-DNDEBUG`. ## Step 2: identify the cause | Generator | What went wrong | Evidence | |---|---|---| | `Ninja`, `Unix Makefiles` | `CMAKE_BUILD_TYPE` never set, so its toolchain-specific default (empty for GCC and Clang on Linux and macOS) applied | `CMAKE_BUILD_TYPE:STRING=` in the cache | | `Ninja Multi-Config`, Visual Studio, Xcode | `-DCMAKE_BUILD_TYPE=Release` passed, but these generators ignore it; the build step had no `--config` | configure prints `CMake Warning (unused-cli)` listing `CMAKE_BUILD_TYPE` among manually-specified variables not used; outputs under `Debug/` | The second case is easy to miss in CI logs. In a CMake 4.4.4 run, configuring with `-G "Ninja Multi-Config" -DCMAKE_BUILD_TYPE=Release` printed that warning, and the following `cmake --build build` compiled with `-DCMAKE_INTDIR="Debug" -g`, because `build.ninja` uses the first entry of `CMAKE_CONFIGURATION_TYPES`, which is `Debug` by default. ## Step 3: fix the build 1. **Single-config:** reconfigure with `-DCMAKE_BUILD_TYPE=Release` (or `--fresh` if other cached values are suspect), then rebuild. 2. **Multi-config:** keep the generator and pass the configuration at every later step: `cmake --build build --config Release`, `cmake --install build --config Release`, `ctest --test-dir build -C Release`. 3. **Both:** never set `CMAKE_CXX_FLAGS` to `-O2` by hand to compensate. It applies to every configuration and hides the real problem. ## Why the two causes look alike Both failures leave a binary that runs, passes most tests and is merely slow, and neither stops the build. The single-config case is silent: an empty build type is a legal value and CMake prints nothing about it. The multi-config case prints one warning during configure that CI logs easily bury, and the output then lands under `Debug/` while a packaging script may be copying from a hard-coded path that happens to hold an older binary. Two cheap habits catch both: - Print the active configuration in the build log, for example with a custom target that runs `cmake -E echo "$<CONFIG>"`. - Make the packaging step take its input from `cmake --install build --config Release --prefix stage`, not from a guessed path inside the build tree. ## Step 4: make it hard to repeat A project can choose a default for single-config generators only when the user gave none: ```cmake get_property(is_multi GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG) if(NOT is_multi AND NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE) endif() ``` This runs after `project()`, where an empty cached value already exists, hence `FORCE`; the guard keeps an explicit `-DCMAKE_BUILD_TYPE=Debug` intact. Alternatives are the `CMAKE_BUILD_TYPE` environment variable (CMake 3.22+) on build machines, and configure and build presets that name the configuration, which the material on presets covers. ## Per-configuration flags done properly When the fix tempts someone to add release-only flags, put them where CMake can tell configurations apart: - `target_compile_options(app PRIVATE $<$<CONFIG:Release>:-fno-plt>)` adds a flag to one target in one configuration and works under every generator. - Cache variables such as `CMAKE_CXX_FLAGS_RELEASE` change a configuration for the whole build tree; set them with `-D` or in a toolchain file through `CMAKE_CXX_FLAGS_RELEASE_INIT`, not with a plain `set()` that the cache would shadow on the next run. - `if(CMAKE_BUILD_TYPE STREQUAL "Release")` is wrong for multi-config generators, which never set a current configuration while CMake runs. What each optimization flag does to the generated code belongs to the material on GCC optimization levels; the mechanics of `$<CONFIG>` belong to the material on generator expressions.

  • Why does the default-build-type snippet need CACHE ... FORCE instead of a plain set(CMAKE_BUILD_TYPE Release)?
    `project()` already created `CMAKE_BUILD_TYPE` as an empty cache entry. A plain `set()` inside the guard does change the build, but only as a normal variable: in a CMake 4.4.4 run it compiled with `-O3 -DNDEBUG` while `CMakeCache.txt` still said `CMAKE_BUILD_TYPE:STRING=`, so `ccmake`, `cmake-gui` and IDEs report no build type. `FORCE` records the default in the cache, and the guard keeps an explicit choice intact.
  • How can CI catch an unoptimized release build before it ships?
    Configure with `CMAKE_EXPORT_COMPILE_COMMANDS=ON` and check that the release job's `compile_commands.json` contains the expected optimization flags and `-DNDEBUG`, or grep `cmake --build -v` output. For multi-config generators, fail the job if `--config` is missing, and fail the job when configure prints the unused-cli warning naming `CMAKE_BUILD_TYPE`.

  • Passing -DCMAKE_BUILD_TYPE=Release makes a Visual Studio build produce Release binaries
  • A directory named build-release must contain an optimized build
  • Adding -O2 to CMAKE_CXX_FLAGS is the right fix for a missing build type
  • if(CMAKE_BUILD_TYPE STREQUAL Release) is a reliable way to add release-only flags
  • Without --config, a multi-config build defaults to Release