CMake Generator Expressions: Platform‑Specific Flags Made Simple

Problem: Platform‑Specific Compile Options

When a project targets multiple operating systems, architectures, or build configurations, you often need to tweak compiler flags, link directories, or preprocessor definitions. Traditional CMake code uses if() blocks to branch on $ or $, which quickly becomes cluttered and hard to maintain:

if(CMAKE_BUILD_TYPE STREQUAL "Debug")
  target_compile_options(myapp PRIVATE -g)
elseif(CMAKE_BUILD_TYPE STREQUAL "Release")
  target_compile_options(myapp PRIVATE -O3)
endif()

Adding more conditions for Windows, Linux, or different toolchains multiplies the lines of code and increases the chance for copy‑and‑paste errors.

Thesis: Generator Expressions Keep Build Logic Declarative

CMake’s generator expressions (GE) allow you to embed build‑time logic directly in the language syntax. They are evaluated by CMake’s generator, not the compiler, so the final build system receives a concrete value. This eliminates runtime checks, keeps the build fast, and keeps your CMakeLists.txt tidy.

1. Using the Syntax

A generator expression starts with $< and ends with >. Inside you can use predicates like CONFIG:Debug, PLATFORM_ID:Windows, or TARGET_PROPERTY:TYPE,SHARED to return a string if the condition is true, otherwise an empty string. The string is then concatenated into the surrounding value.

• $<:-g> expands to -g only when the build type is Debug.
• $<:-DLINUX> adds a definition on Linux.
• $<:-fPIC> applies -fPIC only to shared libraries.

Because GE are part of the language, you can use them anywhere a string is accepted: target_compile_options, target_link_libraries, set(... CACHE), and even in add_custom_command arguments.

2. Practical Example

Below is a minimal CMakeLists.txt that demonstrates platform‑specific flags for a library called mylib. The example works on any generator (Make, Ninja, Visual Studio) and CMake 3.10+.

# CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(MyLib LANGUAGES CXX)

add_library(mylib src/foo.cpp src/bar.cpp)

# Compile options that differ by configuration
# Debug: enable debug symbols
# Release: enable high‑level optimizations
target_compile_options(mylib
  PRIVATE
    $<:-g>
    $<:-O3>
)

# Platform‑specific preprocessor definitions
# Linux: define _LINUX
# Windows: define _WIN32
target_compile_definitions(mylib
  PRIVATE
    $<:_LINUX>
    $<:_WIN32>
)

# Link library only on macOS
# For example, link with pthread on macOS but not on Linux
target_link_libraries(mylib
  PRIVATE
    $<:-lpthread>
)

To build and inspect the flags:

1. cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug – generates the build system for Debug.
2. cmake -S . -B build -DCMAKE_BUILD_TYPE=Release – regenerates for Release.
3. Open build/CMakeFiles/mylib.dir/build.make (Make) or build/mylib.ninja (Ninja) to see the concrete compiler options. You should see -g in Debug and -O3 in Release.
4. Run cmake --build build --config Debug to compile the library.

3. Trade‑offs and Limitations

• Readability for Newcomers: GE can look cryptic. Adding a comment or a small helper function (e.g., set_debug_flags()) improves clarity.
• Configuration vs. Generation: GE are evaluated during the generation step. If you change a variable after the first cmake run, you must re‑run CMake to update the expressions.
• Generator Support: Some expressions (like $<LINK_OPTIONS>) are only supported by certain generators, e.g., Visual Studio 2019+. Check the cmake --help-policy output for generator‑specific features.
• Silent Failures: A typo inside an expression causes CMake to treat the entire expression as a literal string, which may silently drop a flag. Running cmake --dump-variables or inspecting the generated build files helps catch this.

4. Actionable Next Steps

1. Identify the compile options or definitions that vary across configurations or platforms.
2. Replace if() blocks with generator expressions using the $<...> syntax.
3. Test the build for each configuration by inspecting the generated build files (e.g., build.ninja or build/Makefile).
4. Add comments or helper functions for complex expressions to keep the CMakeLists.txt readable.

By moving conditional logic into the language, you keep your build scripts concise, portable, and less error‑prone.