1CMAKE-GENERATOR-EXPRESSIONS(7) CMake CMAKE-GENERATOR-EXPRESSIONS(7)
2
6 cmake-generator-expressions - CMake Generator Expressions
7
9 Generator expressions are evaluated during build system generation to
10 produce information specific to each build configuration.
11 Generator expressions are allowed in the context of many target proper‐
13 ties, such as LINK_LIBRARIES, INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS
14 and others. They may also be used when using commands to populate
15 those properties, such as target_link_libraries(), tar‐
16 get_include_directories(), target_compile_definitions() and others.
17 They enable conditional linking, conditional definitions used when com‐
19 piling, conditional include directories, and more. The conditions may
20 be based on the build configuration, target properties, platform infor‐
21 mation or any other queryable information.
22 Generator expressions have the form $<...>. To avoid confusion, this
24 page deviates from most of the CMake documentation in that it omits
25 angular brackets <...> around placeholders like condition, string, tar‐
26 get, among others.
27 Generator expressions can be nested, as shown in most of the examples
29 below.
30
32 Boolean expressions evaluate to either 0 or 1. They are typically used
33 to construct the condition in a conditional generator expression.
34 Available boolean expressions are:
36 Logical Operators
38 $<BOOL:string>
39 Converts string to 0 or 1 according to the rules of the if()
40 command. Evaluates to 0 if any of the following is true:
41 · string is empty,
43 · string is a case-insensitive equal of 0, FALSE, OFF, N, NO,
45 IGNORE, or NOTFOUND, or
46 · string ends in the suffix -NOTFOUND (case-sensitive).
48 Otherwise evaluates to 1.
50 $<AND:conditions>
52 where conditions is a comma-separated list of boolean expres‐
53 sions. Evaluates to 1 if all conditions are 1. Otherwise eval‐
54 uates to 0.
55 $<OR:conditions>
57 where conditions is a comma-separated list of boolean expres‐
58 sions. Evaluates to 1 if at least one of the conditions is 1.
59 Otherwise evaluates to 0.
60 $<NOT:condition>
62 0 if condition is 1, else 1.
63 String Comparisons
65 $<STREQUAL:string1,string2>
66 1 if string1 and string2 are equal, else 0. The comparison is
67 case-sensitive. For a case-insensitive comparison, combine with
68 a string transforming generator expression,
69 $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...
71 $<EQUAL:value1,value2>
73 1 if value1 and value2 are numerically equal, else 0.
74 $<IN_LIST:string,list>
76 1 if string is member of the comma-separated list, else 0. Uses
77 case-sensitive comparisons.
78 $<VERSION_LESS:v1,v2>
80 1 if v1 is a version less than v2, else 0.
81 $<VERSION_GREATER:v1,v2>
83 1 if v1 is a version greater than v2, else 0.
84 $<VERSION_EQUAL:v1,v2>
86 1 if v1 is the same version as v2, else 0.
87 $<VERSION_LESS_EQUAL:v1,v2>
89 1 if v1 is a version less than or equal to v2, else 0.
90 $<VERSION_GREATER_EQUAL:v1,v2>
92 1 if v1 is a version greater than or equal to v2, else 0.
93 Variable Queries
95 $<TARGET_EXISTS:target>
96 1 if target exists, else 0.
97 $<CONFIG:cfg>
99 1 if config is cfg, else 0. This is a case-insensitive compari‐
100 son. The mapping in MAP_IMPORTED_CONFIG_<CONFIG> is also con‐
101 sidered by this expression when it is evaluated on a property on
102 an IMPORTED target.
103 $<PLATFORM_ID:platform_id>
105 1 if the CMake-id of the platform matches platform_id otherwise
106 0. See also the CMAKE_SYSTEM_NAME variable.
107 $<C_COMPILER_ID:compiler_id>
109 1 if the CMake-id of the C compiler matches compiler_id, other‐
110 wise 0. See also the CMAKE_<LANG>_COMPILER_ID variable.
111 $<CXX_COMPILER_ID:compiler_id>
113 1 if the CMake-id of the CXX compiler matches compiler_id, oth‐
114 erwise 0. See also the CMAKE_<LANG>_COMPILER_ID variable.
115 $<Fortran_COMPILER_ID:compiler_id>
117 1 if the CMake-id of the Fortran compiler matches compiler_id,
118 otherwise 0. See also the CMAKE_<LANG>_COMPILER_ID variable.
119 $<C_COMPILER_VERSION:version>
121 1 if the version of the C compiler matches version, otherwise 0.
122 See also the CMAKE_<LANG>_COMPILER_VERSION variable.
123 $<CXX_COMPILER_VERSION:version>
125 1 if the version of the CXX compiler matches version, otherwise
126 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
127 $<Fortran_COMPILER_VERSION:version>
129 1 if the version of the Fortran compiler matches version, other‐
130 wise 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
131 $<TARGET_POLICY:policy>
133 1 if the policy was NEW when the ‘head’ target was created, else
134 0. If the policy was not set, the warning message for the pol‐
135 icy will be emitted. This generator expression only works for a
136 subset of policies.
137 $<COMPILE_FEATURES:features>
139 where features is a comma-spearated list. Evaluates to 1 if all
140 of the features are available for the ‘head’ target, and 0 oth‐
141 erwise. If this expression is used while evaluating the link
142 implementation of a target and if any dependency transitively
143 increases the required C_STANDARD or CXX_STANDARD for the ‘head’
144 target, an error is reported. See the cmake-compile-features(7)
145 manual for information on compile features and a list of sup‐
146 ported compilers.
147 $<COMPILE_LANGUAGE:language>
149 1 when the language used for compilation unit matches language,
150 otherwise 0. This expression may be used to specify compile
151 options, compile definitions, and include directories for source
152 files of a particular language in a target. For example:
153 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
155 target_compile_options(myapp
156 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
157 )
158 target_compile_definitions(myapp
159 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
160 $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
161 )
162 target_include_directories(myapp
163 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
164 )
165 This specifies the use of the -fno-exceptions compile option,
167 COMPILING_CXX compile definition, and cxx_headers include direc‐
168 tory for C++ only (compiler id checks elided). It also speci‐
169 fies a COMPILING_CUDA compile definition for CUDA.
170 Note that with Visual Studio Generators and Xcode there is no
172 way to represent target-wide compile definitions or include
173 directories separately for C and CXX languages. Also, with Vis‐
174 ual Studio Generators there is no way to represent target-wide
175 flags separately for C and CXX languages. Under these genera‐
176 tors, expressions for both C and C++ sources will be evaluated
177 using CXX if there are any C++ sources and otherwise using C. A
178 workaround is to create separate libraries for each source file
179 language instead:
180 add_library(myapp_c foo.c)
182 add_library(myapp_cxx bar.cpp)
183 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
184 add_executable(myapp main.cpp)
185 target_link_libraries(myapp myapp_c myapp_cxx)
186
188 These expressions expand to some string. For example,
189 include_directories(/usr/include/$<CXX_COMPILER_ID>/)
191 expands to /usr/include/GNU/ or /usr/include/Clang/ etc, depending on
193 the compiler identifier.
194 String-valued expressions may also be combined with other expressions.
196 Here an example for a string-valued expression within a boolean expres‐
197 sions within a conditional expression:
198 $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
200 expands to OLD_COMPILER if the CMAKE_CXX_COMPILER_VERSION is less than
202 4.2.0.
203 And here two nested string-valued expressions:
205 -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
207 generates a string of the entries in the INCLUDE_DIRECTORIES target
209 property with each entry preceded by -I.
210 Expanding on the previous example, if one first wants to check if the
212 INCLUDE_DIRECTORIES property is non-empty, then it is advisable to
213 introduce a helper variable to keep the code readable:
214 set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
216 $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
217 The following string-valued generator expressions are available:
219 Escaped Characters
221 String literals to escape the special meaning a character would other‐
222 wise have:
223 $<ANGLE-R>
225 A literal >. Used for example to compare strings that contain a
226 >.
227 $<COMMA>
229 A literal ,. Used for example to compare strings which contain a
230 ,.
231 $<SEMICOLON>
233 A literal ;. Used to prevent list expansion on an argument with
234 ;.
235 Conditional Expressions
237 Conditional generator expressions depend on a boolean condition that
238 must be 0 or 1.
239 $<condition:true_string>
241 Evaluates to true_string if condition is 1. Otherwise evaluates
242 to the empty string.
243 $<IF:condition,true_string,false_string>
245 Evaluates to true_string if condition is 1. Otherwise evaluates
246 to false_string.
247 Typically, the condition is a boolean generator expression. For
249 instance,
250 $<$<CONFIG:Debug>:DEBUG_MODE>
252 expands to DEBUG_MODE when the Debug configuration is used, and other‐
254 wise expands to the empty string.
255 String Transformations
257 $<JOIN:list,string>
258 Joins the list with the content of string.
259 $<LOWER_CASE:string>
261 Content of string converted to lower case.
262 $<UPPER_CASE:string>
264 Content of string converted to upper case.
265 $<GENEX_EVAL:expr>
267 Content of expr evaluated as a generator expression in the cur‐
268 rent context. This enables consumption of generator expressions
269 whose evaluation results itself in generator expressions.
270 $<TARGET_GENEX_EVAL:tgt,expr>
272 Content of expr evaluated as a generator expression in the con‐
273 text of tgt target. This enables consumption of custom target
274 properties that themselves contain generator expressions.
275 Having the capability to evaluate generator expressions is very
277 useful when you want to manage custom properties supporting gen‐
278 erator expressions. For example:
279 add_library(foo ...)
281 set_property(TARGET foo PROPERTY
283 CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
284 )
285 add_custom_target(printFooKeys
287 COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
288 )
289 This naive implementation of the printFooKeys custom command is
291 wrong because CUSTOM_KEYS target property is not evaluated and
292 the content is passed as is (i.e. $<$<CON‐
293 FIG:DEBUG>:FOO_EXTRA_THINGS>).
294 To have the expected result (i.e. FOO_EXTRA_THINGS if config is
296 Debug), it is required to evaluate the output of $<TARGET_PROP‐
297 ERTY:foo,CUSTOM_KEYS>:
298 add_custom_target(printFooKeys
300 COMMAND ${CMAKE_COMMAND} -E
301 echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
302 )
303 Variable Queries
305 $<CONFIG>
306 Configuration name.
307 $<CONFIGURATION>
309 Configuration name. Deprecated since CMake 3.0. Use CONFIG
310 instead.
311 $<PLATFORM_ID>
313 The CMake-id of the platform. See also the CMAKE_SYSTEM_NAME
314 variable.
315 $<C_COMPILER_ID>
317 The CMake-id of the C compiler used. See also the
318 CMAKE_<LANG>_COMPILER_ID variable.
319 $<CXX_COMPILER_ID>
321 The CMake-id of the CXX compiler used. See also the
322 CMAKE_<LANG>_COMPILER_ID variable.
323 $<Fortran_COMPILER_ID>
325 The CMake-id of the Fortran compiler used. See also the
326 CMAKE_<LANG>_COMPILER_ID variable.
327 $<C_COMPILER_VERSION>
329 The version of the C compiler used. See also the
330 CMAKE_<LANG>_COMPILER_VERSION variable.
331 $<CXX_COMPILER_VERSION>
333 The version of the CXX compiler used. See also the
334 CMAKE_<LANG>_COMPILER_VERSION variable.
335 $<Fortran_COMPILER_VERSION>
337 The version of the Fortran compiler used. See also the
338 CMAKE_<LANG>_COMPILER_VERSION variable.
339 $<COMPILE_LANGUAGE>
341 The compile language of source files when evaluating compile
342 options. See the related boolean expression $<COMPILE_LAN‐
343 GUAGE:language> for notes about the portability of this genera‐
344 tor expression.
345 Target-Dependent Queries
347 $<TARGET_NAME_IF_EXISTS:tgt>
348 Expands to the tgt if the given target exists, an empty string
349 otherwise.
350 $<TARGET_FILE:tgt>
352 Full path to main file (.exe, .so.1.2, .a) where tgt is the name
353 of a target.
354 $<TARGET_FILE_NAME:tgt>
356 Name of main file (.exe, .so.1.2, .a).
357 $<TARGET_FILE_DIR:tgt>
359 Directory of main file (.exe, .so.1.2, .a).
360 $<TARGET_LINKER_FILE:tgt>
362 File used to link (.a, .lib, .so) where tgt is the name of a
363 target.
364 $<TARGET_LINKER_FILE_NAME:tgt>
366 Name of file used to link (.a, .lib, .so).
367 $<TARGET_LINKER_FILE_DIR:tgt>
369 Directory of file used to link (.a, .lib, .so).
370 $<TARGET_SONAME_FILE:tgt>
372 File with soname (.so.3) where tgt is the name of a target.
373 $<TARGET_SONAME_FILE_NAME:tgt>
375 Name of file with soname (.so.3).
376 $<TARGET_SONAME_FILE_DIR:tgt>
378 Directory of with soname (.so.3).
379 $<TARGET_PDB_FILE:tgt>
381 Full path to the linker generated program database file (.pdb)
382 where tgt is the name of a target.
383 See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
385 and their configuration specific variants PDB_NAME_<CONFIG> and
386 PDB_OUTPUT_DIRECTORY_<CONFIG>.
387 $<TARGET_PDB_FILE_NAME:tgt>
389 Name of the linker generated program database file (.pdb).
390 $<TARGET_PDB_FILE_DIR:tgt>
392 Directory of the linker generated program database file (.pdb).
393 $<TARGET_BUNDLE_DIR:tgt>
395 Full path to the bundle directory (my.app, my.framework, or
396 my.bundle) where tgt is the name of a target.
397 $<TARGET_BUNDLE_CONTENT_DIR:tgt>
399 Full path to the bundle content directory where tgt is the name
400 of a target. For the macOS SDK it leads to my.app/Contents,
401 my.framework, or my.bundle/Contents. For all other SDKs (e.g.
402 iOS) it leads to my.app, my.framework, or my.bundle due to the
403 flat bundle structure.
404 $<TARGET_PROPERTY:tgt,prop>
406 Value of the property prop on the target tgt.
407 Note that tgt is not added as a dependency of the target this
409 expression is evaluated on.
410 $<TARGET_PROPERTY:prop>
412 Value of the property prop on the target on which the generator
413 expression is evaluated. Note that for generator expressions in
414 Target Usage Requirements this is the value of the property on
415 the consuming target rather than the target specifying the
416 requirement.
417 $<INSTALL_PREFIX>
419 Content of the install prefix when the target is exported via
420 install(EXPORT) and empty otherwise.
421 Output-Related Expressions
423 $<TARGET_NAME:...>
424 Marks ... as being the name of a target. This is required if
425 exporting targets to multiple dependent export sets. The ...
426 must be a literal name of a target- it may not contain generator
427 expressions.
428 $<LINK_ONLY:...>
430 Content of ... except when evaluated in a link interface while
431 propagating Target Usage Requirements, in which case it is the
432 empty string. Intended for use only in an INTER‐
433 FACE_LINK_LIBRARIES target property, perhaps via the tar‐
434 get_link_libraries() command, to specify private link dependen‐
435 cies without other usage requirements.
436 $<INSTALL_INTERFACE:...>
438 Content of ... when the property is exported using
439 install(EXPORT), and empty otherwise.
440 $<BUILD_INTERFACE:...>
442 Content of ... when the property is exported using export(), or
443 when the target is used by another target in the same buildsys‐
444 tem. Expands to the empty string otherwise.
445 $<MAKE_C_IDENTIFIER:...>
447 Content of ... converted to a C identifier. The conversion fol‐
448 lows the same behavior as string(MAKE_C_IDENTIFIER).
449 $<TARGET_OBJECTS:objLib>
451 List of objects resulting from build of objLib. objLib must be
452 an object of type OBJECT_LIBRARY.
453 $<SHELL_PATH:...>
455 Content of ... converted to shell path style. For example,
456 slashes are converted to backslashes in Windows shells and drive
457 letters are converted to posix paths in MSYS shells. The ...
458 must be an absolute path.
459
461 Since generator expressions are evaluated during generation of the
462 buildsystem, and not during processing of CMakeLists.txt files, it is
463 not possible to inspect their result with the message() command.
464 One possible way to generate debug messages is to add a custom target,
466 add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
468 The shell command make genexdebug (invoked after execution of cmake)
470 would then print the result of $<...>.
471 Another way is to write debug messages to a file:
473 file(GENERATE OUTPUT filename CONTENT "$<...>")
475
477 2000-2019 Kitware, Inc. and Contributors
4783.14.5 Jun 01, 2019 CMAKE-GENERATOR-EXPRESSIONS(7)