cmake-generator-expressions(7)¶
Contents
Introduction¶
Generator expressions are evaluated during build system generation to produce information specific to each build configuration.
Generator expressions are allowed in the context of many target properties,
such as LINK_LIBRARIES, INCLUDE_DIRECTORIES,
COMPILE_DEFINITIONS and others. They may also be used when using
commands to populate those properties, such as target_link_libraries(),
target_include_directories(), target_compile_definitions()
and others.
They enable conditional linking, conditional definitions used when compiling, conditional include directories, and more. The conditions may be based on the build configuration, target properties, platform information or any other queryable information.
Generator expressions have the form $<...>. To avoid confusion, this page
deviates from most of the CMake documentation in that it omits angular brackets
<...> around placeholders like condition, string, target,
among others.
Generator expressions can be nested, as shown in most of the examples below.
Boolean Generator Expressions¶
Boolean expressions evaluate to either 0 or 1.
They are typically used to construct the condition in a conditional
generator expression.
Available boolean expressions are:
Logical Operators¶
$<BOOL:string>Converts
stringto0or1. Evaluates to0if any of the following is true:stringis empty,stringis a case-insensitive equal of0,FALSE,OFF,N,NO,IGNORE, orNOTFOUND, orstringends in the suffix-NOTFOUND(case-sensitive).
Otherwise evaluates to
1.$<AND:conditions>- where
conditionsis a comma-separated list of boolean expressions. Evaluates to1if all conditions are1. Otherwise evaluates to0. $<OR:conditions>- where
conditionsis a comma-separated list of boolean expressions. Evaluates to1if at least one of the conditions is1. Otherwise evaluates to0. $<NOT:condition>0ifconditionis1, else1.
String Comparisons¶
$<STREQUAL:string1,string2>1ifstring1andstring2are equal, else0. The comparison is case-sensitive. For a case-insensitive comparison, combine with a string transforming generator expression,$<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...
$<EQUAL:value1,value2>1ifvalue1andvalue2are numerically equal, else0.$<IN_LIST:string,list>1ifstringis member of the semicolon-separatedlist, else0. Uses case-sensitive comparisons.$<VERSION_LESS:v1,v2>1ifv1is a version less thanv2, else0.$<VERSION_GREATER:v1,v2>1ifv1is a version greater thanv2, else0.$<VERSION_EQUAL:v1,v2>1ifv1is the same version asv2, else0.$<VERSION_LESS_EQUAL:v1,v2>1ifv1is a version less than or equal tov2, else0.$<VERSION_GREATER_EQUAL:v1,v2>1ifv1is a version greater than or equal tov2, else0.
Variable Queries¶
$<TARGET_EXISTS:target>1iftargetexists, else0.$<CONFIG:cfg>1if config iscfg, else0. This is a case-insensitive comparison. The mapping inMAP_IMPORTED_CONFIG_<CONFIG>is also considered by this expression when it is evaluated on a property on anIMPORTEDtarget.$<PLATFORM_ID:platform_ids>- where
platform_idsis a comma-separated list.1if the CMake’s platform id matches any one of the entries inplatform_ids, otherwise0. See also theCMAKE_SYSTEM_NAMEvariable. $<C_COMPILER_ID:compiler_ids>- where
compiler_idsis a comma-separated list.1if the CMake’s compiler id of the C compiler matches any one of the entries incompiler_ids, otherwise0. See also theCMAKE_<LANG>_COMPILER_IDvariable. $<CXX_COMPILER_ID:compiler_ids>- where
compiler_idsis a comma-separated list.1if the CMake’s compiler id of the CXX compiler matches any one of the entries incompiler_ids, otherwise0. See also theCMAKE_<LANG>_COMPILER_IDvariable. $<CUDA_COMPILER_ID:compiler_ids>- where
compiler_idsis a comma-separated list.1if the CMake’s compiler id of the CUDA compiler matches any one of the entries incompiler_ids, otherwise0. See also theCMAKE_<LANG>_COMPILER_IDvariable. $<OBJC_COMPILER_ID:compiler_ids>- where
compiler_idsis a comma-separated list.1if the CMake’s compiler id of the Objective-C compiler matches any one of the entries incompiler_ids, otherwise0. See also theCMAKE_<LANG>_COMPILER_IDvariable. $<OBJCXX_COMPILER_ID:compiler_ids>- where
compiler_idsis a comma-separated list.1if the CMake’s compiler id of the Objective-C++ compiler matches any one of the entries incompiler_ids, otherwise0. See also theCMAKE_<LANG>_COMPILER_IDvariable. $<Fortran_COMPILER_ID:compiler_ids>- where
compiler_idsis a comma-separated list.1if the CMake’s compiler id of the Fortran compiler matches any one of the entries incompiler_ids, otherwise0. See also theCMAKE_<LANG>_COMPILER_IDvariable. $<C_COMPILER_VERSION:version>1if the version of the C compiler matchesversion, otherwise0. See also theCMAKE_<LANG>_COMPILER_VERSIONvariable.$<CXX_COMPILER_VERSION:version>1if the version of the CXX compiler matchesversion, otherwise0. See also theCMAKE_<LANG>_COMPILER_VERSIONvariable.$<CUDA_COMPILER_VERSION:version>1if the version of the CXX compiler matchesversion, otherwise0. See also theCMAKE_<LANG>_COMPILER_VERSIONvariable.$<OBJC_COMPILER_VERSION:version>1if the version of the OBJC compiler matchesversion, otherwise0. See also theCMAKE_<LANG>_COMPILER_VERSIONvariable.$<OBJCXX_COMPILER_VERSION:version>1if the version of the OBJCXX compiler matchesversion, otherwise0. See also theCMAKE_<LANG>_COMPILER_VERSIONvariable.$<Fortran_COMPILER_VERSION:version>1if the version of the Fortran compiler matchesversion, otherwise0. See also theCMAKE_<LANG>_COMPILER_VERSIONvariable.$<TARGET_POLICY:policy>1if thepolicywas NEW when the ‘head’ target was created, else0. If thepolicywas not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.$<COMPILE_FEATURES:features>- where
featuresis a comma-spearated list. Evaluates to1if all of thefeaturesare available for the ‘head’ target, and0otherwise. If this expression is used while evaluating the link implementation of a target and if any dependency transitively increases the requiredC_STANDARDorCXX_STANDARDfor the ‘head’ target, an error is reported. See thecmake-compile-features(7)manual for information on compile features and a list of supported compilers.
$<COMPILE_LANG_AND_ID:language,compiler_ids>1when the language used for compilation unit matcheslanguageand the CMake’s compiler id of the language compiler matches any one of the entries incompiler_ids, otherwise0. This expression is a short form for the combination of$<COMPILE_LANGUAGE:language>and$<LANG_COMPILER_ID:compiler_ids>. This expression may be used to specify compile options, compile definitions, and include directories for source files of a particular language and compiler combination in a target. For example:add_executable(myapp main.cpp foo.c bar.cpp zot.cu) target_compile_definitions(myapp PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> )
This specifies the use of different compile definitions based on both the compiler id and compilation language. This example will have a
COMPILING_CXX_WITH_CLANGcompile definition when Clang is the CXX compiler, andCOMPILING_CXX_WITH_INTELwhen Intel is the CXX compiler. Likewise when the C compiler is Clang it will only see theCOMPILING_C_WITH_CLANGdefinition.Without the
COMPILE_LANG_AND_IDgenerator expression the same logic would be expressed as:target_compile_definitions(myapp PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> )
$<COMPILE_LANGUAGE:languages>1when the language used for compilation unit matches any of the entries inlanguages, otherwise0. This expression may be used to specify compile options, compile definitions, and include directories for source files of a particular language in a target. For example:add_executable(myapp main.cpp foo.c bar.cpp zot.cu) target_compile_options(myapp PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> ) target_compile_definitions(myapp PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA> ) target_include_directories(myapp PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers> )
This specifies the use of the
-fno-exceptionscompile option,COMPILING_CXXcompile definition, andcxx_headersinclude directory for C++ only (compiler id checks elided). It also specifies aCOMPILING_CUDAcompile definition for CUDA.Note that with Visual Studio Generators and
Xcodethere is no way to represent target-wide compile definitions or include directories separately forCandCXXlanguages. Also, with Visual Studio Generators there is no way to represent target-wide flags separately forCandCXXlanguages. Under these generators, expressions for both C and C++ sources will be evaluated usingCXXif there are any C++ sources and otherwise usingC. A workaround is to create separate libraries for each source file language instead:add_library(myapp_c foo.c) add_library(myapp_cxx bar.cpp) target_compile_options(myapp_cxx PUBLIC -fno-exceptions) add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx)
String-Valued Generator Expressions¶
These expressions expand to some string. For example,
include_directories(/usr/include/$<CXX_COMPILER_ID>/)
expands to /usr/include/GNU/ or /usr/include/Clang/ etc, depending on
the compiler identifier.
String-valued expressions may also be combined with other expressions. Here an example for a string-valued expression within a boolean expressions within a conditional expression:
$<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
expands to OLD_COMPILER if the
CMAKE_CXX_COMPILER_VERSION is less
than 4.2.0.
And here two nested string-valued expressions:
-I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
generates a string of the entries in the INCLUDE_DIRECTORIES target
property with each entry preceded by -I.
Expanding on the previous example, if one first wants to check if the
INCLUDE_DIRECTORIES property is non-empty, then it is advisable to
introduce a helper variable to keep the code readable:
set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
$<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
The following string-valued generator expressions are available:
Escaped Characters¶
String literals to escape the special meaning a character would otherwise have:
$<ANGLE-R>- A literal
>. Used for example to compare strings that contain a>. $<COMMA>- A literal
,. Used for example to compare strings which contain a,. $<SEMICOLON>- A literal
;. Used to prevent list expansion on an argument with;.
Conditional Expressions¶
Conditional generator expressions depend on a boolean condition
that must be 0 or 1.
$<condition:true_string>- Evaluates to
true_stringifconditionis1. Otherwise evaluates to the empty string. $<IF:condition,true_string,false_string>- Evaluates to
true_stringifconditionis1. Otherwise evaluates tofalse_string.
Typically, the condition is a boolean generator expression. For instance,
$<$<CONFIG:Debug>:DEBUG_MODE>
expands to DEBUG_MODE when the Debug configuration is used, and
otherwise expands to the empty string.
String Transformations¶
$<JOIN:list,string>- Joins the list with the content of
string. $<REMOVE_DUPLICATES:list>- Removes duplicated items in the given
list. $<FILTER:list,INCLUDE|EXCLUDE,regex>- Includes or removes items from
listthat match the regular expressionregex. $<LOWER_CASE:string>- Content of
stringconverted to lower case. $<UPPER_CASE:string>- Content of
stringconverted to upper case. $<GENEX_EVAL:expr>- Content of
exprevaluated as a generator expression in the current context. This enables consumption of generator expressions whose evaluation results itself in generator expressions. $<TARGET_GENEX_EVAL:tgt,expr>Content of
exprevaluated as a generator expression in the context oftgttarget. This enables consumption of custom target properties that themselves contain generator expressions.Having the capability to evaluate generator expressions is very useful when you want to manage custom properties supporting generator expressions. For example:
add_library(foo ...) set_property(TARGET foo PROPERTY CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> ) add_custom_target(printFooKeys COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> )
This naive implementation of the
printFooKeyscustom command is wrong becauseCUSTOM_KEYStarget property is not evaluated and the content is passed as is (i.e.$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>).To have the expected result (i.e.
FOO_EXTRA_THINGSif config isDebug), it is required to evaluate the output of$<TARGET_PROPERTY:foo,CUSTOM_KEYS>:add_custom_target(printFooKeys COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> )
Variable Queries¶
$<CONFIG>- Configuration name.
$<CONFIGURATION>- Configuration name. Deprecated since CMake 3.0. Use
CONFIGinstead. $<PLATFORM_ID>- The current system’s CMake platform id.
See also the
CMAKE_SYSTEM_NAMEvariable. $<C_COMPILER_ID>- The CMake’s compiler id of the C compiler used.
See also the
CMAKE_<LANG>_COMPILER_IDvariable. $<CXX_COMPILER_ID>- The CMake’s compiler id of the CXX compiler used.
See also the
CMAKE_<LANG>_COMPILER_IDvariable. $<CUDA_COMPILER_ID>- The CMake’s compiler id of the CUDA compiler used.
See also the
CMAKE_<LANG>_COMPILER_IDvariable. $<OBJC_COMPILER_ID>- The CMake’s compiler id of the OBJC compiler used.
See also the
CMAKE_<LANG>_COMPILER_IDvariable. $<OBJCXX_COMPILER_ID>- The CMake’s compiler id of the OBJCXX compiler used.
See also the
CMAKE_<LANG>_COMPILER_IDvariable. $<Fortran_COMPILER_ID>- The CMake’s compiler id of the Fortran compiler used.
See also the
CMAKE_<LANG>_COMPILER_IDvariable. $<C_COMPILER_VERSION>- The version of the C compiler used.
See also the
CMAKE_<LANG>_COMPILER_VERSIONvariable. $<CXX_COMPILER_VERSION>- The version of the CXX compiler used.
See also the
CMAKE_<LANG>_COMPILER_VERSIONvariable. $<CUDA_COMPILER_VERSION>- The version of the CUDA compiler used.
See also the
CMAKE_<LANG>_COMPILER_VERSIONvariable. $<OBJC_COMPILER_VERSION>- The version of the OBJC compiler used.
See also the
CMAKE_<LANG>_COMPILER_VERSIONvariable. $<OBJCXX_COMPILER_VERSION>- The version of the OBJCXX compiler used.
See also the
CMAKE_<LANG>_COMPILER_VERSIONvariable. $<Fortran_COMPILER_VERSION>- The version of the Fortran compiler used.
See also the
CMAKE_<LANG>_COMPILER_VERSIONvariable. $<COMPILE_LANGUAGE>- The compile language of source files when evaluating compile options.
See the related boolean expression
$<COMPILE_LANGUAGE:language>for notes about the portability of this generator expression.
Target-Dependent Queries¶
$<TARGET_NAME_IF_EXISTS:tgt>- Expands to the
tgtif the given target exists, an empty string otherwise. $<TARGET_FILE:tgt>- Full path to main file (.exe, .so.1.2, .a) where
tgtis the name of a target. $<TARGET_FILE_BASE_NAME:tgt>Base name of main file where
tgtis the name of a target.The base name corresponds to the target file name (see
$<TARGET_FILE_NAME:tgt>) without prefix and suffix. For example, if target file name islibbase.so, the base name isbase.See also the
OUTPUT_NAME,ARCHIVE_OUTPUT_NAME,LIBRARY_OUTPUT_NAMEandRUNTIME_OUTPUT_NAMEtarget properties and their configuration specific variantsOUTPUT_NAME_<CONFIG>,ARCHIVE_OUTPUT_NAME_<CONFIG>,LIBRARY_OUTPUT_NAME_<CONFIG>andRUNTIME_OUTPUT_NAME_<CONFIG>.The
<CONFIG>_POSTFIXandDEBUG_POSTFIXtarget properties can also be considered.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_FILE_PREFIX:tgt>Prefix of main file where
tgtis the name of a target.See also the
PREFIXtarget property.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_FILE_SUFFIX:tgt>Suffix of main file where
tgtis the name of a target.The suffix corresponds to the file extension (such as ”.so” or ”.exe”).
See also the
SUFFIXtarget property.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_FILE_NAME:tgt>- Name of main file (.exe, .so.1.2, .a).
$<TARGET_FILE_DIR:tgt>- Directory of main file (.exe, .so.1.2, .a).
$<TARGET_LINKER_FILE:tgt>- File used to link (.a, .lib, .so) where
tgtis the name of a target. $<TARGET_LINKER_FILE_BASE_NAME:tgt>Base name of file used to link where
tgtis the name of a target.The base name corresponds to the target linker file name (see
$<TARGET_LINKER_FILE_NAME:tgt>) without prefix and suffix. For example, if target file name islibbase.a, the base name isbase.See also the
OUTPUT_NAME,ARCHIVE_OUTPUT_NAME, andLIBRARY_OUTPUT_NAMEtarget properties and their configuration specific variantsOUTPUT_NAME_<CONFIG>,ARCHIVE_OUTPUT_NAME_<CONFIG>andLIBRARY_OUTPUT_NAME_<CONFIG>.The
<CONFIG>_POSTFIXandDEBUG_POSTFIXtarget properties can also be considered.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_LINKER_FILE_PREFIX:tgt>Prefix of file used to link where
tgtis the name of a target.See also the
PREFIXandIMPORT_PREFIXtarget properties.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_LINKER_FILE_SUFFIX:tgt>Suffix of file used to link where
tgtis the name of a target.The suffix corresponds to the file extension (such as ”.so” or ”.lib”).
See also the
SUFFIXandIMPORT_SUFFIXtarget properties.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_LINKER_FILE_NAME:tgt>- Name of file used to link (.a, .lib, .so).
$<TARGET_LINKER_FILE_DIR:tgt>- Directory of file used to link (.a, .lib, .so).
$<TARGET_SONAME_FILE:tgt>- File with soname (.so.3) where
tgtis the name of a target. $<TARGET_SONAME_FILE_NAME:tgt>- Name of file with soname (.so.3).
$<TARGET_SONAME_FILE_DIR:tgt>- Directory of with soname (.so.3).
$<TARGET_PDB_FILE:tgt>Full path to the linker generated program database file (.pdb) where
tgtis the name of a target.See also the
PDB_NAMEandPDB_OUTPUT_DIRECTORYtarget properties and their configuration specific variantsPDB_NAME_<CONFIG>andPDB_OUTPUT_DIRECTORY_<CONFIG>.$<TARGET_PDB_FILE_BASE_NAME:tgt>Base name of the linker generated program database file (.pdb) where
tgtis the name of a target.The base name corresponds to the target PDB file name (see
$<TARGET_PDB_FILE_NAME:tgt>) without prefix and suffix. For example, if target file name isbase.pdb, the base name isbase.See also the
PDB_NAMEtarget property and its configuration specific variantPDB_NAME_<CONFIG>.The
<CONFIG>_POSTFIXandDEBUG_POSTFIXtarget properties can also be considered.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_PDB_FILE_NAME:tgt>- Name of the linker generated program database file (.pdb).
$<TARGET_PDB_FILE_DIR:tgt>- Directory of the linker generated program database file (.pdb).
$<TARGET_BUNDLE_DIR:tgt>- Full path to the bundle directory (
my.app,my.framework, ormy.bundle) wheretgtis the name of a target. $<TARGET_BUNDLE_CONTENT_DIR:tgt>- Full path to the bundle content directory where
tgtis the name of a target. For the macOS SDK it leads tomy.app/Contents,my.framework, ormy.bundle/Contents. For all other SDKs (e.g. iOS) it leads tomy.app,my.framework, ormy.bundledue to the flat bundle structure. $<TARGET_PROPERTY:tgt,prop>Value of the property
propon the targettgt.Note that
tgtis not added as a dependency of the target this expression is evaluated on.$<TARGET_PROPERTY:prop>- Value of the property
propon the target on which the generator expression is evaluated. Note that for generator expressions in Transitive Usage Requirements this is the value of the property on the consuming target rather than the target specifying the requirement. $<INSTALL_PREFIX>- Content of the install prefix when the target is exported via
install(EXPORT)and empty otherwise.
Debugging¶
Since generator expressions are evaluated during generation of the buildsystem,
and not during processing of CMakeLists.txt files, it is not possible to
inspect their result with the message() command.
One possible way to generate debug messages is to add a custom target,
add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
The shell command make genexdebug (invoked after execution of cmake)
would then print the result of $<...>.
Another way is to write debug messages to a file:
file(GENERATE OUTPUT filename CONTENT "$<...>")