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. They have
11 the form $<...>. For example:
12 target_include_directories(tgt PRIVATE /opt/include/$<CXX_COMPILER_ID>)
14 This would expand to /opt/include/GNU, /opt/include/Clang, etc. de‐
16 pending on the C++ compiler used.
17 Generator expressions are allowed in the context of many target proper‐
19 ties, such as LINK_LIBRARIES, INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS
20 and others. They may also be used when using commands to populate
21 those properties, such as target_link_libraries(),
22 target_include_directories(), target_compile_definitions() and others.
23 They enable conditional linking, conditional definitions used when com‐
24 piling, conditional include directories, and more. The conditions may
25 be based on the build configuration, target properties, platform infor‐
26 mation, or any other queryable information.
27 Generator expressions can be nested:
29 target_compile_definitions(tgt PRIVATE
31 $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
32 )
33 The above would expand to OLD_COMPILER if the
35 CMAKE_CXX_COMPILER_VERSION is less than 4.2.0.
36
38 Generator expressions are typically parsed after command arguments. If
39 a generator expression contains spaces, new lines, semicolons or other
40 characters that may be interpreted as command argument separators, the
41 whole expression should be surrounded by quotes when passed to a com‐
42 mand. Failure to do so may result in the expression being split and it
43 may no longer be recognized as a generator expression.
44 When using add_custom_command() or add_custom_target(), use the VERBA‐
46 TIM and COMMAND_EXPAND_LISTS options to obtain robust argument split‐
47 ting and quoting.
48 # WRONG: Embedded space will be treated as an argument separator.
50 # This ends up not being seen as a generator expression at all.
51 add_custom_target(run_some_tool
52 COMMAND some_tool -I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>
53 VERBATIM
54 )
55 # Better, but still not robust. Quotes prevent the space from splitting the
57 # expression. However, the tool will receive the expanded value as a single
58 # argument.
59 add_custom_target(run_some_tool
60 COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>"
61 VERBATIM
62 )
63 # Nearly correct. Using a semicolon to separate arguments and adding the
65 # COMMAND_EXPAND_LISTS option means that paths with spaces will be handled
66 # correctly. Quoting the whole expression ensures it is seen as a generator
67 # expression. But if the target property is empty, we will get a bare -I
68 # with nothing after it.
69 add_custom_target(run_some_tool
70 COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,;-I>"
71 COMMAND_EXPAND_LISTS
72 VERBATIM
73 )
74 Using variables to build up a more complex generator expression is also
76 a good way to reduce errors and improve readability. The above example
77 can be improved further like so:
78 # The $<BOOL:...> check prevents adding anything if the property is empty,
80 # assuming the property value cannot be one of CMake's false constants.
81 set(prop "$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>")
82 add_custom_target(run_some_tool
83 COMMAND some_tool "$<$<BOOL:${prop}>:-I$<JOIN:${prop},;-I>>"
84 COMMAND_EXPAND_LISTS
85 VERBATIM
86 )
87 A common mistake is to try to split a generator expression across mul‐
89 tiple lines with indenting:
90 # WRONG: New lines and spaces all treated as argument separators, so the
92 # generator expression is split and not recognized correctly.
93 target_compile_definitions(tgt PRIVATE
94 $<$<AND:
95 $<CXX_COMPILER_ID:GNU>,
96 $<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
97 >:HAVE_5_OR_LATER>
98 )
99 Again, use helper variables with well-chosen names to build up a read‐
101 able expression instead:
102 set(is_gnu "$<CXX_COMPILER_ID:GNU>")
104 set(v5_or_later "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>")
105 set(meet_requirements "$<AND:${is_gnu},${v5_or_later}>")
106 target_compile_definitions(tgt PRIVATE
107 "$<${meet_requirements}:HAVE_5_OR_LATER>"
108 )
109
111 Since generator expressions are evaluated during generation of the
112 buildsystem, and not during processing of CMakeLists.txt files, it is
113 not possible to inspect their result with the message() command. One
114 possible way to generate debug messages is to add a custom target:
115 add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
117 After running cmake, you can then build the genexdebug target to print
119 the result of the $<...> expression (i.e. run the command cmake --build
120 ... --target genexdebug).
121 Another way is to write debug messages to a file with file(GENERATE):
123 file(GENERATE OUTPUT filename CONTENT "$<...>")
125
127 NOTE:
128 This reference deviates from most of the CMake documentation in that
129 it omits angular brackets <...> around placeholders like condition,
130 string, target, etc. This is to prevent an opportunity for those
131 placeholders to be misinterpreted as generator expressions.
132 Conditional Expressions
134 A fundamental category of generator expressions relates to conditional
135 logic. Two forms of conditional generator expressions are supported:
136 $<condition:true_string>
138 Evaluates to true_string if condition is 1, or an empty string
139 if condition evaluates to 0. Any other value for condition re‐
140 sults in an error.
141 $<IF:condition,true_string,false_string>
143 New in version 3.8.
144 Evaluates to true_string if condition is 1, or false_string if
147 condition is 0. Any other value for condition results in an er‐
148 ror.
149 Typically, the condition is itself a generator expression. For in‐
151 stance, the following expression expands to DEBUG_MODE when the Debug
152 configuration is used, and the empty string for all other configura‐
153 tions:
154 $<$<CONFIG:Debug>:DEBUG_MODE>
156 Boolean-like condition values other than 1 or 0 can be handled by wrap‐
158 ping them with the $<BOOL:...> generator expression:
159 $<BOOL:string>
161 Converts string to 0 or 1. Evaluates to 0 if any of the follow‐
162 ing is true:
163 • string is empty,
165 • string is a case-insensitive equal of 0, FALSE, OFF, N, NO,
167 IGNORE, or NOTFOUND, or
168 • string ends in the suffix -NOTFOUND (case-sensitive).
170 Otherwise evaluates to 1.
172 The $<BOOL:...> generator expression is often used when a condition is
174 provided by a CMake variable:
175 $<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE>
177 Logical Operators
179 The common boolean logic operators are supported:
180 $<AND:conditions>
182 where conditions is a comma-separated list of boolean expres‐
183 sions, all of which must evaluate to either 1 or 0. The whole
184 expression evaluates to 1 if all conditions are 1. If any con‐
185 dition is 0, the whole expression evaluates to 0.
186 $<OR:conditions>
188 where conditions is a comma-separated list of boolean expres‐
189 sions. all of which must evaluate to either 1 or 0. The whole
190 expression evaluates to 1 if at least one of the conditions is
191 1. If all conditions evaluate to 0, the whole expression evalu‐
192 ates to 0.
193 $<NOT:condition>
195 condition must be 0 or 1. The result of the expression is 0 if
196 condition is 1, else 1.
197 Primary Comparison Expressions
199 CMake supports a variety of generator expressions that compare things.
200 This section covers the primary and most widely used comparison types.
201 Other more specific comparison types are documented in their own sepa‐
202 rate sections further below.
203 String Comparisons
205 $<STREQUAL:string1,string2>
206 1 if string1 and string2 are equal, else 0. The comparison is
207 case-sensitive. For a case-insensitive comparison, combine with
208 a string transforming generator expression. For example, the
209 following evaluates to 1 if ${foo} is any of BAR, Bar, bar, etc.
210 $<STREQUAL:$<UPPER_CASE:${foo}>,BAR>
212 $<EQUAL:value1,value2>
214 1 if value1 and value2 are numerically equal, else 0.
215 Version Comparisons
217 $<VERSION_LESS:v1,v2>
218 1 if v1 is a version less than v2, else 0.
219 $<VERSION_GREATER:v1,v2>
221 1 if v1 is a version greater than v2, else 0.
222 $<VERSION_EQUAL:v1,v2>
224 1 if v1 is the same version as v2, else 0.
225 $<VERSION_LESS_EQUAL:v1,v2>
227 New in version 3.7.
228 1 if v1 is a version less than or equal to v2, else 0.
231 $<VERSION_GREATER_EQUAL:v1,v2>
233 New in version 3.7.
234 1 if v1 is a version greater than or equal to v2, else 0.
237 String Transformations
239 $<LOWER_CASE:string>
240 Content of string converted to lower case.
241 $<UPPER_CASE:string>
243 Content of string converted to upper case.
244 $<MAKE_C_IDENTIFIER:...>
246 Content of ... converted to a C identifier. The conversion fol‐
247 lows the same behavior as string(MAKE_C_IDENTIFIER).
248 List Expressions
250 $<IN_LIST:string,list>
251 New in version 3.12.
252 1 if string is an item in the semicolon-separated list, else 0.
255 It uses case-sensitive comparisons.
256 $<JOIN:list,string>
258 Joins the list with the content of string inserted between each
259 item.
260 $<REMOVE_DUPLICATES:list>
262 New in version 3.15.
263 Removes duplicated items in the given list. The relative order
266 of items is preserved, but if duplicates are encountered, only
267 the first instance is preserved.
268 $<FILTER:list,INCLUDE|EXCLUDE,regex>
270 New in version 3.15.
271 Includes or removes items from list that match the regular ex‐
274 pression regex.
275 Path Expressions
277 Most of the expressions in this section are closely associated with the
278 cmake_path() command, providing the same capabilities, but in the form
279 of a generator expression.
280 For all generator expressions in this section, paths are expected to be
282 in cmake-style format. The $<PATH:CMAKE_PATH> generator expression can
283 be used to convert a native path to a cmake-style one.
284 Path Comparisons
286 $<PATH_EQUAL:path1,path2>
287 New in version 3.24.
288 Compares the lexical representations of two paths. No normaliza‐
291 tion is performed on either path. Returns 1 if the paths are
292 equal, 0 otherwise.
293 See cmake_path(COMPARE) for more details.
295 Path Queries
297 These expressions provide the generation-time capabilities equivalent
298 to the Query options of the cmake_path() command. All paths are ex‐
299 pected to be in cmake-style format.
300 $<PATH:HAS_*,path>
302 New in version 3.24.
303 The following operations return 1 if the particular path compo‐
306 nent is present, 0 otherwise. See Path Structure And Terminology
307 for the meaning of each path component.
308 $<PATH:HAS_ROOT_NAME,path>
310 $<PATH:HAS_ROOT_DIRECTORY,path>
311 $<PATH:HAS_ROOT_PATH,path>
312 $<PATH:HAS_FILENAME,path>
313 $<PATH:HAS_EXTENSION,path>
314 $<PATH:HAS_STEM,path>
315 $<PATH:HAS_RELATIVE_PART,path>
316 $<PATH:HAS_PARENT_PATH,path>
317 Note the following special cases:
319 • For HAS_ROOT_PATH, a true result will only be returned if at
321 least one of root-name or root-directory is non-empty.
322 • For HAS_PARENT_PATH, the root directory is also considered to
324 have a parent, which will be itself. The result is true ex‐
325 cept if the path consists of just a filename.
326 $<PATH:IS_ABSOLUTE,path>
328 New in version 3.24.
329 Returns 1 if the path is absolute, 0 otherwise.
332 $<PATH:IS_RELATIVE,path>
334 New in version 3.24.
335 This will return the opposite of IS_ABSOLUTE.
338 $<PATH:IS_PREFIX[,NORMALIZE],path,input>
340 New in version 3.24.
341 Returns 1 if path is the prefix of input, 0 otherwise.
344 When the NORMALIZE option is specified, path and input are
346 normalized before the check.
347 Path Decomposition
349 These expressions provide the generation-time capabilities equivalent
350 to the Decomposition options of the cmake_path() command. All paths
351 are expected to be in cmake-style format.
352 $<PATH:GET_*,...>
354 New in version 3.24.
355 The following operations retrieve a different component or group
358 of components from a path. See Path Structure And Terminology
359 for the meaning of each path component.
360 $<PATH:GET_ROOT_NAME,path>
362 $<PATH:GET_ROOT_DIRECTORY,path>
363 $<PATH:GET_ROOT_PATH,path>
364 $<PATH:GET_FILENAME,path>
365 $<PATH:GET_EXTENSION[,LAST_ONLY],path>
366 $<PATH:GET_STEM[,LAST_ONLY],path>
367 $<PATH:GET_RELATIVE_PART,path>
368 $<PATH:GET_PARENT_PATH,path>
369 If a requested component is not present in the path, an empty
371 string is returned.
372 Path Transformations
374 These expressions provide the generation-time capabilities equivalent
375 to the Modification and Generation options of the cmake_path() command.
376 All paths are expected to be in cmake-style format.
377 $<PATH:CMAKE_PATH[,NORMALIZE],path>
379 New in version 3.24.
380 Returns path. If path is a native path, it is converted into a
383 cmake-style path with forward-slashes (/). On Windows, the long
384 filename marker is taken into account.
385 When the NORMALIZE option is specified, the path is normalized
387 after the conversion.
388 $<PATH:APPEND,path,input,...>
390 New in version 3.24.
391 Returns all the input arguments appended to path using / as the
394 directory-separator. Depending on the input, the value of path
395 may be discarded.
396 See cmake_path(APPEND) for more details.
398 $<PATH:REMOVE_FILENAME,path>
400 New in version 3.24.
401 Returns path with filename component (as returned by
404 $<PATH:GET_FILENAME>) removed. After removal, any trailing di‐
405 rectory-separator is left alone, if present.
406 See cmake_path(REMOVE_FILENAME) for more details.
408 $<PATH:REPLACE_FILENAME,path,input>
410 New in version 3.24.
411 Returns path with the filename component replaced by input. If
414 path has no filename component (i.e. $<PATH:HAS_FILENAME> re‐
415 turns 0), path is unchanged.
416 See cmake_path(REPLACE_FILENAME) for more details.
418 $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path>
420 New in version 3.24.
421 Returns path with the extension removed, if any.
424 See cmake_path(REMOVE_EXTENSION) for more details.
426 $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path,input>
428 New in version 3.24.
429 Returns path with the extension replaced by input, if any.
432 See cmake_path(REPLACE_EXTENSION) for more details.
434 $<PATH:NORMAL_PATH,path>
436 New in version 3.24.
437 Returns path normalized according to the steps described in
440 Normalization.
441 $<PATH:RELATIVE_PATH,path,base_directory>
443 New in version 3.24.
444 Returns path, modified to make it relative to the base_directory
447 argument.
448 See cmake_path(RELATIVE_PATH) for more details.
450 $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory>
452 New in version 3.24.
453 Returns path as absolute. If path is a relative path
456 ($<PATH:IS_RELATIVE> returns 1), it is evaluated relative to the
457 given base directory specified by base_directory argument.
458 When the NORMALIZE option is specified, the path is normalized
460 after the path computation.
461 See cmake_path(ABSOLUTE_PATH) for more details.
463 Shell Paths
465 $<SHELL_PATH:...>
466 New in version 3.4.
467 Content of ... converted to shell path style. For example,
470 slashes are converted to backslashes in Windows shells and drive
471 letters are converted to posix paths in MSYS shells. The ...
472 must be an absolute path.
473 New in version 3.14: The ... may be a semicolon-separated list
475 of paths, in which case each path is converted individually and
476 a result list is generated using the shell path separator (: on
477 POSIX and ; on Windows). Be sure to enclose the argument con‐
478 taining this genex in double quotes in CMake source code so that
479 ; does not split arguments.
480 Configuration Expressions
483 $<CONFIG>
484 Configuration name. Use this instead of the deprecated
485 CONFIGURATION generator expression.
486 $<CONFIG:cfgs>
488 1 if config is any one of the entries in comma-separated list
489 cfgs, else 0. This is a case-insensitive comparison. The mapping
490 in MAP_IMPORTED_CONFIG_<CONFIG> is also considered by this ex‐
491 pression when it is evaluated on a property of an IMPORTED tar‐
492 get.
493 Changed in version 3.19: Multiple configurations can be speci‐
495 fied for cfgs. CMake 3.18 and earlier only accepted a single
496 configuration.
497 $<OUTPUT_CONFIG:...>
500 New in version 3.20.
501 Only valid in add_custom_command() and add_custom_target() as
504 the outer-most generator expression in an argument. With the
505 Ninja Multi-Config generator, generator expressions in ... are
506 evaluated using the custom command's "output config". With
507 other generators, the content of ... is evaluated normally.
508 $<COMMAND_CONFIG:...>
510 New in version 3.20.
511 Only valid in add_custom_command() and add_custom_target() as
514 the outer-most generator expression in an argument. With the
515 Ninja Multi-Config generator, generator expressions in ... are
516 evaluated using the custom command's "command config". With
517 other generators, the content of ... is evaluated normally.
518 Toolchain And Language Expressions
520 Platform
521 $<PLATFORM_ID>
522 The current system's CMake platform id. See also the
523 CMAKE_SYSTEM_NAME variable.
524 $<PLATFORM_ID:platform_ids>
526 1 if CMake's platform id matches any one of the entries in
527 comma-separated list platform_ids, otherwise 0. See also the
528 CMAKE_SYSTEM_NAME variable.
529 Compiler Version
531 See also the CMAKE_<LANG>_COMPILER_VERSION variable, which is closely
532 related to the expressions in this sub-section.
533 $<C_COMPILER_VERSION>
535 The version of the C compiler used.
536 $<C_COMPILER_VERSION:version>
538 1 if the version of the C compiler matches version, otherwise 0.
539 $<CXX_COMPILER_VERSION>
541 The version of the CXX compiler used.
542 $<CXX_COMPILER_VERSION:version>
544 1 if the version of the CXX compiler matches version, otherwise
545 0.
546 $<CUDA_COMPILER_VERSION>
548 New in version 3.15.
549 The version of the CUDA compiler used.
552 $<CUDA_COMPILER_VERSION:version>
554 New in version 3.15.
555 1 if the version of the CXX compiler matches version, otherwise
558 0.
559 $<OBJC_COMPILER_VERSION>
561 New in version 3.16.
562 The version of the OBJC compiler used.
565 $<OBJC_COMPILER_VERSION:version>
567 New in version 3.16.
568 1 if the version of the OBJC compiler matches version, otherwise
571 0.
572 $<OBJCXX_COMPILER_VERSION>
574 New in version 3.16.
575 The version of the OBJCXX compiler used.
578 $<OBJCXX_COMPILER_VERSION:version>
580 New in version 3.16.
581 1 if the version of the OBJCXX compiler matches version, other‐
584 wise 0.
585 $<Fortran_COMPILER_VERSION>
587 The version of the Fortran compiler used.
588 $<Fortran_COMPILER_VERSION:version>
590 1 if the version of the Fortran compiler matches version, other‐
591 wise 0.
592 $<HIP_COMPILER_VERSION>
594 New in version 3.21.
595 The version of the HIP compiler used.
598 $<HIP_COMPILER_VERSION:version>
600 New in version 3.21.
601 1 if the version of the HIP compiler matches version, otherwise
604 0.
605 $<ISPC_COMPILER_VERSION>
607 New in version 3.19.
608 The version of the ISPC compiler used.
611 $<ISPC_COMPILER_VERSION:version>
613 New in version 3.19.
614 1 if the version of the ISPC compiler matches version, otherwise
617 0.
618 Compiler Language And ID
620 See also the CMAKE_<LANG>_COMPILER_ID variable, which is closely re‐
621 lated to most of the expressions in this sub-section.
622 $<C_COMPILER_ID>
624 CMake's compiler id of the C compiler used.
625 $<C_COMPILER_ID:compiler_ids>
627 where compiler_ids is a comma-separated list. 1 if CMake's com‐
628 piler id of the C compiler matches any one of the entries in
629 compiler_ids, otherwise 0.
630 $<CXX_COMPILER_ID>
632 CMake's compiler id of the CXX compiler used.
633 $<CXX_COMPILER_ID:compiler_ids>
635 where compiler_ids is a comma-separated list. 1 if CMake's com‐
636 piler id of the CXX compiler matches any one of the entries in
637 compiler_ids, otherwise 0.
638 $<CUDA_COMPILER_ID>
640 New in version 3.15.
641 CMake's compiler id of the CUDA compiler used.
644 $<CUDA_COMPILER_ID:compiler_ids>
646 New in version 3.15.
647 where compiler_ids is a comma-separated list. 1 if CMake's com‐
650 piler id of the CUDA compiler matches any one of the entries in
651 compiler_ids, otherwise 0.
652 $<OBJC_COMPILER_ID>
654 New in version 3.16.
655 CMake's compiler id of the OBJC compiler used.
658 $<OBJC_COMPILER_ID:compiler_ids>
660 New in version 3.16.
661 where compiler_ids is a comma-separated list. 1 if CMake's com‐
664 piler id of the Objective-C compiler matches any one of the en‐
665 tries in compiler_ids, otherwise 0.
666 $<OBJCXX_COMPILER_ID>
668 New in version 3.16.
669 CMake's compiler id of the OBJCXX compiler used.
672 $<OBJCXX_COMPILER_ID:compiler_ids>
674 New in version 3.16.
675 where compiler_ids is a comma-separated list. 1 if CMake's com‐
678 piler id of the Objective-C++ compiler matches any one of the
679 entries in compiler_ids, otherwise 0.
680 $<Fortran_COMPILER_ID>
682 CMake's compiler id of the Fortran compiler used.
683 $<Fortran_COMPILER_ID:compiler_ids>
685 where compiler_ids is a comma-separated list. 1 if CMake's com‐
686 piler id of the Fortran compiler matches any one of the entries
687 in compiler_ids, otherwise 0.
688 $<HIP_COMPILER_ID>
690 New in version 3.21.
691 CMake's compiler id of the HIP compiler used.
694 $<HIP_COMPILER_ID:compiler_ids>
696 New in version 3.21.
697 where compiler_ids is a comma-separated list. 1 if CMake's com‐
700 piler id of the HIP compiler matches any one of the entries in
701 compiler_ids, otherwise 0.
702 $<ISPC_COMPILER_ID>
704 New in version 3.19.
705 CMake's compiler id of the ISPC compiler used.
708 $<ISPC_COMPILER_ID:compiler_ids>
710 New in version 3.19.
711 where compiler_ids is a comma-separated list. 1 if CMake's com‐
714 piler id of the ISPC compiler matches any one of the entries in
715 compiler_ids, otherwise 0.
716 $<COMPILE_LANGUAGE>
718 New in version 3.3.
719 The compile language of source files when evaluating compile op‐
722 tions. See the related boolean expression $<COMPILE_LAN‐
723 GUAGE:language> for notes about the portability of this genera‐
724 tor expression.
725 $<COMPILE_LANGUAGE:languages>
727 New in version 3.3.
728 Changed in version 3.15: Multiple languages can be specified for
731 languages. CMake 3.14 and earlier only accepted a single lan‐
732 guage.
733 1 when the language used for compilation unit matches any of the
736 comma-separated entries in languages, otherwise 0. This expres‐
737 sion may be used to specify compile options, compile defini‐
738 tions, and include directories for source files of a particular
739 language in a target. For example:
740 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
742 target_compile_options(myapp
743 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
744 )
745 target_compile_definitions(myapp
746 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
747 $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
748 )
749 target_include_directories(myapp
750 PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
751 )
752 This specifies the use of the -fno-exceptions compile option,
754 COMPILING_CXX compile definition, and cxx_headers include direc‐
755 tory for C++ only (compiler id checks elided). It also speci‐
756 fies a COMPILING_CUDA compile definition for CUDA.
757 Note that with Visual Studio Generators and Xcode there is no
759 way to represent target-wide compile definitions or include di‐
760 rectories separately for C and CXX languages. Also, with Visual
761 Studio Generators there is no way to represent target-wide flags
762 separately for C and CXX languages. Under these generators, ex‐
763 pressions for both C and C++ sources will be evaluated using CXX
764 if there are any C++ sources and otherwise using C. A work‐
765 around is to create separate libraries for each source file lan‐
766 guage instead:
767 add_library(myapp_c foo.c)
769 add_library(myapp_cxx bar.cpp)
770 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
771 add_executable(myapp main.cpp)
772 target_link_libraries(myapp myapp_c myapp_cxx)
773 $<COMPILE_LANG_AND_ID:language,compiler_ids>
775 New in version 3.15.
776 1 when the language used for compilation unit matches language
779 and CMake's compiler id of the language compiler matches any one
780 of the comma-separated entries in compiler_ids, otherwise 0.
781 This expression is a short form for the combination of $<COM‐
782 PILE_LANGUAGE:language> and $<LANG_COMPILER_ID:compiler_ids>.
783 This expression may be used to specify compile options, compile
784 definitions, and include directories for source files of a par‐
785 ticular language and compiler combination in a target. For ex‐
786 ample:
787 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
789 target_compile_definitions(myapp
790 PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
791 $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
792 $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
793 )
794 This specifies the use of different compile definitions based on
796 both the compiler id and compilation language. This example will
797 have a COMPILING_CXX_WITH_CLANG compile definition when Clang is
798 the CXX compiler, and COMPILING_CXX_WITH_INTEL when Intel is the
799 CXX compiler. Likewise, when the C compiler is Clang, it will
800 only see the COMPILING_C_WITH_CLANG definition.
801 Without the COMPILE_LANG_AND_ID generator expression, the same
803 logic would be expressed as:
804 target_compile_definitions(myapp
806 PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
807 $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
808 $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
809 )
810 Compile Features
812 $<COMPILE_FEATURES:features>
813 New in version 3.1.
814 where features is a comma-separated list. Evaluates to 1 if all
817 of the features are available for the 'head' target, and 0 oth‐
818 erwise. If this expression is used while evaluating the link im‐
819 plementation of a target and if any dependency transitively in‐
820 creases the required C_STANDARD or CXX_STANDARD for the 'head'
821 target, an error is reported. See the cmake-compile-features(7)
822 manual for information on compile features and a list of sup‐
823 ported compilers.
824 Linker Language And ID
826 $<LINK_LANGUAGE>
827 New in version 3.18.
828 The link language of the target when evaluating link options.
831 See the related boolean expression $<LINK_LANGUAGE:languages>
832 for notes about the portability of this generator expression.
833 NOTE:
835 This generator expression is not supported by the link li‐
836 braries properties to avoid side-effects due to the double
837 evaluation of these properties.
838 $<LINK_LANGUAGE:languages>
840 New in version 3.18.
841 1 when the language used for link step matches any of the
844 comma-separated entries in languages, otherwise 0. This expres‐
845 sion may be used to specify link libraries, link options, link
846 directories and link dependencies of a particular language in a
847 target. For example:
848 add_library(api_C ...)
850 add_library(api_CXX ...)
851 add_library(api INTERFACE)
852 target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
853 $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
854 target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
855 $<$<LINK_LANGUAGE:CXX>:api_CXX>)
856 add_executable(myapp1 main.c)
858 target_link_options(myapp1 PRIVATE api)
859 add_executable(myapp2 main.cpp)
861 target_link_options(myapp2 PRIVATE api)
862 This specifies to use the api target for linking targets myapp1
864 and myapp2. In practice, myapp1 will link with target api_C and
865 option -opt_c because it will use C as link language. And myapp2
866 will link with api_CXX and option -opt_cxx because CXX will be
867 the link language.
868 NOTE:
870 To determine the link language of a target, it is required to
871 collect, transitively, all the targets which will be linked
872 to it. So, for link libraries properties, a double evaluation
873 will be done. During the first evaluation, $<LINK_LAN‐
874 GUAGE:..> expressions will always return 0. The link lan‐
875 guage computed after this first pass will be used to do the
876 second pass. To avoid inconsistency, it is required that the
877 second pass do not change the link language. Moreover, to
878 avoid unexpected side-effects, it is required to specify com‐
879 plete entities as part of the $<LINK_LANGUAGE:..> expression.
880 For example:
881 add_library(lib STATIC file.cxx)
883 add_library(libother STATIC file.c)
884 # bad usage
886 add_executable(myapp1 main.c)
887 target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
888 # correct usage
890 add_executable(myapp2 main.c)
891 target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
892 In this example, for myapp1, the first pass will, unexpect‐
894 edly, determine that the link language is CXX because the
895 evaluation of the generator expression will be an empty
896 string so myapp1 will depends on target lib which is C++. On
897 the contrary, for myapp2, the first evaluation will give C as
898 link language, so the second pass will correctly add target
899 libother as link dependency.
900 $<LINK_LANG_AND_ID:language,compiler_ids>
902 New in version 3.18.
903 1 when the language used for link step matches language and the
906 CMake's compiler id of the language linker matches any one of
907 the comma-separated entries in compiler_ids, otherwise 0. This
908 expression is a short form for the combination of $<LINK_LAN‐
909 GUAGE:language> and $<LANG_COMPILER_ID:compiler_ids>. This ex‐
910 pression may be used to specify link libraries, link options,
911 link directories and link dependencies of a particular language
912 and linker combination in a target. For example:
913 add_library(libC_Clang ...)
915 add_library(libCXX_Clang ...)
916 add_library(libC_Intel ...)
917 add_library(libCXX_Intel ...)
918 add_executable(myapp main.c)
920 if (CXX_CONFIG)
921 target_sources(myapp PRIVATE file.cxx)
922 endif()
923 target_link_libraries(myapp
924 PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
925 $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
926 $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
927 $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
928 This specifies the use of different link libraries based on both
930 the compiler id and link language. This example will have target
931 libCXX_Clang as link dependency when Clang or AppleClang is the
932 CXX linker, and libCXX_Intel when Intel is the CXX linker.
933 Likewise when the C linker is Clang or AppleClang, target
934 libC_Clang will be added as link dependency and libC_Intel when
935 Intel is the C linker.
936 See the note related to $<LINK_LANGUAGE:language> for con‐
938 straints about the usage of this generator expression.
939 Link Features
941 $<LINK_LIBRARY:feature,library-list>
942 New in version 3.24.
943 Specify a set of libraries to link to a target, along with a
946 feature which provides details about how they should be linked.
947 For example:
948 add_library(lib1 STATIC ...)
950 add_library(lib2 ...)
951 target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")
952 This specifies that lib2 should link to lib1 and use the
954 WHOLE_ARCHIVE feature when doing so.
955 Feature names are case-sensitive and may only contain letters,
957 numbers and underscores. Feature names defined in all uppercase
958 are reserved for CMake's own built-in features. The pre-defined
959 built-in library features are:
960 DEFAULT
962 This feature corresponds to standard linking, essentially
963 equivalent to using no feature at all. It is typically
964 only used with the LINK_LIBRARY_OVERRIDE and
965 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
966 WHOLE_ARCHIVE
968 Force inclusion of all members of a static library. This
969 feature is only supported for the following platforms,
970 with limitations as noted:
971 • Linux.
973 • All BSD variants.
975 • SunOS.
977 • All Apple variants. The library must be specified as a
979 CMake target name, a library file name (such as lib‐
980 foo.a), or a library file path (such as /path/to/lib‐
981 foo.a). Due to a limitation of the Apple linker, it
982 cannot be specified as a plain library name like foo,
983 where foo is not a CMake target.
984 • Windows. When using a MSVC or MSVC-like toolchain, the
986 MSVC version must be greater than 1900.
987 • Cygwin.
989 • MSYS.
991 FRAMEWORK
993 This option tells the linker to search for the specified
994 framework using the -framework linker option. It can
995 only be used on Apple platforms, and only with a linker
996 that understands the option used (i.e. the linker pro‐
997 vided with Xcode, or one compatible with it).
998 The framework can be specified as a CMake framework tar‐
1000 get, a bare framework name, or a file path. If a target
1001 is given, that target must have the FRAMEWORK target
1002 property set to true. For a file path, if it contains a
1003 directory part, that directory will be added as a frame‐
1004 work search path.
1005 add_library(lib SHARED ...)
1007 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
1008 # The constructed linker command line will contain:
1010 # -F/path/to -framework my_framework
1011 File paths must conform to one of the following patterns
1013 (* is a wildcard, and optional parts are shown as [...]):
1014 • [/path/to/]FwName[.framework]
1016 • [/path/to/]FwName.framework/FwName[suffix]
1018 • [/path/to/]FwName.framework/Versions/*/FwName[suf‐
1020 fix]
1021 Note that CMake recognizes and automatically handles
1023 framework targets, even without using the $<LINK_LI‐
1024 BRARY:FRAMEWORK,...> expression. The generator expres‐
1025 sion can still be used with a CMake target if the project
1026 wants to be explicit about it, but it is not required to
1027 do so. The linker command line may have some differences
1028 between using the generator expression or not, but the
1029 final result should be the same. On the other hand, if a
1030 file path is given, CMake will recognize some paths auto‐
1031 matically, but not all cases. The project may want to
1032 use $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that
1033 the expected behavior is clear.
1034 New in version 3.25: The
1036 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property
1037 as well as the suffix of the framework library name are
1038 now supported by the FRAMEWORK features.
1039 NEEDED_FRAMEWORK
1042 This is similar to the FRAMEWORK feature, except it
1043 forces the linker to link with the framework even if no
1044 symbols are used from it. It uses the -needed_framework
1045 option and has the same linker constraints as FRAMEWORK.
1046 REEXPORT_FRAMEWORK
1048 This is similar to the FRAMEWORK feature, except it tells
1049 the linker that the framework should be available to
1050 clients linking to the library being created. It uses
1051 the -reexport_framework option and has the same linker
1052 constraints as FRAMEWORK.
1053 WEAK_FRAMEWORK
1055 This is similar to the FRAMEWORK feature, except it
1056 forces the linker to mark the framework and all refer‐
1057 ences to it as weak imports. It uses the -weak_framework
1058 option and has the same linker constraints as FRAMEWORK.
1059 NEEDED_LIBRARY
1061 This is similar to the NEEDED_FRAMEWORK feature, except
1062 it is for use with non-framework targets or libraries
1063 (Apple platforms only). It uses the -needed_library or
1064 -needed-l option as appropriate, and has the same linker
1065 constraints as NEEDED_FRAMEWORK.
1066 REEXPORT_LIBRARY
1068 This is similar to the REEXPORT_FRAMEWORK feature, ex‐
1069 cept it is for use with non-framework targets or li‐
1070 braries (Apple platforms only). It uses the -reex‐
1071 port_library or -reexport-l option as appropriate, and
1072 has the same linker constraints as REEXPORT_FRAMEWORK.
1073 WEAK_LIBRARY
1075 This is similar to the WEAK_FRAMEWORK feature, except it
1076 is for use with non-framework targets or libraries (Apple
1077 platforms only). It uses the -weak_library or -weak-l
1078 option as appropriate, and has the same linker con‐
1079 straints as WEAK_FRAMEWORK.
1080 Built-in and custom library features are defined in terms of the
1082 following variables:
1083 • CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
1085 • CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>
1087 • CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
1089 • CMAKE_LINK_LIBRARY_USING_<FEATURE>
1091 The value used for each of these variables is the value as set
1093 at the end of the directory scope in which the target was cre‐
1094 ated. The usage is as follows:
1095 1. If the language-specific
1097 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable
1098 is true, the feature must be defined by the corresponding
1099 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> variable.
1100 2. If no language-specific feature is supported, then the
1102 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable must be
1103 true and the feature must be defined by the corresponding
1104 CMAKE_LINK_LIBRARY_USING_<FEATURE> variable.
1105 The following limitations should be noted:
1107 • The library-list can specify CMake targets or libraries. Any
1109 CMake target of type OBJECT or INTERFACE will ignore the fea‐
1110 ture aspect of the expression and instead be linked in the
1111 standard way.
1112 • The $<LINK_LIBRARY:...> generator expression can only be used
1114 to specify link libraries. In practice, this means it can ap‐
1115 pear in the LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES, and
1116 INTERFACE_LINK_LIBRARIES_DIRECT target properties, and be
1117 specified in target_link_libraries() and link_libraries() com‐
1118 mands.
1119 • If a $<LINK_LIBRARY:...> generator expression appears in the
1121 INTERFACE_LINK_LIBRARIES property of a target, it will be in‐
1122 cluded in the imported target generated by a install(EXPORT)
1123 command. It is the responsibility of the environment consum‐
1124 ing this import to define the link feature used by this ex‐
1125 pression.
1126 • Each target or library involved in the link step must have at
1128 most only one kind of library feature. The absence of a fea‐
1129 ture is also incompatible with all other features. For exam‐
1130 ple:
1131 add_library(lib1 ...)
1133 add_library(lib2 ...)
1134 add_library(lib3 ...)
1135 # lib1 will be associated with feature1
1137 target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
1138 # lib1 is being linked with no feature here. This conflicts with the
1140 # use of feature1 in the line above and would result in an error.
1141 target_link_libraries(lib3 PRIVATE lib1 lib2)
1142 Where it isn't possible to use the same feature throughout a
1144 build for a given target or library, the LINK_LIBRARY_OVERRIDE
1145 and LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties can be
1146 used to resolve such incompatibilities.
1147 • The $<LINK_LIBRARY:...> generator expression does not guaran‐
1149 tee that the list of specified targets and libraries will be
1150 kept grouped together. To manage constructs like
1151 --start-group and --end-group, as supported by the GNU ld
1152 linker, use the LINK_GROUP generator expression instead.
1153 $<LINK_GROUP:feature,library-list>
1155 New in version 3.24.
1156 Specify a group of libraries to link to a target, along with a
1159 feature which defines how that group should be linked. For ex‐
1160 ample:
1161 add_library(lib1 STATIC ...)
1163 add_library(lib2 ...)
1164 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
1165 This specifies that lib2 should link to lib1 and external, and
1167 that both of those two libraries should be included on the
1168 linker command line according to the definition of the RESCAN
1169 feature.
1170 Feature names are case-sensitive and may only contain letters,
1172 numbers and underscores. Feature names defined in all uppercase
1173 are reserved for CMake's own built-in features. Currently,
1174 there is only one pre-defined built-in group feature:
1175 RESCAN Some linkers are single-pass only. For such linkers,
1177 circular references between libraries typically result in
1178 unresolved symbols. This feature instructs the linker to
1179 search the specified static libraries repeatedly until no
1180 new undefined references are created.
1181 Normally, a static library is searched only once in the
1183 order that it is specified on the command line. If a
1184 symbol in that library is needed to resolve an undefined
1185 symbol referred to by an object in a library that appears
1186 later on the command line, the linker would not be able
1187 to resolve that reference. By grouping the static li‐
1188 braries with the RESCAN feature, they will all be
1189 searched repeatedly until all possible references are re‐
1190 solved. This will use linker options like --start-group
1191 and --end-group, or on SunOS, -z rescan-start and -z res‐
1192 can-end.
1193 Using this feature has a significant performance cost. It
1195 is best to use it only when there are unavoidable circu‐
1196 lar references between two or more static libraries.
1197 This feature is available when using toolchains that tar‐
1199 get Linux, BSD, and SunOS. It can also be used when tar‐
1200 geting Windows platforms if the GNU toolchain is used.
1201 Built-in and custom group features are defined in terms of the
1203 following variables:
1204 • CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
1206 • CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
1208 • CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
1210 • CMAKE_LINK_GROUP_USING_<FEATURE>
1212 The value used for each of these variables is the value as set
1214 at the end of the directory scope in which the target was cre‐
1215 ated. The usage is as follows:
1216 1. If the language-specific
1218 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable is
1219 true, the feature must be defined by the corresponding
1220 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable.
1221 2. If no language-specific feature is supported, then the
1223 CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be
1224 true and the feature must be defined by the corresponding
1225 CMAKE_LINK_GROUP_USING_<FEATURE> variable.
1226 The LINK_GROUP generator expression is compatible with the
1228 LINK_LIBRARY generator expression. The libraries involved in a
1229 group can be specified using the LINK_LIBRARY generator expres‐
1230 sion.
1231 Each target or external library involved in the link step is al‐
1233 lowed to be part of multiple groups, but only if all the groups
1234 involved specify the same feature. Such groups will not be
1235 merged on the linker command line, the individual groups will
1236 still be preserved. Mixing different group features for the
1237 same target or library is forbidden.
1238 add_library(lib1 ...)
1240 add_library(lib2 ...)
1241 add_library(lib3 ...)
1242 add_library(lib4 ...)
1243 add_library(lib5 ...)
1244 target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
1246 target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
1247 # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
1248 # Both groups specify the same feature, so this is fine.
1249 target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
1251 # An error will be raised here because both lib1 and lib3 are part of two
1252 # groups with different features.
1253 When a target or an external library is involved in the link
1255 step as part of a group and also as not part of any group, any
1256 occurrence of the non-group link item will be replaced by the
1257 groups it belongs to.
1258 add_library(lib1 ...)
1260 add_library(lib2 ...)
1261 add_library(lib3 ...)
1262 add_library(lib4 ...)
1263 target_link_libraries(lib3 PUBLIC lib1)
1265 target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
1267 # lib4 will only be linked with lib3 and the group {lib1,lib2}
1268 Because lib1 is part of the group defined for lib4, that group
1270 then gets applied back to the use of lib1 for lib3. The end re‐
1271 sult will be as though the linking relationship for lib3 had
1272 been specified as:
1273 target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
1275 Be aware that the precedence of the group over the non-group
1277 link item can result in circular dependencies between groups.
1278 If this occurs, a fatal error is raised because circular depen‐
1279 dencies are not allowed for groups.
1280 add_library(lib1A ...)
1282 add_library(lib1B ...)
1283 add_library(lib2A ...)
1284 add_library(lib2B ...)
1285 add_library(lib3 ...)
1286 # Non-group linking relationships, these are non-circular so far
1288 target_link_libraries(lib1A PUBLIC lib2A)
1289 target_link_libraries(lib2B PUBLIC lib1B)
1290 # The addition of these groups creates circular dependencies
1292 target_link_libraries(lib3 PRIVATE
1293 "$<LINK_GROUP:feat,lib1A,lib1B>"
1294 "$<LINK_GROUP:feat,lib2A,lib2B>"
1295 )
1296 Because of the groups defined for lib3, the linking relation‐
1298 ships for lib1A and lib2B effectively get expanded to the equiv‐
1299 alent of:
1300 target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
1302 target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
1303 This creates a circular dependency between groups: lib1A -->
1305 lib2B --> lib1A.
1306 The following limitations should also be noted:
1308 • The library-list can specify CMake targets or libraries. Any
1310 CMake target of type OBJECT or INTERFACE will ignore the fea‐
1311 ture aspect of the expression and instead be linked in the
1312 standard way.
1313 • The $<LINK_GROUP:...> generator expression can only be used to
1315 specify link libraries. In practice, this means it can appear
1316 in the LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES,and
1317 INTERFACE_LINK_LIBRARIES_DIRECT target properties, and be
1318 specified in target_link_libraries() and link_libraries() com‐
1319 mands.
1320 • If a $<LINK_GROUP:...> generator expression appears in the
1322 INTERFACE_LINK_LIBRARIES property of a target, it will be in‐
1323 cluded in the imported target generated by a install(EXPORT)
1324 command. It is the responsibility of the environment consum‐
1325 ing this import to define the link feature used by this ex‐
1326 pression.
1327 Link Context
1329 $<LINK_ONLY:...>
1330 New in version 3.1.
1331 Content of ..., except while collecting Transitive Usage Re‐
1334 quirements, in which case it is the empty string. This is in‐
1335 tended for use in an INTERFACE_LINK_LIBRARIES target property,
1336 typically populated via the target_link_libraries() command, to
1337 specify private link dependencies without other usage require‐
1338 ments.
1339 New in version 3.24: LINK_ONLY may also be used in a
1341 LINK_LIBRARIES target property. See policy CMP0131.
1342 $<DEVICE_LINK:list>
1345 New in version 3.18.
1346 Returns the list if it is the device link step, an empty list
1349 otherwise. The device link step is controlled by
1350 CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS prop‐
1351 erties and policy CMP0105. This expression can only be used to
1352 specify link options.
1353 $<HOST_LINK:list>
1355 New in version 3.18.
1356 Returns the list if it is the normal link step, an empty list
1359 otherwise. This expression is mainly useful when a device link
1360 step is also involved (see $<DEVICE_LINK:list> generator expres‐
1361 sion). This expression can only be used to specify link options.
1362 Target-Dependent Expressions
1364 These queries refer to a target tgt. Unless otherwise stated, this can
1365 be any runtime artifact, namely:
1366 • An executable target created by add_executable().
1368 • A shared library target (.so, .dll but not their .lib import library)
1370 created by add_library().
1371 • A static library target created by add_library().
1373 In the following, the phrase "the tgt filename" means the name of the
1375 tgt binary file. This has to be distinguished from the phrase "the tar‐
1376 get name", which is just the string tgt.
1377 $<TARGET_EXISTS:tgt>
1379 New in version 3.12.
1380 1 if tgt exists as a CMake target, else 0.
1383 $<TARGET_NAME_IF_EXISTS:tgt>
1385 New in version 3.12.
1386 The target name tgt if the target exists, an empty string other‐
1389 wise.
1390 Note that tgt is not added as a dependency of the target this
1392 expression is evaluated on.
1393 $<TARGET_NAME:...>
1395 Marks ... as being the name of a target. This is required if
1396 exporting targets to multiple dependent export sets. The ...
1397 must be a literal name of a target, it may not contain generator
1398 expressions.
1399 $<TARGET_PROPERTY:tgt,prop>
1401 Value of the property prop on the target tgt.
1402 Note that tgt is not added as a dependency of the target this
1404 expression is evaluated on.
1405 $<TARGET_PROPERTY:prop>
1407 Value of the property prop on the target for which the expres‐
1408 sion is being evaluated. Note that for generator expressions in
1409 Transitive Usage Requirements this is the consuming target
1410 rather than the target specifying the requirement.
1411 $<TARGET_OBJECTS:tgt>
1413 New in version 3.1.
1414 List of objects resulting from building tgt. This would typi‐
1417 cally be used on object library targets.
1418 $<TARGET_POLICY:policy>
1420 1 if the policy was NEW when the 'head' target was created, else
1421 0. If the policy was not set, the warning message for the pol‐
1422 icy will be emitted. This generator expression only works for a
1423 subset of policies.
1424 $<TARGET_FILE:tgt>
1426 Full path to the tgt binary file.
1427 Note that tgt is not added as a dependency of the target this
1429 expression is evaluated on, unless the expression is being used
1430 in add_custom_command() or add_custom_target().
1431 $<TARGET_FILE_BASE_NAME:tgt>
1433 New in version 3.15.
1434 Base name of tgt, i.e. $<TARGET_FILE_NAME:tgt> without prefix
1437 and suffix. For example, if the tgt filename is libbase.so, the
1438 base name is base.
1439 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
1441 LIBRARY_OUTPUT_NAME and RUNTIME_OUTPUT_NAME target properties
1442 and their configuration specific variants OUTPUT_NAME_<CONFIG>,
1443 ARCHIVE_OUTPUT_NAME_<CONFIG>, LIBRARY_OUTPUT_NAME_<CONFIG> and
1444 RUNTIME_OUTPUT_NAME_<CONFIG>.
1445 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1447 also be considered.
1448 Note that tgt is not added as a dependency of the target this
1450 expression is evaluated on.
1451 $<TARGET_FILE_PREFIX:tgt>
1453 New in version 3.15.
1454 Prefix of the tgt filename (such as lib).
1457 See also the PREFIX target property.
1459 Note that tgt is not added as a dependency of the target this
1461 expression is evaluated on.
1462 $<TARGET_FILE_SUFFIX:tgt>
1464 New in version 3.15.
1465 Suffix of the tgt filename (extension such as .so or .exe).
1468 See also the SUFFIX target property.
1470 Note that tgt is not added as a dependency of the target this
1472 expression is evaluated on.
1473 $<TARGET_FILE_NAME:tgt>
1475 The tgt filename.
1476 Note that tgt is not added as a dependency of the target this
1478 expression is evaluated on (see policy CMP0112).
1479 $<TARGET_FILE_DIR:tgt>
1481 Directory of the tgt binary file.
1482 Note that tgt is not added as a dependency of the target this
1484 expression is evaluated on (see policy CMP0112).
1485 $<TARGET_LINKER_FILE:tgt>
1487 File used when linking to the tgt target. This will usually be
1488 the library that tgt represents (.a, .lib, .so), but for a
1489 shared library on DLL platforms, it would be the .lib import li‐
1490 brary associated with the DLL.
1491 $<TARGET_LINKER_FILE_BASE_NAME:tgt>
1493 New in version 3.15.
1494 Base name of file used to link the target tgt, i.e. $<TAR‐
1497 GET_LINKER_FILE_NAME:tgt> without prefix and suffix. For exam‐
1498 ple, if target file name is libbase.a, the base name is base.
1499 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, and
1501 LIBRARY_OUTPUT_NAME target properties and their configuration
1502 specific variants OUTPUT_NAME_<CONFIG>,
1503 ARCHIVE_OUTPUT_NAME_<CONFIG> and LIBRARY_OUTPUT_NAME_<CONFIG>.
1504 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1506 also be considered.
1507 Note that tgt is not added as a dependency of the target this
1509 expression is evaluated on.
1510 $<TARGET_LINKER_FILE_PREFIX:tgt>
1512 New in version 3.15.
1513 Prefix of file used to link target tgt.
1516 See also the PREFIX and IMPORT_PREFIX target properties.
1518 Note that tgt is not added as a dependency of the target this
1520 expression is evaluated on.
1521 $<TARGET_LINKER_FILE_SUFFIX:tgt>
1523 New in version 3.15.
1524 Suffix of file used to link where tgt is the name of a target.
1527 The suffix corresponds to the file extension (such as ".so" or
1529 ".lib").
1530 See also the SUFFIX and IMPORT_SUFFIX target properties.
1532 Note that tgt is not added as a dependency of the target this
1534 expression is evaluated on.
1535 $<TARGET_LINKER_FILE_NAME:tgt>
1537 Name of file used to link target tgt.
1538 Note that tgt is not added as a dependency of the target this
1540 expression is evaluated on (see policy CMP0112).
1541 $<TARGET_LINKER_FILE_DIR:tgt>
1543 Directory of file used to link target tgt.
1544 Note that tgt is not added as a dependency of the target this
1546 expression is evaluated on (see policy CMP0112).
1547 $<TARGET_SONAME_FILE:tgt>
1549 File with soname (.so.3) where tgt is the name of a target.
1550 $<TARGET_SONAME_FILE_NAME:tgt>
1552 Name of file with soname (.so.3).
1553 Note that tgt is not added as a dependency of the target this
1555 expression is evaluated on (see policy CMP0112).
1556 $<TARGET_SONAME_FILE_DIR:tgt>
1558 Directory of with soname (.so.3).
1559 Note that tgt is not added as a dependency of the target this
1561 expression is evaluated on (see policy CMP0112).
1562 $<TARGET_PDB_FILE:tgt>
1564 New in version 3.1.
1565 Full path to the linker generated program database file (.pdb)
1568 where tgt is the name of a target.
1569 See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
1571 and their configuration specific variants PDB_NAME_<CONFIG> and
1572 PDB_OUTPUT_DIRECTORY_<CONFIG>.
1573 $<TARGET_PDB_FILE_BASE_NAME:tgt>
1575 New in version 3.15.
1576 Base name of the linker generated program database file (.pdb)
1579 where tgt is the name of a target.
1580 The base name corresponds to the target PDB file name (see
1582 $<TARGET_PDB_FILE_NAME:tgt>) without prefix and suffix. For ex‐
1583 ample, if target file name is base.pdb, the base name is base.
1584 See also the PDB_NAME target property and its configuration spe‐
1586 cific variant PDB_NAME_<CONFIG>.
1587 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1589 also be considered.
1590 Note that tgt is not added as a dependency of the target this
1592 expression is evaluated on.
1593 $<TARGET_PDB_FILE_NAME:tgt>
1595 New in version 3.1.
1596 Name of the linker generated program database file (.pdb).
1599 Note that tgt is not added as a dependency of the target this
1601 expression is evaluated on (see policy CMP0112).
1602 $<TARGET_PDB_FILE_DIR:tgt>
1604 New in version 3.1.
1605 Directory of the linker generated program database file (.pdb).
1608 Note that tgt is not added as a dependency of the target this
1610 expression is evaluated on (see policy CMP0112).
1611 $<TARGET_BUNDLE_DIR:tgt>
1613 New in version 3.9.
1614 Full path to the bundle directory (/path/to/my.app,
1617 /path/to/my.framework, or /path/to/my.bundle), where tgt is the
1618 name of a target.
1619 Note that tgt is not added as a dependency of the target this
1621 expression is evaluated on (see policy CMP0112).
1622 $<TARGET_BUNDLE_DIR_NAME:tgt>
1624 New in version 3.24.
1625 Name of the bundle directory (my.app, my.framework, or my.bun‐
1628 dle), where tgt is the name of a target.
1629 Note that tgt is not added as a dependency of the target this
1631 expression is evaluated on (see policy CMP0112).
1632 $<TARGET_BUNDLE_CONTENT_DIR:tgt>
1634 New in version 3.9.
1635 Full path to the bundle content directory where tgt is the name
1638 of a target. For the macOS SDK it leads to /path/to/my.app/Con‐
1639 tents, /path/to/my.framework, or /path/to/my.bundle/Contents.
1640 For all other SDKs (e.g. iOS) it leads to /path/to/my.app,
1641 /path/to/my.framework, or /path/to/my.bundle due to the flat
1642 bundle structure.
1643 Note that tgt is not added as a dependency of the target this
1645 expression is evaluated on (see policy CMP0112).
1646 $<TARGET_RUNTIME_DLLS:tgt>
1648 New in version 3.21.
1649 List of DLLs that the target depends on at runtime. This is de‐
1652 termined by the locations of all the SHARED targets in the tar‐
1653 get's transitive dependencies. Using this generator expression
1654 on targets other than executables, SHARED libraries, and MODULE
1655 libraries is an error. On non-DLL platforms, this expression
1656 always evaluates to an empty string.
1657 This generator expression can be used to copy all of the DLLs
1659 that a target depends on into its output directory in a
1660 POST_BUILD custom command. For example:
1661 find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
1663 add_executable(exe main.c)
1665 target_link_libraries(exe PRIVATE foo::foo foo::bar)
1666 add_custom_command(TARGET exe POST_BUILD
1667 COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
1668 COMMAND_EXPAND_LISTS
1669 )
1670 NOTE:
1672 Imported Targets are supported only if they know the location
1673 of their .dll files. An imported SHARED library must have
1674 IMPORTED_LOCATION set to its .dll file. See the add_library
1675 imported libraries section for details. Many Find Modules
1676 produce imported targets with the UNKNOWN type and therefore
1677 will be ignored.
1678 Export And Install Expressions
1680 $<INSTALL_INTERFACE:...>
1681 Content of ... when the property is exported using
1682 install(EXPORT), and empty otherwise.
1683 $<BUILD_INTERFACE:...>
1685 Content of ... when the property is exported using export(), or
1686 when the target is used by another target in the same buildsys‐
1687 tem. Expands to the empty string otherwise.
1688 $<INSTALL_PREFIX>
1690 Content of the install prefix when the target is exported via
1691 install(EXPORT), or when evaluated in the INSTALL_NAME_DIR prop‐
1692 erty or the INSTALL_NAME_DIR argument of
1693 install(RUNTIME_DEPENDENCY_SET), and empty otherwise.
1694 Multi-level Expression Evaluation
1696 $<GENEX_EVAL:expr>
1697 New in version 3.12.
1698 Content of expr evaluated as a generator expression in the cur‐
1701 rent context. This enables consumption of generator expressions
1702 whose evaluation results itself in generator expressions.
1703 $<TARGET_GENEX_EVAL:tgt,expr>
1705 New in version 3.12.
1706 Content of expr evaluated as a generator expression in the con‐
1709 text of tgt target. This enables consumption of custom target
1710 properties that themselves contain generator expressions.
1711 Having the capability to evaluate generator expressions is very
1713 useful when you want to manage custom properties supporting gen‐
1714 erator expressions. For example:
1715 add_library(foo ...)
1717 set_property(TARGET foo PROPERTY
1719 CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
1720 )
1721 add_custom_target(printFooKeys
1723 COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
1724 )
1725 This naive implementation of the printFooKeys custom command is
1727 wrong because CUSTOM_KEYS target property is not evaluated and
1728 the content is passed as is (i.e. $<$<CONFIG:DEBUG>:FOO_EX‐
1729 TRA_THINGS>).
1730 To have the expected result (i.e. FOO_EXTRA_THINGS if config is
1732 Debug), it is required to evaluate the output of $<TARGET_PROP‐
1733 ERTY:foo,CUSTOM_KEYS>:
1734 add_custom_target(printFooKeys
1736 COMMAND ${CMAKE_COMMAND} -E
1737 echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
1738 )
1739 Escaped Characters
1741 These expressions evaluate to specific string literals. Use them in
1742 place of the actual string literal where you need to prevent them from
1743 having their special meaning.
1744 $<ANGLE-R>
1746 A literal >. Used for example to compare strings that contain a
1747 >.
1748 $<COMMA>
1750 A literal ,. Used for example to compare strings which contain a
1751 ,.
1752 $<SEMICOLON>
1754 A literal ;. Used to prevent list expansion on an argument with
1755 ;.
1756 Deprecated Expressions
1758 $<CONFIGURATION>
1759 Configuration name. Deprecated since CMake 3.0. Use CONFIG in‐
1760 stead.
1761
1763 2000-2023 Kitware, Inc. and Contributors
17643.25.2 Jan 19, 2023 CMAKE-GENERATOR-EXPRESSIONS(7)