In CMake, what is a generator expression such as $<CONFIG>, and why does message() print it unevaluated?
answer
- configure, then generate
- dollar sign and angle brackets
- one value per configuration
- write it to a file instead
basics
~20 sA generator expression is a $<...> placeholder that CMake evaluates while generating the build system, separately for each configuration and target. message() runs earlier, while CMakeLists.txt is read, so it prints the raw text; file(GENERATE) shows real values.
solid answer
~40 sCMake works in two phases. The **configure** phase runs `CMakeLists.txt` top to bottom: variables, `if()`, `message()`. The **generate** phase then writes the native build files for each configuration, and that is when **generator expressions** are evaluated. Their forms are `$<NAME>` (a value such as `$<CONFIG>`), `$<NAME:arg>` (a test or query such as `$<CXX_COMPILER_ID:GNU>` or `$<TARGET_FILE:imgproc>`), `$<condition:text>` and `$<IF:condition,a,b>`, and they nest. During configure they are plain strings, so `message("$<CONFIG>")` prints `$<CONFIG>`. To see what one evaluates to, write it out with `file(GENERATE OUTPUT ... CONTENT ...)`, putting `$<CONFIG>` in the file name under a multi-config generator and adding `TARGET` for expressions that need a target, or echo it from a custom target.
code
cmake · 7 linesadd_library(imgproc STATIC blur.cpp)
message(STATUS "message shows: $<CONFIG> and $<CXX_COMPILER_ID>")
file(GENERATE OUTPUT "${CMAKE_BINARY_DIR}/genex-$<CONFIG>.txt"
CONTENT "config=$<CONFIG> id=$<CXX_COMPILER_ID> file=$<TARGET_FILE:imgproc>\n"
TARGET imgproc)go deeper
Recall the $<...> form, that it is evaluated at generate time rather than configure time, and that message() therefore shows it unexpanded.
Explain the configure and generate phases, the conditional forms with 1 and 0, nesting, and how file(GENERATE) or a custom target reveals the evaluated value.
Debug a wrong per-configuration or per-compiler setting by dumping the expression per configuration, and replace hard-coded build paths with target queries.
Keep generator expressions small and named through variables, because unreadable nested expressions become build logic nobody on the team can safely change.
## Two phases, two kinds of logic Running `cmake -S . -B build` does two separate things: 1. **Configure.** CMake executes the `CMakeLists.txt` files as a script: it sets variables, evaluates `if()`, calls functions, creates targets and records their properties. `message()` prints during this phase. 2. **Generate.** With every target and property known, CMake writes the native build system (Ninja files, Makefiles, a Visual Studio solution). For multi-configuration generators it writes rules for every configuration at once. A **generator expression** is a piece of text of the form `$<...>` that CMake stores during configure and evaluates only during generate, once for each context it is used in: each configuration, each target, each language. That is why it can depend on things the configure-time script cannot know for sure, such as which configuration a rule is for. ## The syntax | Form | Meaning | Example | |---|---|---| | `$<NAME>` | a value | `$<CONFIG>` gives `Debug`, `Release`, ... | | `$<NAME:args>` | a query or a test that yields `1` or `0` | `$<CXX_COMPILER_ID:GNU,Clang>` | | `$<condition:text>` | `text` if the condition is `1`, empty if `0` | `$<$<CONFIG:Debug>:IMGPROC_CHECKS>` | | `$<IF:condition,a,b>` | `a` or `b` | `$<IF:$<CONFIG:Debug>,dbg,opt>` | Key rules: - A condition must evaluate to exactly `1` or `0`; any other value is an error. `$<BOOL:...>` converts CMake's usual true and false strings into `1` and `0`. - Expressions nest, and the inner ones are evaluated first. - They work only where a command or property says it supports them, such as `target_compile_definitions`, `target_include_directories`, `target_link_libraries`, `add_custom_command`, `file(GENERATE)` and many `INTERFACE_*` properties. Elsewhere they stay literal text. - Arguments containing spaces or semicolons should be quoted so the expression is not split. ## Why message() cannot show the value `message()` executes during configure; the expression has not been evaluated yet, and with a multi-config generator it does not even have *one* value. So: ```cmake message(STATUS "message shows: $<CONFIG> and $<CXX_COMPILER_ID>") ``` prints exactly `-- message shows: $<CONFIG> and $<CXX_COMPILER_ID>`. ## Debugging generator expressions The CMake manual describes two techniques: - **`file(GENERATE)`** writes a file during the generate phase with the expressions evaluated. Under a multi-config generator, put `$<CONFIG>` in the output name, because writing one file with different content per configuration is an error. Expressions that need a target, such as `$<CXX_COMPILER_ID>`, need the `TARGET <name>` option (added in CMake 3.19); without it, CMake 4.4.4 reports that `$<CXX_COMPILER_ID>` may only be used with binary targets. - **A debug custom target**: `add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")`, then `cmake --build build --target genexdebug` prints the evaluated value. Here is what one `file(GENERATE)` call produced under Ninja Multi-Config with Apple clang, trimmed to a few of its fields: ```plaintext config=Debug id=AppleClang clang=0 clangs=1 if=dbg file=<build>/Debug/libimgproc.a config=Release id=AppleClang clang=0 clangs=1 if=opt file=<build>/Release/libimgproc.a config=RelWithDebInfo id=AppleClang clang=0 clangs=1 if=opt file=<build>/RelWithDebInfo/libimgproc.a ``` One file per configuration, each with its own answers, which is exactly what `message()` could not show. ## $<TARGET_FILE> and friends Target queries return facts that exist only after generation decides them: - `$<TARGET_FILE:imgproc>` is the full path of the built binary, including the configuration directory under a multi-config generator. - Used inside `add_custom_command` or `add_custom_target`, it also makes the command depend on `imgproc`, so the tool runs after the library is built. - `$<TARGET_FILE_NAME:...>` and `$<TARGET_FILE_DIR:...>` return the parts of that path. Hard-coding `${CMAKE_BINARY_DIR}/libimgproc.a` instead breaks as soon as the generator, platform prefix or configuration directory differs. ## Mistakes that look like CMake bugs - **Expecting configure-time commands to expand them.** `set()`, `if()`, `message()`, `file(WRITE)` and `configure_file()` all run before generation and see the literal `$<...>` text. - **Using them where they are not supported.** A property that does not document generator-expression support keeps the text verbatim, and the compiler or tool later receives a string starting with `$<`. - **Feeding a CMake boolean straight into a condition.** With `option(IMGPROC_SIMD ... ON)`, the expression `$<${IMGPROC_SIMD}:IMGPROC_USE_SIMD>` becomes `$<ON:IMGPROC_USE_SIMD>`, and CMake 4.4.4 stops with "Expression did not evaluate to a known generator expression". Wrap the value: `$<$<BOOL:${IMGPROC_SIMD}>:IMGPROC_USE_SIMD>`, or decide it with a plain `if()`, since an option does not vary per configuration.
- Why does file(GENERATE) fail under a multi-config generator when the output name has no $<CONFIG>?Because it is evaluated once per configuration, and the contents differ when they contain `$<CONFIG>` or another configuration-dependent expression. CMake allows several configurations to write the same file only if the content is identical, so the output name must be unique per configuration, typically by including `$<CONFIG>`.
- When would you choose $<TARGET_FILE:tool> over a hard-coded path in add_custom_command?Always, when the command runs a binary the project builds. `$<TARGET_FILE:tool>` resolves the real path for each generator, platform naming convention and configuration directory, and inside `add_custom_command` it also adds a dependency on `tool`, so the command runs only after `tool` is built.
- Generator expressions are evaluated while CMakeLists.txt is executed
- message() is the way to debug a generator expression
- Every CMake command and property expands generator expressions
- A condition may be any truthy string such as ON or YES