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(), target_include_di‐
16 rectories(), 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 an‐
25 gular 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. Evaluates to 0 if any of the follow‐
40 ing 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 New in version 3.12.
77 1 if string is member of the semicolon-separated list, else 0.
80 Uses case-sensitive comparisons.
81 $<VERSION_LESS:v1,v2>
83 1 if v1 is a version less than v2, else 0.
84 $<VERSION_GREATER:v1,v2>
86 1 if v1 is a version greater than v2, else 0.
87 $<VERSION_EQUAL:v1,v2>
89 1 if v1 is the same version as v2, else 0.
90 $<VERSION_LESS_EQUAL:v1,v2>
92 New in version 3.7.
93 1 if v1 is a version less than or equal to v2, else 0.
96 $<VERSION_GREATER_EQUAL:v1,v2>
98 New in version 3.7.
99 1 if v1 is a version greater than or equal to v2, else 0.
102 Variable Queries
104 $<TARGET_EXISTS:target>
105 New in version 3.12.
106 1 if target exists, else 0.
109 $<CONFIG:cfgs>
111 1 if config is any one of the entries in comma-separated list
112 cfgs, else 0. This is a case-insensitive comparison. The mapping
113 in MAP_IMPORTED_CONFIG_<CONFIG> is also considered by this ex‐
114 pression when it is evaluated on a property on an IMPORTED tar‐
115 get.
116 $<PLATFORM_ID:platform_ids>
118 where platform_ids is a comma-separated list. 1 if the CMake's
119 platform id matches any one of the entries in platform_ids, oth‐
120 erwise 0. See also the CMAKE_SYSTEM_NAME variable.
121 $<C_COMPILER_ID:compiler_ids>
123 where compiler_ids is a comma-separated list. 1 if the CMake's
124 compiler id of the C compiler matches any one of the entries in
125 compiler_ids, otherwise 0. See also the CMAKE_<LANG>_COM‐
126 PILER_ID variable.
127 $<CXX_COMPILER_ID:compiler_ids>
129 where compiler_ids is a comma-separated list. 1 if the CMake's
130 compiler id of the CXX compiler matches any one of the entries
131 in compiler_ids, otherwise 0. See also the CMAKE_<LANG>_COM‐
132 PILER_ID variable.
133 $<CUDA_COMPILER_ID:compiler_ids>
135 New in version 3.15.
136 where compiler_ids is a comma-separated list. 1 if the CMake's
139 compiler id of the CUDA compiler matches any one of the entries
140 in compiler_ids, otherwise 0. See also the CMAKE_<LANG>_COM‐
141 PILER_ID variable.
142 $<OBJC_COMPILER_ID:compiler_ids>
144 New in version 3.16.
145 where compiler_ids is a comma-separated list. 1 if the CMake's
148 compiler id of the Objective-C compiler matches any one of the
149 entries in compiler_ids, otherwise 0. See also the
150 CMAKE_<LANG>_COMPILER_ID variable.
151 $<OBJCXX_COMPILER_ID:compiler_ids>
153 New in version 3.16.
154 where compiler_ids is a comma-separated list. 1 if the CMake's
157 compiler id of the Objective-C++ compiler matches any one of the
158 entries in compiler_ids, otherwise 0. See also the
159 CMAKE_<LANG>_COMPILER_ID variable.
160 $<Fortran_COMPILER_ID:compiler_ids>
162 where compiler_ids is a comma-separated list. 1 if the CMake's
163 compiler id of the Fortran compiler matches any one of the en‐
164 tries in compiler_ids, otherwise 0. See also the
165 CMAKE_<LANG>_COMPILER_ID variable.
166 $<HIP_COMPILER_ID:compiler_ids>
168 where compiler_ids is a comma-separated list. 1 if the CMake's
169 compiler id of the HIP compiler matches any one of the entries
170 in compiler_ids, otherwise 0. See also the CMAKE_<LANG>_COM‐
171 PILER_ID variable.
172 $<ISPC_COMPILER_ID:compiler_ids>
174 New in version 3.19.
175 where compiler_ids is a comma-separated list. 1 if the CMake's
178 compiler id of the ISPC compiler matches any one of the entries
179 in compiler_ids, otherwise 0. See also the CMAKE_<LANG>_COM‐
180 PILER_ID variable.
181 $<C_COMPILER_VERSION:version>
183 1 if the version of the C compiler matches version, otherwise 0.
184 See also the CMAKE_<LANG>_COMPILER_VERSION variable.
185 $<CXX_COMPILER_VERSION:version>
187 1 if the version of the CXX compiler matches version, otherwise
188 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
189 $<CUDA_COMPILER_VERSION:version>
191 New in version 3.15.
192 1 if the version of the CXX compiler matches version, otherwise
195 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
196 $<OBJC_COMPILER_VERSION:version>
198 New in version 3.16.
199 1 if the version of the OBJC compiler matches version, otherwise
202 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
203 $<OBJCXX_COMPILER_VERSION:version>
205 New in version 3.16.
206 1 if the version of the OBJCXX compiler matches version, other‐
209 wise 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
210 $<Fortran_COMPILER_VERSION:version>
212 1 if the version of the Fortran compiler matches version, other‐
213 wise 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
214 $<HIP_COMPILER_VERSION:version>
216 1 if the version of the HIP compiler matches version, otherwise
217 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
218 $<ISPC_COMPILER_VERSION:version>
220 New in version 3.19.
221 1 if the version of the ISPC compiler matches version, otherwise
224 0. See also the CMAKE_<LANG>_COMPILER_VERSION variable.
225 $<TARGET_POLICY:policy>
227 1 if the policy was NEW when the 'head' target was created, else
228 0. If the policy was not set, the warning message for the pol‐
229 icy will be emitted. This generator expression only works for a
230 subset of policies.
231 $<COMPILE_FEATURES:features>
233 New in version 3.1.
234 where features is a comma-spearated list. Evaluates to 1 if all
237 of the features are available for the 'head' target, and 0 oth‐
238 erwise. If this expression is used while evaluating the link im‐
239 plementation of a target and if any dependency transitively in‐
240 creases the required C_STANDARD or CXX_STANDARD for the 'head'
241 target, an error is reported. See the cmake-compile-features(7)
242 manual for information on compile features and a list of sup‐
243 ported compilers.
244 $<COMPILE_LANG_AND_ID:language,compiler_ids>
246 New in version 3.15.
247 1 when the language used for compilation unit matches language
250 and the CMake's compiler id of the language compiler matches any
251 one of the entries in compiler_ids, otherwise 0. This expression
252 is a short form for the combination of $<COMPILE_LANGUAGE:lan‐
253 guage> and $<LANG_COMPILER_ID:compiler_ids>. This expression may
254 be used to specify compile options, compile definitions, and in‐
255 clude directories for source files of a particular language and
256 compiler combination in a target. For example:
257 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
259 target_compile_definitions(myapp
260 PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
261 $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
262 $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
263 )
264 This specifies the use of different compile definitions based on
266 both the compiler id and compilation language. This example will
267 have a COMPILING_CXX_WITH_CLANG compile definition when Clang is
268 the CXX compiler, and COMPILING_CXX_WITH_INTEL when Intel is the
269 CXX compiler. Likewise when the C compiler is Clang it will
270 only see the COMPILING_C_WITH_CLANG definition.
271 Without the COMPILE_LANG_AND_ID generator expression the same
273 logic would be expressed as:
274 target_compile_definitions(myapp
276 PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
277 $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
278 $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
279 )
280 $<COMPILE_LANGUAGE:languages>
282 New in version 3.3.
283 1 when the language used for compilation unit matches any of the
286 entries in languages, otherwise 0. This expression may be used
287 to specify compile options, compile definitions, and include di‐
288 rectories for source files of a particular language in a target.
289 For example:
290 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
292 target_compile_options(myapp
293 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
294 )
295 target_compile_definitions(myapp
296 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
297 $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
298 )
299 target_include_directories(myapp
300 PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
301 )
302 This specifies the use of the -fno-exceptions compile option,
304 COMPILING_CXX compile definition, and cxx_headers include direc‐
305 tory for C++ only (compiler id checks elided). It also speci‐
306 fies a COMPILING_CUDA compile definition for CUDA.
307 Note that with Visual Studio Generators and Xcode there is no
309 way to represent target-wide compile definitions or include di‐
310 rectories separately for C and CXX languages. Also, with Visual
311 Studio Generators there is no way to represent target-wide flags
312 separately for C and CXX languages. Under these generators, ex‐
313 pressions for both C and C++ sources will be evaluated using CXX
314 if there are any C++ sources and otherwise using C. A work‐
315 around is to create separate libraries for each source file lan‐
316 guage instead:
317 add_library(myapp_c foo.c)
319 add_library(myapp_cxx bar.cpp)
320 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
321 add_executable(myapp main.cpp)
322 target_link_libraries(myapp myapp_c myapp_cxx)
323 $<LINK_LANG_AND_ID:language,compiler_ids>
325 New in version 3.18.
326 1 when the language used for link step matches language and the
329 CMake's compiler id of the language linker matches any one of
330 the entries in compiler_ids, otherwise 0. This expression is a
331 short form for the combination of $<LINK_LANGUAGE:language> and
332 $<LANG_COMPILER_ID:compiler_ids>. This expression may be used to
333 specify link libraries, link options, link directories and link
334 dependencies of a particular language and linker combination in
335 a target. For example:
336 add_library(libC_Clang ...)
338 add_library(libCXX_Clang ...)
339 add_library(libC_Intel ...)
340 add_library(libCXX_Intel ...)
341 add_executable(myapp main.c)
343 if (CXX_CONFIG)
344 target_sources(myapp PRIVATE file.cxx)
345 endif()
346 target_link_libraries(myapp
347 PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
348 $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
349 $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
350 $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
351 This specifies the use of different link libraries based on both
353 the compiler id and link language. This example will have target
354 libCXX_Clang as link dependency when Clang or AppleClang is the
355 CXX linker, and libCXX_Intel when Intel is the CXX linker.
356 Likewise when the C linker is Clang or AppleClang, target
357 libC_Clang will be added as link dependency and libC_Intel when
358 Intel is the C linker.
359 See the note related to $<LINK_LANGUAGE:language> for con‐
361 straints about the usage of this generator expression.
362 $<LINK_LANGUAGE:languages>
364 New in version 3.18.
365 1 when the language used for link step matches any of the en‐
368 tries in languages, otherwise 0. This expression may be used to
369 specify link libraries, link options, link directories and link
370 dependencies of a particular language in a target. For example:
371 add_library(api_C ...)
373 add_library(api_CXX ...)
374 add_library(api INTERFACE)
375 target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
376 $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
377 target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
378 $<$<LINK_LANGUAGE:CXX>:api_CXX>)
379 add_executable(myapp1 main.c)
381 target_link_options(myapp1 PRIVATE api)
382 add_executable(myapp2 main.cpp)
384 target_link_options(myapp2 PRIVATE api)
385 This specifies to use the api target for linking targets myapp1
387 and myapp2. In practice, myapp1 will link with target api_C and
388 option -opt_c because it will use C as link language. And myapp2
389 will link with api_CXX and option -opt_cxx because CXX will be
390 the link language.
391 NOTE:
393 To determine the link language of a target, it is required to
394 collect, transitively, all the targets which will be linked
395 to it. So, for link libraries properties, a double evaluation
396 will be done. During the first evaluation, $<LINK_LAN‐
397 GUAGE:..> expressions will always return 0. The link lan‐
398 guage computed after this first pass will be used to do the
399 second pass. To avoid inconsistency, it is required that the
400 second pass do not change the link language. Moreover, to
401 avoid unexpected side-effects, it is required to specify com‐
402 plete entities as part of the $<LINK_LANGUAGE:..> expression.
403 For example:
404 add_library(lib STATIC file.cxx)
406 add_library(libother STATIC file.c)
407 # bad usage
409 add_executable(myapp1 main.c)
410 target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
411 # correct usage
413 add_executable(myapp2 main.c)
414 target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
415 In this example, for myapp1, the first pass will, unexpect‐
417 edly, determine that the link language is CXX because the
418 evaluation of the generator expression will be an empty
419 string so myapp1 will depends on target lib which is C++. On
420 the contrary, for myapp2, the first evaluation will give C as
421 link language, so the second pass will correctly add target
422 libother as link dependency.
423 $<DEVICE_LINK:list>
425 New in version 3.18.
426 Returns the list if it is the device link step, an empty list
429 otherwise. The device link step is controlled by CUDA_SEPARA‐
430 BLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS properties and
431 policy CMP0105. This expression can only be used to specify link
432 options.
433 $<HOST_LINK:list>
435 New in version 3.18.
436 Returns the list if it is the normal link step, an empty list
439 otherwise. This expression is mainly useful when a device link
440 step is also involved (see $<DEVICE_LINK:list> generator expres‐
441 sion). This expression can only be used to specify link options.
442
444 These expressions expand to some string. For example,
445 include_directories(/usr/include/$<CXX_COMPILER_ID>/)
447 expands to /usr/include/GNU/ or /usr/include/Clang/ etc, depending on
449 the compiler identifier.
450 String-valued expressions may also be combined with other expressions.
452 Here an example for a string-valued expression within a boolean expres‐
453 sions within a conditional expression:
454 $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
456 expands to OLD_COMPILER if the CMAKE_CXX_COMPILER_VERSION is less than
458 4.2.0.
459 And here two nested string-valued expressions:
461 -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
463 generates a string of the entries in the INCLUDE_DIRECTORIES target
465 property with each entry preceded by -I.
466 Expanding on the previous example, if one first wants to check if the
468 INCLUDE_DIRECTORIES property is non-empty, then it is advisable to in‐
469 troduce a helper variable to keep the code readable:
470 set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
472 $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
473 The following string-valued generator expressions are available:
475 Escaped Characters
477 String literals to escape the special meaning a character would other‐
478 wise have:
479 $<ANGLE-R>
481 A literal >. Used for example to compare strings that contain a
482 >.
483 $<COMMA>
485 A literal ,. Used for example to compare strings which contain a
486 ,.
487 $<SEMICOLON>
489 A literal ;. Used to prevent list expansion on an argument with
490 ;.
491 Conditional Expressions
493 Conditional generator expressions depend on a boolean condition that
494 must be 0 or 1.
495 $<condition:true_string>
497 Evaluates to true_string if condition is 1. Otherwise evaluates
498 to the empty string.
499 $<IF:condition,true_string,false_string>
501 New in version 3.8.
502 Evaluates to true_string if condition is 1. Otherwise evaluates
505 to false_string.
506 Typically, the condition is a boolean generator expression. For in‐
508 stance,
509 $<$<CONFIG:Debug>:DEBUG_MODE>
511 expands to DEBUG_MODE when the Debug configuration is used, and other‐
513 wise expands to the empty string.
514 String Transformations
516 $<JOIN:list,string>
517 Joins the list with the content of string.
518 $<REMOVE_DUPLICATES:list>
520 New in version 3.15.
521 Removes duplicated items in the given list.
524 $<FILTER:list,INCLUDE|EXCLUDE,regex>
526 New in version 3.15.
527 Includes or removes items from list that match the regular ex‐
530 pression regex.
531 $<LOWER_CASE:string>
533 Content of string converted to lower case.
534 $<UPPER_CASE:string>
536 Content of string converted to upper case.
537 $<GENEX_EVAL:expr>
539 New in version 3.12.
540 Content of expr evaluated as a generator expression in the cur‐
543 rent context. This enables consumption of generator expressions
544 whose evaluation results itself in generator expressions.
545 $<TARGET_GENEX_EVAL:tgt,expr>
547 New in version 3.12.
548 Content of expr evaluated as a generator expression in the con‐
551 text of tgt target. This enables consumption of custom target
552 properties that themselves contain generator expressions.
553 Having the capability to evaluate generator expressions is very
555 useful when you want to manage custom properties supporting gen‐
556 erator expressions. For example:
557 add_library(foo ...)
559 set_property(TARGET foo PROPERTY
561 CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
562 )
563 add_custom_target(printFooKeys
565 COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
566 )
567 This naive implementation of the printFooKeys custom command is
569 wrong because CUSTOM_KEYS target property is not evaluated and
570 the content is passed as is (i.e. $<$<CONFIG:DEBUG>:FOO_EX‐
571 TRA_THINGS>).
572 To have the expected result (i.e. FOO_EXTRA_THINGS if config is
574 Debug), it is required to evaluate the output of $<TARGET_PROP‐
575 ERTY:foo,CUSTOM_KEYS>:
576 add_custom_target(printFooKeys
578 COMMAND ${CMAKE_COMMAND} -E
579 echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
580 )
581 Variable Queries
583 $<CONFIG>
584 Configuration name.
585 $<CONFIGURATION>
587 Configuration name. Deprecated since CMake 3.0. Use CONFIG in‐
588 stead.
589 $<PLATFORM_ID>
591 The current system's CMake platform id. See also the CMAKE_SYS‐
592 TEM_NAME variable.
593 $<C_COMPILER_ID>
595 The CMake's compiler id of the C compiler used. See also the
596 CMAKE_<LANG>_COMPILER_ID variable.
597 $<CXX_COMPILER_ID>
599 The CMake's compiler id of the CXX compiler used. See also the
600 CMAKE_<LANG>_COMPILER_ID variable.
601 $<CUDA_COMPILER_ID>
603 The CMake's compiler id of the CUDA compiler used. See also the
604 CMAKE_<LANG>_COMPILER_ID variable.
605 $<OBJC_COMPILER_ID>
607 New in version 3.16.
608 The CMake's compiler id of the OBJC compiler used. See also the
611 CMAKE_<LANG>_COMPILER_ID variable.
612 $<OBJCXX_COMPILER_ID>
614 New in version 3.16.
615 The CMake's compiler id of the OBJCXX compiler used. See also
618 the CMAKE_<LANG>_COMPILER_ID variable.
619 $<Fortran_COMPILER_ID>
621 The CMake's compiler id of the Fortran compiler used. See also
622 the CMAKE_<LANG>_COMPILER_ID variable.
623 $<HIP_COMPILER_ID>
625 The CMake's compiler id of the HIP compiler used. See also the
626 CMAKE_<LANG>_COMPILER_ID variable.
627 $<ISPC_COMPILER_ID>
629 New in version 3.19.
630 The CMake's compiler id of the ISPC compiler used. See also the
633 CMAKE_<LANG>_COMPILER_ID variable.
634 $<C_COMPILER_VERSION>
636 The version of the C compiler used. See also the
637 CMAKE_<LANG>_COMPILER_VERSION variable.
638 $<CXX_COMPILER_VERSION>
640 The version of the CXX compiler used. See also the
641 CMAKE_<LANG>_COMPILER_VERSION variable.
642 $<CUDA_COMPILER_VERSION>
644 The version of the CUDA compiler used. See also the
645 CMAKE_<LANG>_COMPILER_VERSION variable.
646 $<OBJC_COMPILER_VERSION>
648 New in version 3.16.
649 The version of the OBJC compiler used. See also the
652 CMAKE_<LANG>_COMPILER_VERSION variable.
653 $<OBJCXX_COMPILER_VERSION>
655 New in version 3.16.
656 The version of the OBJCXX compiler used. See also the
659 CMAKE_<LANG>_COMPILER_VERSION variable.
660 $<Fortran_COMPILER_VERSION>
662 The version of the Fortran compiler used. See also the
663 CMAKE_<LANG>_COMPILER_VERSION variable.
664 $<HIP_COMPILER_VERSION>
666 The version of the HIP compiler used. See also the
667 CMAKE_<LANG>_COMPILER_VERSION variable.
668 $<ISPC_COMPILER_VERSION>
670 New in version 3.19.
671 The version of the ISPC compiler used. See also the
674 CMAKE_<LANG>_COMPILER_VERSION variable.
675 $<COMPILE_LANGUAGE>
677 New in version 3.3.
678 The compile language of source files when evaluating compile op‐
681 tions. See the related boolean expression $<COMPILE_LAN‐
682 GUAGE:language> for notes about the portability of this genera‐
683 tor expression.
684 $<LINK_LANGUAGE>
686 New in version 3.18.
687 The link language of target when evaluating link options. See
690 the related boolean expression $<LINK_LANGUAGE:language> for
691 notes about the portability of this generator expression.
692 NOTE:
694 This generator expression is not supported by the link li‐
695 braries properties to avoid side-effects due to the double
696 evaluation of these properties.
697 Target-Dependent Queries
699 These queries refer to a target tgt. This can be any runtime artifact,
700 namely:
701 • an executable target created by add_executable()
703 • a shared library target (.so, .dll but not their .lib import library)
705 created by add_library()
706 • a static library target created by add_library()
708 In the following, "the tgt filename" means the name of the tgt binary
710 file. This has to be distinguished from "the target name", which is
711 just the string tgt.
712 $<TARGET_NAME_IF_EXISTS:tgt>
714 New in version 3.12.
715 The target name tgt if the target exists, an empty string other‐
718 wise.
719 Note that tgt is not added as a dependency of the target this
721 expression is evaluated on.
722 $<TARGET_FILE:tgt>
724 Full path to the tgt binary file.
725 $<TARGET_FILE_BASE_NAME:tgt>
727 New in version 3.15.
728 Base name of tgt, i.e. $<TARGET_FILE_NAME:tgt> without prefix
731 and suffix. For example, if the tgt filename is libbase.so, the
732 base name is base.
733 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, LIBRARY_OUT‐
735 PUT_NAME and RUNTIME_OUTPUT_NAME target properties and their
736 configuration specific variants OUTPUT_NAME_<CONFIG>, AR‐
737 CHIVE_OUTPUT_NAME_<CONFIG>, LIBRARY_OUTPUT_NAME_<CONFIG> and
738 RUNTIME_OUTPUT_NAME_<CONFIG>.
739 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
741 also be considered.
742 Note that tgt is not added as a dependency of the target this
744 expression is evaluated on.
745 $<TARGET_FILE_PREFIX:tgt>
747 New in version 3.15.
748 Prefix of the tgt filename (such as lib).
751 See also the PREFIX target property.
753 Note that tgt is not added as a dependency of the target this
755 expression is evaluated on.
756 $<TARGET_FILE_SUFFIX:tgt>
758 New in version 3.15.
759 Suffix of the tgt filename (extension such as .so or .exe).
762 See also the SUFFIX target property.
764 Note that tgt is not added as a dependency of the target this
766 expression is evaluated on.
767 $<TARGET_FILE_NAME:tgt>
769 The tgt filename.
770 Note that tgt is not added as a dependency of the target this
772 expression is evaluated on (see policy CMP0112).
773 $<TARGET_FILE_DIR:tgt>
775 Directory of the tgt binary file.
776 Note that tgt is not added as a dependency of the target this
778 expression is evaluated on (see policy CMP0112).
779 $<TARGET_LINKER_FILE:tgt>
781 File used when linking to the tgt target. This will usually be
782 the library that tgt represents (.a, .lib, .so), but for a
783 shared library on DLL platforms, it would be the .lib import li‐
784 brary associated with the DLL.
785 $<TARGET_LINKER_FILE_BASE_NAME:tgt>
787 New in version 3.15.
788 Base name of file used to link the target tgt, i.e. $<TAR‐
791 GET_LINKER_FILE_NAME:tgt> without prefix and suffix. For exam‐
792 ple, if target file name is libbase.a, the base name is base.
793 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, and LIBRARY_OUT‐
795 PUT_NAME target properties and their configuration specific
796 variants OUTPUT_NAME_<CONFIG>, ARCHIVE_OUTPUT_NAME_<CONFIG> and
797 LIBRARY_OUTPUT_NAME_<CONFIG>.
798 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
800 also be considered.
801 Note that tgt is not added as a dependency of the target this
803 expression is evaluated on.
804 $<TARGET_LINKER_FILE_PREFIX:tgt>
806 New in version 3.15.
807 Prefix of file used to link target tgt.
810 See also the PREFIX and IMPORT_PREFIX target properties.
812 Note that tgt is not added as a dependency of the target this
814 expression is evaluated on.
815 $<TARGET_LINKER_FILE_SUFFIX:tgt>
817 New in version 3.15.
818 Suffix of file used to link where tgt is the name of a target.
821 The suffix corresponds to the file extension (such as ".so" or
823 ".lib").
824 See also the SUFFIX and IMPORT_SUFFIX target properties.
826 Note that tgt is not added as a dependency of the target this
828 expression is evaluated on.
829 $<TARGET_LINKER_FILE_NAME:tgt>
831 Name of file used to link target tgt.
832 Note that tgt is not added as a dependency of the target this
834 expression is evaluated on (see policy CMP0112).
835 $<TARGET_LINKER_FILE_DIR:tgt>
837 Directory of file used to link target tgt.
838 Note that tgt is not added as a dependency of the target this
840 expression is evaluated on (see policy CMP0112).
841 $<TARGET_SONAME_FILE:tgt>
843 File with soname (.so.3) where tgt is the name of a target.
844 $<TARGET_SONAME_FILE_NAME:tgt>
846 Name of file with soname (.so.3).
847 Note that tgt is not added as a dependency of the target this
849 expression is evaluated on (see policy CMP0112).
850 $<TARGET_SONAME_FILE_DIR:tgt>
852 Directory of with soname (.so.3).
853 Note that tgt is not added as a dependency of the target this
855 expression is evaluated on (see policy CMP0112).
856 $<TARGET_PDB_FILE:tgt>
858 New in version 3.1.
859 Full path to the linker generated program database file (.pdb)
862 where tgt is the name of a target.
863 See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
865 and their configuration specific variants PDB_NAME_<CONFIG> and
866 PDB_OUTPUT_DIRECTORY_<CONFIG>.
867 $<TARGET_PDB_FILE_BASE_NAME:tgt>
869 New in version 3.15.
870 Base name of the linker generated program database file (.pdb)
873 where tgt is the name of a target.
874 The base name corresponds to the target PDB file name (see
876 $<TARGET_PDB_FILE_NAME:tgt>) without prefix and suffix. For ex‐
877 ample, if target file name is base.pdb, the base name is base.
878 See also the PDB_NAME target property and its configuration spe‐
880 cific variant PDB_NAME_<CONFIG>.
881 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
883 also be considered.
884 Note that tgt is not added as a dependency of the target this
886 expression is evaluated on.
887 $<TARGET_PDB_FILE_NAME:tgt>
889 New in version 3.1.
890 Name of the linker generated program database file (.pdb).
893 Note that tgt is not added as a dependency of the target this
895 expression is evaluated on (see policy CMP0112).
896 $<TARGET_PDB_FILE_DIR:tgt>
898 New in version 3.1.
899 Directory of the linker generated program database file (.pdb).
902 Note that tgt is not added as a dependency of the target this
904 expression is evaluated on (see policy CMP0112).
905 $<TARGET_BUNDLE_DIR:tgt>
907 New in version 3.9.
908 Full path to the bundle directory (my.app, my.framework, or
911 my.bundle) where tgt is the name of a target.
912 Note that tgt is not added as a dependency of the target this
914 expression is evaluated on (see policy CMP0112).
915 $<TARGET_BUNDLE_CONTENT_DIR:tgt>
917 New in version 3.9.
918 Full path to the bundle content directory where tgt is the name
921 of a target. For the macOS SDK it leads to my.app/Contents,
922 my.framework, or my.bundle/Contents. For all other SDKs (e.g.
923 iOS) it leads to my.app, my.framework, or my.bundle due to the
924 flat bundle structure.
925 Note that tgt is not added as a dependency of the target this
927 expression is evaluated on (see policy CMP0112).
928 $<TARGET_PROPERTY:tgt,prop>
930 Value of the property prop on the target tgt.
931 Note that tgt is not added as a dependency of the target this
933 expression is evaluated on.
934 $<TARGET_PROPERTY:prop>
936 Value of the property prop on the target for which the expres‐
937 sion is being evaluated. Note that for generator expressions in
938 Target Usage Requirements this is the consuming target rather
939 than the target specifying the requirement.
940 $<TARGET_RUNTIME_DLLS:tgt>
942 New in version 3.21.
943 List of DLLs that the target depends on at runtime. This is de‐
946 termined by the locations of all the SHARED and MODULE targets
947 in the target's transitive dependencies. Using this generator
948 expression on targets other than executables, SHARED libraries,
949 and MODULE libraries is an error. On non-DLL platforms, it
950 evaluates to an empty string.
951 This generator expression can be used to copy all of the DLLs
953 that a target depends on into its output directory in a
954 POST_BUILD custom command. For example:
955 find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
957 add_executable(exe main.c)
959 target_link_libraries(exe PRIVATE foo::foo foo::bar)
960 add_custom_command(TARGET exe POST_BUILD
961 COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
962 COMMAND_EXPAND_LISTS
963 )
964 NOTE:
966 Imported Targets are supported only if they know the location
967 of their .dll files. An imported SHARED or MODULE library
968 must have IMPORTED_LOCATION set to its .dll file. See the
969 add_library imported libraries section for details. Many
970 Find Modules produce imported targets with the UNKNOWN type
971 and therefore will be ignored.
972 $<INSTALL_PREFIX>
974 Content of the install prefix when the target is exported via
975 install(EXPORT), or when evaluated in the INSTALL_NAME_DIR prop‐
976 erty or the INSTALL_NAME_DIR argument of install(RUNTIME_DEPEN‐
977 DENCY_SET), and empty otherwise.
978 Output-Related Expressions
980 $<TARGET_NAME:...>
981 Marks ... as being the name of a target. This is required if
982 exporting targets to multiple dependent export sets. The ...
983 must be a literal name of a target- it may not contain generator
984 expressions.
985 $<LINK_ONLY:...>
987 New in version 3.1.
988 Content of ... except when evaluated in a link interface while
991 propagating Target Usage Requirements, in which case it is the
992 empty string. Intended for use only in an INTERFACE_LINK_LI‐
993 BRARIES target property, perhaps via the target_link_libraries()
994 command, to specify private link dependencies without other us‐
995 age requirements.
996 $<INSTALL_INTERFACE:...>
998 Content of ... when the property is exported using install(EX‐
999 PORT), and empty otherwise.
1000 $<BUILD_INTERFACE:...>
1002 Content of ... when the property is exported using export(), or
1003 when the target is used by another target in the same buildsys‐
1004 tem. Expands to the empty string otherwise.
1005 $<MAKE_C_IDENTIFIER:...>
1007 Content of ... converted to a C identifier. The conversion fol‐
1008 lows the same behavior as string(MAKE_C_IDENTIFIER).
1009 $<TARGET_OBJECTS:objLib>
1011 New in version 3.1.
1012 List of objects resulting from build of objLib.
1015 $<SHELL_PATH:...>
1017 New in version 3.4.
1018 Content of ... converted to shell path style. For example,
1021 slashes are converted to backslashes in Windows shells and drive
1022 letters are converted to posix paths in MSYS shells. The ...
1023 must be an absolute path.
1024 New in version 3.14: The ... may be a semicolon-separated list
1026 of paths, in which case each path is converted individually and
1027 a result list is generated using the shell path separator (: on
1028 POSIX and ; on Windows). Be sure to enclose the argument con‐
1029 taining this genex in double quotes in CMake source code so that
1030 ; does not split arguments.
1031 $<OUTPUT_CONFIG:...>
1034 New in version 3.20.
1035 Only valid in add_custom_command() and add_custom_target() as
1038 the outer-most generator expression in an argument. With the
1039 Ninja Multi-Config generator, generator expressions in ... are
1040 evaluated using the custom command's "output config". With
1041 other generators, the content of ... is evaluated normally.
1042 $<COMMAND_CONFIG:...>
1044 New in version 3.20.
1045 Only valid in add_custom_command() and add_custom_target() as
1048 the outer-most generator expression in an argument. With the
1049 Ninja Multi-Config generator, generator expressions in ... are
1050 evaluated using the custom command's "command config". With
1051 other generators, the content of ... is evaluated normally.
1052
1054 Since generator expressions are evaluated during generation of the
1055 buildsystem, and not during processing of CMakeLists.txt files, it is
1056 not possible to inspect their result with the message() command.
1057 One possible way to generate debug messages is to add a custom target,
1059 add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
1061 The shell command make genexdebug (invoked after execution of cmake)
1063 would then print the result of $<...>.
1064 Another way is to write debug messages to a file:
1066 file(GENERATE OUTPUT filename CONTENT "$<...>")
1068
1070 2000-2022 Kitware, Inc. and Contributors
10713.22.2 Jan 25, 2022 CMAKE-GENERATOR-EXPRESSIONS(7)