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 Finally, the above example can be expressed in a more simple and robust
89 way using an alternate generator expression:
90 add_custom_target(run_some_tool
92 COMMAND some_tool "$<LIST:TRANSFORM,$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,PREPEND,-I>"
93 COMMAND_EXPAND_LISTS
94 VERBATIM
95 )
96 A common mistake is to try to split a generator expression across mul‐
98 tiple lines with indenting:
99 # WRONG: New lines and spaces all treated as argument separators, so the
101 # generator expression is split and not recognized correctly.
102 target_compile_definitions(tgt PRIVATE
103 $<$<AND:
104 $<CXX_COMPILER_ID:GNU>,
105 $<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
106 >:HAVE_5_OR_LATER>
107 )
108 Again, use helper variables with well-chosen names to build up a read‐
110 able expression instead:
111 set(is_gnu "$<CXX_COMPILER_ID:GNU>")
113 set(v5_or_later "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>")
114 set(meet_requirements "$<AND:${is_gnu},${v5_or_later}>")
115 target_compile_definitions(tgt PRIVATE
116 "$<${meet_requirements}:HAVE_5_OR_LATER>"
117 )
118
120 Since generator expressions are evaluated during generation of the
121 buildsystem, and not during processing of CMakeLists.txt files, it is
122 not possible to inspect their result with the message() command. One
123 possible way to generate debug messages is to add a custom target:
124 add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
126 After running cmake, you can then build the genexdebug target to print
128 the result of the $<...> expression (i.e. run the command cmake --build
129 ... --target genexdebug).
130 Another way is to write debug messages to a file with file(GENERATE):
132 file(GENERATE OUTPUT filename CONTENT "$<...>")
134
136 NOTE:
137 This reference deviates from most of the CMake documentation in that
138 it omits angular brackets <...> around placeholders like condition,
139 string, target, etc. This is to prevent an opportunity for those
140 placeholders to be misinterpreted as generator expressions.
141 Conditional Expressions
143 A fundamental category of generator expressions relates to conditional
144 logic. Two forms of conditional generator expressions are supported:
145 $<condition:true_string>
147 Evaluates to true_string if condition is 1, or an empty string
148 if condition evaluates to 0. Any other value for condition re‐
149 sults in an error.
150 $<IF:condition,true_string,false_string>
152 New in version 3.8.
153 Evaluates to true_string if condition is 1, or false_string if
156 condition is 0. Any other value for condition results in an er‐
157 ror.
158 Typically, the condition is itself a generator expression. For in‐
160 stance, the following expression expands to DEBUG_MODE when the Debug
161 configuration is used, and the empty string for all other configura‐
162 tions:
163 $<$<CONFIG:Debug>:DEBUG_MODE>
165 Boolean-like condition values other than 1 or 0 can be handled by wrap‐
167 ping them with the $<BOOL:...> generator expression:
168 $<BOOL:string>
170 Converts string to 0 or 1. Evaluates to 0 if any of the follow‐
171 ing is true:
172 • string is empty,
174 • string is a case-insensitive equal of 0, FALSE, OFF, N, NO,
176 IGNORE, or NOTFOUND, or
177 • string ends in the suffix -NOTFOUND (case-sensitive).
179 Otherwise evaluates to 1.
181 The $<BOOL:...> generator expression is often used when a condition is
183 provided by a CMake variable:
184 $<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE>
186 Logical Operators
188 The common boolean logic operators are supported:
189 $<AND:conditions>
191 where conditions is a comma-separated list of boolean expres‐
192 sions, all of which must evaluate to either 1 or 0. The whole
193 expression evaluates to 1 if all conditions are 1. If any con‐
194 dition is 0, the whole expression evaluates to 0.
195 $<OR:conditions>
197 where conditions is a comma-separated list of boolean expres‐
198 sions. all of which must evaluate to either 1 or 0. The whole
199 expression evaluates to 1 if at least one of the conditions is
200 1. If all conditions evaluate to 0, the whole expression evalu‐
201 ates to 0.
202 $<NOT:condition>
204 condition must be 0 or 1. The result of the expression is 0 if
205 condition is 1, else 1.
206 Primary Comparison Expressions
208 CMake supports a variety of generator expressions that compare things.
209 This section covers the primary and most widely used comparison types.
210 Other more specific comparison types are documented in their own sepa‐
211 rate sections further below.
212 String Comparisons
214 $<STREQUAL:string1,string2>
215 1 if string1 and string2 are equal, else 0. The comparison is
216 case-sensitive. For a case-insensitive comparison, combine with
217 a string transforming generator expression. For example, the
218 following evaluates to 1 if ${foo} is any of BAR, Bar, bar, etc.
219 $<STREQUAL:$<UPPER_CASE:${foo}>,BAR>
221 $<EQUAL:value1,value2>
223 1 if value1 and value2 are numerically equal, else 0.
224 Version Comparisons
226 $<VERSION_LESS:v1,v2>
227 1 if v1 is a version less than v2, else 0.
228 $<VERSION_GREATER:v1,v2>
230 1 if v1 is a version greater than v2, else 0.
231 $<VERSION_EQUAL:v1,v2>
233 1 if v1 is the same version as v2, else 0.
234 $<VERSION_LESS_EQUAL:v1,v2>
236 New in version 3.7.
237 1 if v1 is a version less than or equal to v2, else 0.
240 $<VERSION_GREATER_EQUAL:v1,v2>
242 New in version 3.7.
243 1 if v1 is a version greater than or equal to v2, else 0.
246 String Transformations
248 $<LOWER_CASE:string>
249 Content of string converted to lower case.
250 $<UPPER_CASE:string>
252 Content of string converted to upper case.
253 $<MAKE_C_IDENTIFIER:...>
255 Content of ... converted to a C identifier. The conversion fol‐
256 lows the same behavior as string(MAKE_C_IDENTIFIER).
257 List Expressions
259 Most of the expressions in this section are closely associated with the
260 list() command, providing the same capabilities, but in the form of a
261 generator expression.
262 In each of the following list-related generator expressions, the list
264 must not contain any commas if that generator expression expects some‐
265 thing to be provided after the list. For example, the expression
266 $<LIST:FIND,list,value> requires a value after the list. Since a comma
267 is used to separate the list and the value, the list cannot itself con‐
268 tain a comma. This restriction does not apply to the list() command,
269 it is specific to the list-handling generator expressions only.
270 List Comparisons
272 $<IN_LIST:string,list>
273 New in version 3.12.
274 1 if string is an item in the semicolon-separated list, else 0.
277 It uses case-sensitive comparisons.
278 List Queries
280 $<LIST:LENGTH,list>
281 New in version 3.27.
282 The number of items in the list.
285 $<LIST:GET,list,index,...>
287 New in version 3.27.
288 Expands to the list of items specified by indices from the list.
291 $<LIST:SUBLIST,list,begin,length>
293 New in version 3.27.
294 A sublist of the given list. If length is 0, an empty list will
297 be returned. If length is -1 or the list is smaller than begin
298 + length, the remaining items of the list starting at begin will
299 be returned.
300 $<LIST:FIND,list,value>
302 New in version 3.27.
303 The index of the first item in list with the specified value, or
306 -1 if value is not in the list.
307 List Transformations
309 $<LIST:JOIN,list,glue>
310 New in version 3.27.
311 Converts list to a single string with the content of the glue
314 string inserted between each item. This is conceptually the
315 same operation as $<JOIN:list,glue>, but the two have different
316 behavior with regard to empty items. $<LIST:JOIN,list,glue>
317 preserves all empty items, whereas $<JOIN:list,glue> drops all
318 empty items from the list.
319 $<LIST:APPEND,list,item,...>
321 New in version 3.27.
322 The list with each item appended. Multiple items should be sep‐
325 arated by commas.
326 $<LIST:PREPEND,list,item,...>
328 New in version 3.27.
329 The list with each item inserted at the beginning. If there are
332 multiple items, they should be separated by commas, and the or‐
333 der of the prepended items will be preserved.
334 $<LIST:INSERT,list,index,item,...>
336 New in version 3.27.
337 The list with the item (or multiple items) inserted at the spec‐
340 ified index. Multiple items should be separated by commas.
341 It is an error to specify an out-of-range index. Valid indexes
343 are 0 to N, where N is the length of the list, inclusive. An
344 empty list has length 0.
345 $<LIST:POP_BACK,list>
347 New in version 3.27.
348 The list with the last item removed.
351 $<LIST:POP_FRONT,list>
353 New in version 3.27.
354 The list with the first item removed.
357 $<LIST:REMOVE_ITEM,list,value,...>
359 New in version 3.27.
360 The list with all instances of the given value (or values) re‐
363 moved. If multiple values are given, they should be separated
364 by commas.
365 $<LIST:REMOVE_AT,list,index,...>
367 New in version 3.27.
368 The list with the item at each given index removed.
371 $<LIST:REMOVE_DUPLICATES,list>
373 New in version 3.27.
374 The list with all duplicated items removed. The relative order
377 of items is preserved, but if duplicates are encountered, only
378 the first instance is preserved. The result is the same as
379 $<REMOVE_DUPLICATES:list>.
380 $<LIST:FILTER,list,INCLUDE|EXCLUDE,regex>
382 New in version 3.27.
383 A list of items from the list which match (INCLUDE) or do not
386 match (EXCLUDE) the regular expression regex. The result is the
387 same as $<FILTER:list,INCLUDE|EXCLUDE,regex>.
388 $<LIST:TRANSFORM,list,ACTION[,SELECTOR]>
390 New in version 3.27.
391 The list transformed by applying an ACTION to all or, by speci‐
394 fying a SELECTOR, to the selected list items.
395 NOTE:
397 The TRANSFORM sub-command does not change the number of items
398 in the list. If a SELECTOR is specified, only some items will
399 be changed, the other ones will remain the same as before the
400 transformation.
401 ACTION specifies the action to apply to the items of the list.
403 The actions have exactly the same semantics as for the
404 list(TRANSFORM) command. ACTION must be one of the following:
405 APPEND, PREPEND
407 Append, prepend specified value to each item of the
408 list.
409 $<LIST:TRANSFORM,list,(APPEND|PREPEND),value[,SELECTOR]>
411 TOLOWER, TOUPPER
413 Convert each item of the list to lower, upper charac‐
414 ters.
415 $<LIST:TRANSFORM,list,(TOLOWER|TOUPPER)[,SELECTOR]>
417 STRIP Remove leading and trailing spaces from each item of
419 the list.
420 $<LIST:TRANSFORM,list,STRIP[,SELECTOR]>
422 REPLACE:
424 Match the regular expression as many times as possible
425 and substitute the replacement expression for the
426 match for each item of the list.
427 $<LIST:TRANSFORM,list,REPLACE,regular_expression,replace_expression[,SELECTOR]>
429 SELECTOR determines which items of the list will be transformed.
431 Only one type of selector can be specified at a time. When
432 given, SELECTOR must be one of the following:
433 AT Specify a list of indexes.
435 $<LIST:TRANSFORM,list,ACTION,AT,index[,index...]>
437 FOR Specify a range with, optionally, an increment used to
439 iterate over the range.
440 $<LIST:TRANSFORM,list,ACTION,FOR,start,stop[,step]>
442 REGEX Specify a regular expression. Only items matching the
444 regular expression will be transformed.
445 $<LIST:TRANSFORM,list,ACTION,REGEX,regular_expression>
447 $<JOIN:list,glue>
449 Joins the list with the content of the glue string inserted be‐
450 tween each item. This is conceptually the same operation as
451 $<LIST:JOIN,list,glue>, but the two have different behavior with
452 regard to empty items. $<LIST:JOIN,list,glue> preserves all
453 empty items, whereas $<JOIN,list,glue> drops all empty items
454 from the list.
455 $<REMOVE_DUPLICATES:list>
457 New in version 3.15.
458 Removes duplicated items in the given list. The relative order
461 of items is preserved, and if duplicates are encountered, only
462 the first instance is retained. The result is the same as
463 $<LIST:REMOVE_DUPLICATES,list>.
464 $<FILTER:list,INCLUDE|EXCLUDE,regex>
466 New in version 3.15.
467 Includes or removes items from list that match the regular ex‐
470 pression regex. The result is the same as
471 $<LIST:FILTER,list,INCLUDE|EXCLUDE,regex>.
472 List Ordering
474 $<LIST:REVERSE,list>
475 New in version 3.27.
476 The list with the items in reverse order.
479 $<LIST:SORT,list[,(COMPARE:option|CASE:option|ORDER:option)]...>
481 New in version 3.27.
482 The list sorted according to the specified options.
485 Use one of the COMPARE options to select the comparison method
487 for sorting:
488 STRING Sorts a list of strings alphabetically. This is the
490 default behavior if the COMPARE option is not given.
491 FILE_BASENAME
493 Sorts a list of file paths by their basenames.
494 NATURAL
496 Sorts a list of strings using natural order (see the
497 man page for strverscmp(3)), such that contiguous dig‐
498 its are compared as whole numbers. For example, the
499 following list 10.0 1.1 2.1 8.0 2.0 3.1 will be sorted
500 as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL comparison
501 is selected, whereas it will be sorted as 1.1 10.0 2.0
502 2.1 3.1 8.0 with the STRING comparison.
503 Use one of the CASE options to select a case-sensitive or
505 case-insensitive sort mode:
506 SENSITIVE
508 List items are sorted in a case-sensitive manner.
509 This is the default behavior if the CASE option is not
510 given.
511 INSENSITIVE
513 List items are sorted in a case-insensitive manner.
514 The order of items which differ only by upper/lower‐
515 case is not specified.
516 To control the sort order, one of the ORDER options can be
518 given:
519 ASCENDING
521 Sorts the list in ascending order. This is the de‐
522 fault behavior when the ORDER option is not given.
523 DESCENDING
525 Sorts the list in descending order.
526 Options can be specified in any order, but it is an error to
528 specify the same option multiple times.
529 $<LIST:SORT,list,CASE:SENSITIVE,COMPARE:STRING,ORDER:DESCENDING>
531 Path Expressions
533 Most of the expressions in this section are closely associated with the
534 cmake_path() command, providing the same capabilities, but in the form
535 of a generator expression.
536 For all generator expressions in this section, paths are expected to be
538 in cmake-style format. The $<PATH:CMAKE_PATH> generator expression can
539 be used to convert a native path to a cmake-style one.
540 Path Comparisons
542 $<PATH_EQUAL:path1,path2>
543 New in version 3.24.
544 Compares the lexical representations of two paths. No normaliza‐
547 tion is performed on either path. Returns 1 if the paths are
548 equal, 0 otherwise.
549 See cmake_path(COMPARE) for more details.
551 Path Queries
553 These expressions provide the generation-time capabilities equivalent
554 to the Query options of the cmake_path() command. All paths are ex‐
555 pected to be in cmake-style format.
556 $<PATH:HAS_*,path>
558 New in version 3.24.
559 The following operations return 1 if the particular path compo‐
562 nent is present, 0 otherwise. See Path Structure And Terminology
563 for the meaning of each path component.
564 $<PATH:HAS_ROOT_NAME,path>
566 $<PATH:HAS_ROOT_DIRECTORY,path>
567 $<PATH:HAS_ROOT_PATH,path>
568 $<PATH:HAS_FILENAME,path>
569 $<PATH:HAS_EXTENSION,path>
570 $<PATH:HAS_STEM,path>
571 $<PATH:HAS_RELATIVE_PART,path>
572 $<PATH:HAS_PARENT_PATH,path>
573 Note the following special cases:
575 • For HAS_ROOT_PATH, a true result will only be returned if at
577 least one of root-name or root-directory is non-empty.
578 • For HAS_PARENT_PATH, the root directory is also considered to
580 have a parent, which will be itself. The result is true ex‐
581 cept if the path consists of just a filename.
582 $<PATH:IS_ABSOLUTE,path>
584 New in version 3.24.
585 Returns 1 if the path is absolute, 0 otherwise.
588 $<PATH:IS_RELATIVE,path>
590 New in version 3.24.
591 This will return the opposite of IS_ABSOLUTE.
594 $<PATH:IS_PREFIX[,NORMALIZE],path,input>
596 New in version 3.24.
597 Returns 1 if path is the prefix of input, 0 otherwise.
600 When the NORMALIZE option is specified, path and input are
602 normalized before the check.
603 Path Decomposition
605 These expressions provide the generation-time capabilities equivalent
606 to the Decomposition options of the cmake_path() command. All paths
607 are expected to be in cmake-style format.
608 $<PATH:GET_*,...>
610 New in version 3.24.
611 The following operations retrieve a different component or group
614 of components from a path. See Path Structure And Terminology
615 for the meaning of each path component.
616 Changed in version 3.27: All operations now accept a list of
618 paths as argument. When a list of paths is specified, the opera‐
619 tion will be applied to each path.
620 $<PATH:GET_ROOT_NAME,path...>
623 $<PATH:GET_ROOT_DIRECTORY,path...>
624 $<PATH:GET_ROOT_PATH,path...>
625 $<PATH:GET_FILENAME,path...>
626 $<PATH:GET_EXTENSION[,LAST_ONLY],path...>
627 $<PATH:GET_STEM[,LAST_ONLY],path...>
628 $<PATH:GET_RELATIVE_PART,path...>
629 $<PATH:GET_PARENT_PATH,path...>
630 If a requested component is not present in the path, an empty
632 string is returned.
633 Path Transformations
635 These expressions provide the generation-time capabilities equivalent
636 to the Modification and Generation options of the cmake_path() command.
637 All paths are expected to be in cmake-style format.
638 Changed in version 3.27: All operations now accept a list of paths as
640 argument. When a list of paths is specified, the operation will be ap‐
641 plied to each path.
642 $<PATH:CMAKE_PATH[,NORMALIZE],path...>
645 New in version 3.24.
646 Returns path. If path is a native path, it is converted into a
649 cmake-style path with forward-slashes (/). On Windows, the long
650 filename marker is taken into account.
651 When the NORMALIZE option is specified, the path is normalized
653 after the conversion.
654 $<PATH:APPEND,path...,input,...>
656 New in version 3.24.
657 Returns all the input arguments appended to path using / as the
660 directory-separator. Depending on the input, the value of path
661 may be discarded.
662 See cmake_path(APPEND) for more details.
664 $<PATH:REMOVE_FILENAME,path...>
666 New in version 3.24.
667 Returns path with filename component (as returned by
670 $<PATH:GET_FILENAME>) removed. After removal, any trailing di‐
671 rectory-separator is left alone, if present.
672 See cmake_path(REMOVE_FILENAME) for more details.
674 $<PATH:REPLACE_FILENAME,path...,input>
676 New in version 3.24.
677 Returns path with the filename component replaced by input. If
680 path has no filename component (i.e. $<PATH:HAS_FILENAME> re‐
681 turns 0), path is unchanged.
682 See cmake_path(REPLACE_FILENAME) for more details.
684 $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...>
686 New in version 3.24.
687 Returns path with the extension removed, if any.
690 See cmake_path(REMOVE_EXTENSION) for more details.
692 $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input>
694 New in version 3.24.
695 Returns path with the extension replaced by input, if any.
698 See cmake_path(REPLACE_EXTENSION) for more details.
700 $<PATH:NORMAL_PATH,path...>
702 New in version 3.24.
703 Returns path normalized according to the steps described in
706 Normalization.
707 $<PATH:RELATIVE_PATH,path...,base_directory>
709 New in version 3.24.
710 Returns path, modified to make it relative to the base_directory
713 argument.
714 See cmake_path(RELATIVE_PATH) for more details.
716 $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory>
718 New in version 3.24.
719 Returns path as absolute. If path is a relative path
722 ($<PATH:IS_RELATIVE> returns 1), it is evaluated relative to the
723 given base directory specified by base_directory argument.
724 When the NORMALIZE option is specified, the path is normalized
726 after the path computation.
727 See cmake_path(ABSOLUTE_PATH) for more details.
729 Shell Paths
731 $<SHELL_PATH:...>
732 New in version 3.4.
733 Content of ... converted to shell path style. For example,
736 slashes are converted to backslashes in Windows shells and drive
737 letters are converted to posix paths in MSYS shells. The ...
738 must be an absolute path.
739 New in version 3.14: The ... may be a semicolon-separated list
741 of paths, in which case each path is converted individually and
742 a result list is generated using the shell path separator (: on
743 POSIX and ; on Windows). Be sure to enclose the argument con‐
744 taining this genex in double quotes in CMake source code so that
745 ; does not split arguments.
746 Configuration Expressions
749 $<CONFIG>
750 Configuration name. Use this instead of the deprecated
751 CONFIGURATION generator expression.
752 $<CONFIG:cfgs>
754 1 if config is any one of the entries in comma-separated list
755 cfgs, else 0. This is a case-insensitive comparison. The mapping
756 in MAP_IMPORTED_CONFIG_<CONFIG> is also considered by this ex‐
757 pression when it is evaluated on a property of an IMPORTED tar‐
758 get.
759 Changed in version 3.19: Multiple configurations can be speci‐
761 fied for cfgs. CMake 3.18 and earlier only accepted a single
762 configuration.
763 $<OUTPUT_CONFIG:...>
766 New in version 3.20.
767 Only valid in add_custom_command() and add_custom_target() as
770 the outer-most generator expression in an argument. With the
771 Ninja Multi-Config generator, generator expressions in ... are
772 evaluated using the custom command's "output config". With
773 other generators, the content of ... is evaluated normally.
774 $<COMMAND_CONFIG:...>
776 New in version 3.20.
777 Only valid in add_custom_command() and add_custom_target() as
780 the outer-most generator expression in an argument. With the
781 Ninja Multi-Config generator, generator expressions in ... are
782 evaluated using the custom command's "command config". With
783 other generators, the content of ... is evaluated normally.
784 Toolchain And Language Expressions
786 Platform
787 $<PLATFORM_ID>
788 The current system's CMake platform id. See also the
789 CMAKE_SYSTEM_NAME variable.
790 $<PLATFORM_ID:platform_ids>
792 1 if CMake's platform id matches any one of the entries in
793 comma-separated list platform_ids, otherwise 0. See also the
794 CMAKE_SYSTEM_NAME variable.
795 Compiler Version
797 See also the CMAKE_<LANG>_COMPILER_VERSION variable, which is closely
798 related to the expressions in this sub-section.
799 $<C_COMPILER_VERSION>
801 The version of the C compiler used.
802 $<C_COMPILER_VERSION:version>
804 1 if the version of the C compiler matches version, otherwise 0.
805 $<CXX_COMPILER_VERSION>
807 The version of the CXX compiler used.
808 $<CXX_COMPILER_VERSION:version>
810 1 if the version of the CXX compiler matches version, otherwise
811 0.
812 $<CUDA_COMPILER_VERSION>
814 New in version 3.15.
815 The version of the CUDA compiler used.
818 $<CUDA_COMPILER_VERSION:version>
820 New in version 3.15.
821 1 if the version of the CXX compiler matches version, otherwise
824 0.
825 $<OBJC_COMPILER_VERSION>
827 New in version 3.16.
828 The version of the OBJC compiler used.
831 $<OBJC_COMPILER_VERSION:version>
833 New in version 3.16.
834 1 if the version of the OBJC compiler matches version, otherwise
837 0.
838 $<OBJCXX_COMPILER_VERSION>
840 New in version 3.16.
841 The version of the OBJCXX compiler used.
844 $<OBJCXX_COMPILER_VERSION:version>
846 New in version 3.16.
847 1 if the version of the OBJCXX compiler matches version, other‐
850 wise 0.
851 $<Fortran_COMPILER_VERSION>
853 The version of the Fortran compiler used.
854 $<Fortran_COMPILER_VERSION:version>
856 1 if the version of the Fortran compiler matches version, other‐
857 wise 0.
858 $<HIP_COMPILER_VERSION>
860 New in version 3.21.
861 The version of the HIP compiler used.
864 $<HIP_COMPILER_VERSION:version>
866 New in version 3.21.
867 1 if the version of the HIP compiler matches version, otherwise
870 0.
871 $<ISPC_COMPILER_VERSION>
873 New in version 3.19.
874 The version of the ISPC compiler used.
877 $<ISPC_COMPILER_VERSION:version>
879 New in version 3.19.
880 1 if the version of the ISPC compiler matches version, otherwise
883 0.
884 Compiler Language And ID
886 See also the CMAKE_<LANG>_COMPILER_ID variable, which is closely re‐
887 lated to most of the expressions in this sub-section.
888 $<C_COMPILER_ID>
890 CMake's compiler id of the C compiler used.
891 $<C_COMPILER_ID:compiler_ids>
893 where compiler_ids is a comma-separated list. 1 if CMake's com‐
894 piler id of the C compiler matches any one of the entries in
895 compiler_ids, otherwise 0.
896 $<CXX_COMPILER_ID>
898 CMake's compiler id of the CXX compiler used.
899 $<CXX_COMPILER_ID:compiler_ids>
901 where compiler_ids is a comma-separated list. 1 if CMake's com‐
902 piler id of the CXX compiler matches any one of the entries in
903 compiler_ids, otherwise 0.
904 $<CUDA_COMPILER_ID>
906 New in version 3.15.
907 CMake's compiler id of the CUDA compiler used.
910 $<CUDA_COMPILER_ID:compiler_ids>
912 New in version 3.15.
913 where compiler_ids is a comma-separated list. 1 if CMake's com‐
916 piler id of the CUDA compiler matches any one of the entries in
917 compiler_ids, otherwise 0.
918 $<OBJC_COMPILER_ID>
920 New in version 3.16.
921 CMake's compiler id of the OBJC compiler used.
924 $<OBJC_COMPILER_ID:compiler_ids>
926 New in version 3.16.
927 where compiler_ids is a comma-separated list. 1 if CMake's com‐
930 piler id of the Objective-C compiler matches any one of the en‐
931 tries in compiler_ids, otherwise 0.
932 $<OBJCXX_COMPILER_ID>
934 New in version 3.16.
935 CMake's compiler id of the OBJCXX compiler used.
938 $<OBJCXX_COMPILER_ID:compiler_ids>
940 New in version 3.16.
941 where compiler_ids is a comma-separated list. 1 if CMake's com‐
944 piler id of the Objective-C++ compiler matches any one of the
945 entries in compiler_ids, otherwise 0.
946 $<Fortran_COMPILER_ID>
948 CMake's compiler id of the Fortran compiler used.
949 $<Fortran_COMPILER_ID:compiler_ids>
951 where compiler_ids is a comma-separated list. 1 if CMake's com‐
952 piler id of the Fortran compiler matches any one of the entries
953 in compiler_ids, otherwise 0.
954 $<HIP_COMPILER_ID>
956 New in version 3.21.
957 CMake's compiler id of the HIP compiler used.
960 $<HIP_COMPILER_ID:compiler_ids>
962 New in version 3.21.
963 where compiler_ids is a comma-separated list. 1 if CMake's com‐
966 piler id of the HIP compiler matches any one of the entries in
967 compiler_ids, otherwise 0.
968 $<ISPC_COMPILER_ID>
970 New in version 3.19.
971 CMake's compiler id of the ISPC compiler used.
974 $<ISPC_COMPILER_ID:compiler_ids>
976 New in version 3.19.
977 where compiler_ids is a comma-separated list. 1 if CMake's com‐
980 piler id of the ISPC compiler matches any one of the entries in
981 compiler_ids, otherwise 0.
982 $<COMPILE_LANGUAGE>
984 New in version 3.3.
985 The compile language of source files when evaluating compile op‐
988 tions. See the related boolean expression $<COMPILE_LAN‐
989 GUAGE:language> for notes about the portability of this genera‐
990 tor expression.
991 $<COMPILE_LANGUAGE:languages>
993 New in version 3.3.
994 Changed in version 3.15: Multiple languages can be specified for
997 languages. CMake 3.14 and earlier only accepted a single lan‐
998 guage.
999 1 when the language used for compilation unit matches any of the
1002 comma-separated entries in languages, otherwise 0. This expres‐
1003 sion may be used to specify compile options, compile defini‐
1004 tions, and include directories for source files of a particular
1005 language in a target. For example:
1006 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
1008 target_compile_options(myapp
1009 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
1010 )
1011 target_compile_definitions(myapp
1012 PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
1013 $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
1014 )
1015 target_include_directories(myapp
1016 PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
1017 )
1018 This specifies the use of the -fno-exceptions compile option,
1020 COMPILING_CXX compile definition, and cxx_headers include direc‐
1021 tory for C++ only (compiler id checks elided). It also speci‐
1022 fies a COMPILING_CUDA compile definition for CUDA.
1023 Note that with Visual Studio Generators and Xcode there is no
1025 way to represent target-wide compile definitions or include di‐
1026 rectories separately for C and CXX languages. Also, with Visual
1027 Studio Generators there is no way to represent target-wide flags
1028 separately for C and CXX languages. Under these generators, ex‐
1029 pressions for both C and C++ sources will be evaluated using CXX
1030 if there are any C++ sources and otherwise using C. A work‐
1031 around is to create separate libraries for each source file lan‐
1032 guage instead:
1033 add_library(myapp_c foo.c)
1035 add_library(myapp_cxx bar.cpp)
1036 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
1037 add_executable(myapp main.cpp)
1038 target_link_libraries(myapp myapp_c myapp_cxx)
1039 $<COMPILE_LANG_AND_ID:language,compiler_ids>
1041 New in version 3.15.
1042 1 when the language used for compilation unit matches language
1045 and CMake's compiler id of the language compiler matches any one
1046 of the comma-separated entries in compiler_ids, otherwise 0.
1047 This expression is a short form for the combination of $<COM‐
1048 PILE_LANGUAGE:language> and $<LANG_COMPILER_ID:compiler_ids>.
1049 This expression may be used to specify compile options, compile
1050 definitions, and include directories for source files of a par‐
1051 ticular language and compiler combination in a target. For ex‐
1052 ample:
1053 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
1055 target_compile_definitions(myapp
1056 PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
1057 $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
1058 $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
1059 )
1060 This specifies the use of different compile definitions based on
1062 both the compiler id and compilation language. This example will
1063 have a COMPILING_CXX_WITH_CLANG compile definition when Clang is
1064 the CXX compiler, and COMPILING_CXX_WITH_INTEL when Intel is the
1065 CXX compiler. Likewise, when the C compiler is Clang, it will
1066 only see the COMPILING_C_WITH_CLANG definition.
1067 Without the COMPILE_LANG_AND_ID generator expression, the same
1069 logic would be expressed as:
1070 target_compile_definitions(myapp
1072 PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
1073 $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
1074 $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
1075 )
1076 Compile Features
1078 $<COMPILE_FEATURES:features>
1079 New in version 3.1.
1080 where features is a comma-separated list. Evaluates to 1 if all
1083 of the features are available for the 'head' target, and 0 oth‐
1084 erwise. If this expression is used while evaluating the link im‐
1085 plementation of a target and if any dependency transitively in‐
1086 creases the required C_STANDARD or CXX_STANDARD for the 'head'
1087 target, an error is reported. See the cmake-compile-features(7)
1088 manual for information on compile features and a list of sup‐
1089 ported compilers.
1090 Compile Context
1092 $<COMPILE_ONLY:...>
1093 New in version 3.27.
1094 Content of ..., when collecting Transitive Usage Requirements,
1097 otherwise it is the empty string. This is intended for use in
1098 an INTERFACE_LINK_LIBRARIES and LINK_LIBRARIES target proper‐
1099 ties, typically populated via the target_link_libraries() com‐
1100 mand. Provides compilation usage requirements without any link‐
1101 ing requirements.
1102 Use cases include header-only usage where all usages are known
1104 to not have linking requirements (e.g., all-inline or C++ tem‐
1105 plate libraries).
1106 Note that for proper evaluation of this expression requires pol‐
1108 icy CMP0099 to be set to NEW.
1109 Linker Language And ID
1111 $<LINK_LANGUAGE>
1112 New in version 3.18.
1113 The link language of the target when evaluating link options.
1116 See the related boolean expression $<LINK_LANGUAGE:languages>
1117 for notes about the portability of this generator expression.
1118 NOTE:
1120 This generator expression is not supported by the link li‐
1121 braries properties to avoid side-effects due to the double
1122 evaluation of these properties.
1123 $<LINK_LANGUAGE:languages>
1125 New in version 3.18.
1126 1 when the language used for link step matches any of the
1129 comma-separated entries in languages, otherwise 0. This expres‐
1130 sion may be used to specify link libraries, link options, link
1131 directories and link dependencies of a particular language in a
1132 target. For example:
1133 add_library(api_C ...)
1135 add_library(api_CXX ...)
1136 add_library(api INTERFACE)
1137 target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
1138 $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
1139 target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
1140 $<$<LINK_LANGUAGE:CXX>:api_CXX>)
1141 add_executable(myapp1 main.c)
1143 target_link_options(myapp1 PRIVATE api)
1144 add_executable(myapp2 main.cpp)
1146 target_link_options(myapp2 PRIVATE api)
1147 This specifies to use the api target for linking targets myapp1
1149 and myapp2. In practice, myapp1 will link with target api_C and
1150 option -opt_c because it will use C as link language. And myapp2
1151 will link with api_CXX and option -opt_cxx because CXX will be
1152 the link language.
1153 NOTE:
1155 To determine the link language of a target, it is required to
1156 collect, transitively, all the targets which will be linked
1157 to it. So, for link libraries properties, a double evaluation
1158 will be done. During the first evaluation, $<LINK_LAN‐
1159 GUAGE:..> expressions will always return 0. The link lan‐
1160 guage computed after this first pass will be used to do the
1161 second pass. To avoid inconsistency, it is required that the
1162 second pass do not change the link language. Moreover, to
1163 avoid unexpected side-effects, it is required to specify com‐
1164 plete entities as part of the $<LINK_LANGUAGE:..> expression.
1165 For example:
1166 add_library(lib STATIC file.cxx)
1168 add_library(libother STATIC file.c)
1169 # bad usage
1171 add_executable(myapp1 main.c)
1172 target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
1173 # correct usage
1175 add_executable(myapp2 main.c)
1176 target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
1177 In this example, for myapp1, the first pass will, unexpect‐
1179 edly, determine that the link language is CXX because the
1180 evaluation of the generator expression will be an empty
1181 string so myapp1 will depends on target lib which is C++. On
1182 the contrary, for myapp2, the first evaluation will give C as
1183 link language, so the second pass will correctly add target
1184 libother as link dependency.
1185 $<LINK_LANG_AND_ID:language,compiler_ids>
1187 New in version 3.18.
1188 1 when the language used for link step matches language and the
1191 CMake's compiler id of the language linker matches any one of
1192 the comma-separated entries in compiler_ids, otherwise 0. This
1193 expression is a short form for the combination of $<LINK_LAN‐
1194 GUAGE:language> and $<LANG_COMPILER_ID:compiler_ids>. This ex‐
1195 pression may be used to specify link libraries, link options,
1196 link directories and link dependencies of a particular language
1197 and linker combination in a target. For example:
1198 add_library(libC_Clang ...)
1200 add_library(libCXX_Clang ...)
1201 add_library(libC_Intel ...)
1202 add_library(libCXX_Intel ...)
1203 add_executable(myapp main.c)
1205 if (CXX_CONFIG)
1206 target_sources(myapp PRIVATE file.cxx)
1207 endif()
1208 target_link_libraries(myapp
1209 PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
1210 $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
1211 $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
1212 $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
1213 This specifies the use of different link libraries based on both
1215 the compiler id and link language. This example will have target
1216 libCXX_Clang as link dependency when Clang or AppleClang is the
1217 CXX linker, and libCXX_Intel when Intel is the CXX linker.
1218 Likewise when the C linker is Clang or AppleClang, target
1219 libC_Clang will be added as link dependency and libC_Intel when
1220 Intel is the C linker.
1221 See the note related to $<LINK_LANGUAGE:language> for con‐
1223 straints about the usage of this generator expression.
1224 Link Features
1226 $<LINK_LIBRARY:feature,library-list>
1227 New in version 3.24.
1228 Specify a set of libraries to link to a target, along with a
1231 feature which provides details about how they should be linked.
1232 For example:
1233 add_library(lib1 STATIC ...)
1235 add_library(lib2 ...)
1236 target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")
1237 This specifies that lib2 should link to lib1 and use the
1239 WHOLE_ARCHIVE feature when doing so.
1240 Feature names are case-sensitive and may only contain letters,
1242 numbers and underscores. Feature names defined in all uppercase
1243 are reserved for CMake's own built-in features. The pre-defined
1244 built-in library features are:
1245 DEFAULT
1247 This feature corresponds to standard linking, essentially
1248 equivalent to using no feature at all. It is typically
1249 only used with the LINK_LIBRARY_OVERRIDE and
1250 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
1251 WHOLE_ARCHIVE
1253 Force inclusion of all members of a static library. This
1254 feature is only supported for the following platforms,
1255 with limitations as noted:
1256 • Linux.
1258 • All BSD variants.
1260 • SunOS.
1262 • All Apple variants. The library must be specified as a
1264 CMake target name, a library file name (such as lib‐
1265 foo.a), or a library file path (such as /path/to/lib‐
1266 foo.a). Due to a limitation of the Apple linker, it
1267 cannot be specified as a plain library name like foo,
1268 where foo is not a CMake target.
1269 • Windows. When using a MSVC or MSVC-like toolchain, the
1271 MSVC version must be greater than 1900.
1272 • Cygwin.
1274 • MSYS.
1276 FRAMEWORK
1278 This option tells the linker to search for the specified
1279 framework using the -framework linker option. It can
1280 only be used on Apple platforms, and only with a linker
1281 that understands the option used (i.e. the linker pro‐
1282 vided with Xcode, or one compatible with it).
1283 The framework can be specified as a CMake framework tar‐
1285 get, a bare framework name, or a file path. If a target
1286 is given, that target must have the FRAMEWORK target
1287 property set to true. For a file path, if it contains a
1288 directory part, that directory will be added as a frame‐
1289 work search path.
1290 add_library(lib SHARED ...)
1292 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
1293 # The constructed linker command line will contain:
1295 # -F/path/to -framework my_framework
1296 File paths must conform to one of the following patterns
1298 (* is a wildcard, and optional parts are shown as [...]):
1299 • [/path/to/]FwName[.framework]
1301 • [/path/to/]FwName.framework/FwName[suffix]
1303 • [/path/to/]FwName.framework/Versions/*/FwName[suf‐
1305 fix]
1306 Note that CMake recognizes and automatically handles
1308 framework targets, even without using the
1309 $<LINK_LIBRARY:FRAMEWORK,...> expression. The generator
1310 expression can still be used with a CMake target if the
1311 project wants to be explicit about it, but it is not re‐
1312 quired to do so. The linker command line may have some
1313 differences between using the generator expression or
1314 not, but the final result should be the same. On the
1315 other hand, if a file path is given, CMake will recognize
1316 some paths automatically, but not all cases. The project
1317 may want to use $<LINK_LIBRARY:FRAMEWORK,...> for file
1318 paths so that the expected behavior is clear.
1319 New in version 3.25: The
1321 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property
1322 as well as the suffix of the framework library name are
1323 now supported by the FRAMEWORK features.
1324 NEEDED_FRAMEWORK
1327 This is similar to the FRAMEWORK feature, except it
1328 forces the linker to link with the framework even if no
1329 symbols are used from it. It uses the -needed_framework
1330 option and has the same linker constraints as FRAMEWORK.
1331 REEXPORT_FRAMEWORK
1333 This is similar to the FRAMEWORK feature, except it tells
1334 the linker that the framework should be available to
1335 clients linking to the library being created. It uses
1336 the -reexport_framework option and has the same linker
1337 constraints as FRAMEWORK.
1338 WEAK_FRAMEWORK
1340 This is similar to the FRAMEWORK feature, except it
1341 forces the linker to mark the framework and all refer‐
1342 ences to it as weak imports. It uses the -weak_framework
1343 option and has the same linker constraints as FRAMEWORK.
1344 NEEDED_LIBRARY
1346 This is similar to the NEEDED_FRAMEWORK feature, except
1347 it is for use with non-framework targets or libraries
1348 (Apple platforms only). It uses the -needed_library or
1349 -needed-l option as appropriate, and has the same linker
1350 constraints as NEEDED_FRAMEWORK.
1351 REEXPORT_LIBRARY
1353 This is similar to the REEXPORT_FRAMEWORK feature, ex‐
1354 cept it is for use with non-framework targets or li‐
1355 braries (Apple platforms only). It uses the -reex‐
1356 port_library or -reexport-l option as appropriate, and
1357 has the same linker constraints as REEXPORT_FRAMEWORK.
1358 WEAK_LIBRARY
1360 This is similar to the WEAK_FRAMEWORK feature, except it
1361 is for use with non-framework targets or libraries (Apple
1362 platforms only). It uses the -weak_library or -weak-l
1363 option as appropriate, and has the same linker con‐
1364 straints as WEAK_FRAMEWORK.
1365 Built-in and custom library features are defined in terms of the
1367 following variables:
1368 • CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
1370 • CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>
1372 • CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
1374 • CMAKE_LINK_LIBRARY_USING_<FEATURE>
1376 The value used for each of these variables is the value as set
1378 at the end of the directory scope in which the target was cre‐
1379 ated. The usage is as follows:
1380 1. If the language-specific
1382 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable
1383 is true, the feature must be defined by the corresponding
1384 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> variable.
1385 2. If no language-specific feature is supported, then the
1387 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable must be
1388 true and the feature must be defined by the corresponding
1389 CMAKE_LINK_LIBRARY_USING_<FEATURE> variable.
1390 The following limitations should be noted:
1392 • The library-list can specify CMake targets or libraries. Any
1394 CMake target of type OBJECT or INTERFACE will ignore the fea‐
1395 ture aspect of the expression and instead be linked in the
1396 standard way.
1397 • The $<LINK_LIBRARY:...> generator expression can only be used
1399 to specify link libraries. In practice, this means it can ap‐
1400 pear in the LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES, and
1401 INTERFACE_LINK_LIBRARIES_DIRECT target properties, and be
1402 specified in target_link_libraries() and link_libraries() com‐
1403 mands.
1404 • If a $<LINK_LIBRARY:...> generator expression appears in the
1406 INTERFACE_LINK_LIBRARIES property of a target, it will be in‐
1407 cluded in the imported target generated by a install(EXPORT)
1408 command. It is the responsibility of the environment consum‐
1409 ing this import to define the link feature used by this ex‐
1410 pression.
1411 • Each target or library involved in the link step must have at
1413 most only one kind of library feature. The absence of a fea‐
1414 ture is also incompatible with all other features. For exam‐
1415 ple:
1416 add_library(lib1 ...)
1418 add_library(lib2 ...)
1419 add_library(lib3 ...)
1420 # lib1 will be associated with feature1
1422 target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
1423 # lib1 is being linked with no feature here. This conflicts with the
1425 # use of feature1 in the line above and would result in an error.
1426 target_link_libraries(lib3 PRIVATE lib1 lib2)
1427 Where it isn't possible to use the same feature throughout a
1429 build for a given target or library, the LINK_LIBRARY_OVERRIDE
1430 and LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties can be
1431 used to resolve such incompatibilities.
1432 • The $<LINK_LIBRARY:...> generator expression does not guaran‐
1434 tee that the list of specified targets and libraries will be
1435 kept grouped together. To manage constructs like
1436 --start-group and --end-group, as supported by the GNU ld
1437 linker, use the LINK_GROUP generator expression instead.
1438 $<LINK_GROUP:feature,library-list>
1440 New in version 3.24.
1441 Specify a group of libraries to link to a target, along with a
1444 feature which defines how that group should be linked. For ex‐
1445 ample:
1446 add_library(lib1 STATIC ...)
1448 add_library(lib2 ...)
1449 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
1450 This specifies that lib2 should link to lib1 and external, and
1452 that both of those two libraries should be included on the
1453 linker command line according to the definition of the RESCAN
1454 feature.
1455 Feature names are case-sensitive and may only contain letters,
1457 numbers and underscores. Feature names defined in all uppercase
1458 are reserved for CMake's own built-in features. Currently,
1459 there is only one pre-defined built-in group feature:
1460 RESCAN Some linkers are single-pass only. For such linkers,
1462 circular references between libraries typically result in
1463 unresolved symbols. This feature instructs the linker to
1464 search the specified static libraries repeatedly until no
1465 new undefined references are created.
1466 Normally, a static library is searched only once in the
1468 order that it is specified on the command line. If a
1469 symbol in that library is needed to resolve an undefined
1470 symbol referred to by an object in a library that appears
1471 later on the command line, the linker would not be able
1472 to resolve that reference. By grouping the static li‐
1473 braries with the RESCAN feature, they will all be
1474 searched repeatedly until all possible references are re‐
1475 solved. This will use linker options like --start-group
1476 and --end-group, or on SunOS, -z rescan-start and -z res‐
1477 can-end.
1478 Using this feature has a significant performance cost. It
1480 is best to use it only when there are unavoidable circu‐
1481 lar references between two or more static libraries.
1482 This feature is available when using toolchains that tar‐
1484 get Linux, BSD, and SunOS. It can also be used when tar‐
1485 geting Windows platforms if the GNU toolchain is used.
1486 Built-in and custom group features are defined in terms of the
1488 following variables:
1489 • CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
1491 • CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
1493 • CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
1495 • CMAKE_LINK_GROUP_USING_<FEATURE>
1497 The value used for each of these variables is the value as set
1499 at the end of the directory scope in which the target was cre‐
1500 ated. The usage is as follows:
1501 1. If the language-specific
1503 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable is
1504 true, the feature must be defined by the corresponding
1505 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable.
1506 2. If no language-specific feature is supported, then the
1508 CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be
1509 true and the feature must be defined by the corresponding
1510 CMAKE_LINK_GROUP_USING_<FEATURE> variable.
1511 The LINK_GROUP generator expression is compatible with the
1513 LINK_LIBRARY generator expression. The libraries involved in a
1514 group can be specified using the LINK_LIBRARY generator expres‐
1515 sion.
1516 Each target or external library involved in the link step is al‐
1518 lowed to be part of multiple groups, but only if all the groups
1519 involved specify the same feature. Such groups will not be
1520 merged on the linker command line, the individual groups will
1521 still be preserved. Mixing different group features for the
1522 same target or library is forbidden.
1523 add_library(lib1 ...)
1525 add_library(lib2 ...)
1526 add_library(lib3 ...)
1527 add_library(lib4 ...)
1528 add_library(lib5 ...)
1529 target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
1531 target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
1532 # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
1533 # Both groups specify the same feature, so this is fine.
1534 target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
1536 # An error will be raised here because both lib1 and lib3 are part of two
1537 # groups with different features.
1538 When a target or an external library is involved in the link
1540 step as part of a group and also as not part of any group, any
1541 occurrence of the non-group link item will be replaced by the
1542 groups it belongs to.
1543 add_library(lib1 ...)
1545 add_library(lib2 ...)
1546 add_library(lib3 ...)
1547 add_library(lib4 ...)
1548 target_link_libraries(lib3 PUBLIC lib1)
1550 target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
1552 # lib4 will only be linked with lib3 and the group {lib1,lib2}
1553 Because lib1 is part of the group defined for lib4, that group
1555 then gets applied back to the use of lib1 for lib3. The end re‐
1556 sult will be as though the linking relationship for lib3 had
1557 been specified as:
1558 target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
1560 Be aware that the precedence of the group over the non-group
1562 link item can result in circular dependencies between groups.
1563 If this occurs, a fatal error is raised because circular depen‐
1564 dencies are not allowed for groups.
1565 add_library(lib1A ...)
1567 add_library(lib1B ...)
1568 add_library(lib2A ...)
1569 add_library(lib2B ...)
1570 add_library(lib3 ...)
1571 # Non-group linking relationships, these are non-circular so far
1573 target_link_libraries(lib1A PUBLIC lib2A)
1574 target_link_libraries(lib2B PUBLIC lib1B)
1575 # The addition of these groups creates circular dependencies
1577 target_link_libraries(lib3 PRIVATE
1578 "$<LINK_GROUP:feat,lib1A,lib1B>"
1579 "$<LINK_GROUP:feat,lib2A,lib2B>"
1580 )
1581 Because of the groups defined for lib3, the linking relation‐
1583 ships for lib1A and lib2B effectively get expanded to the equiv‐
1584 alent of:
1585 target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
1587 target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
1588 This creates a circular dependency between groups: lib1A -->
1590 lib2B --> lib1A.
1591 The following limitations should also be noted:
1593 • The library-list can specify CMake targets or libraries. Any
1595 CMake target of type OBJECT or INTERFACE will ignore the fea‐
1596 ture aspect of the expression and instead be linked in the
1597 standard way.
1598 • The $<LINK_GROUP:...> generator expression can only be used to
1600 specify link libraries. In practice, this means it can appear
1601 in the LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES,and
1602 INTERFACE_LINK_LIBRARIES_DIRECT target properties, and be
1603 specified in target_link_libraries() and link_libraries() com‐
1604 mands.
1605 • If a $<LINK_GROUP:...> generator expression appears in the
1607 INTERFACE_LINK_LIBRARIES property of a target, it will be in‐
1608 cluded in the imported target generated by a install(EXPORT)
1609 command. It is the responsibility of the environment consum‐
1610 ing this import to define the link feature used by this ex‐
1611 pression.
1612 Link Context
1614 $<LINK_ONLY:...>
1615 New in version 3.1.
1616 Content of ..., except while collecting Transitive Usage Re‐
1619 quirements, in which case it is the empty string. This is in‐
1620 tended for use in an INTERFACE_LINK_LIBRARIES target property,
1621 typically populated via the target_link_libraries() command, to
1622 specify private link dependencies without other usage require‐
1623 ments such as include directories or compile options.
1624 New in version 3.24: LINK_ONLY may also be used in a
1626 LINK_LIBRARIES target property. See policy CMP0131.
1627 $<DEVICE_LINK:list>
1630 New in version 3.18.
1631 Returns the list if it is the device link step, an empty list
1634 otherwise. The device link step is controlled by
1635 CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS prop‐
1636 erties and policy CMP0105. This expression can only be used to
1637 specify link options.
1638 $<HOST_LINK:list>
1640 New in version 3.18.
1641 Returns the list if it is the normal link step, an empty list
1644 otherwise. This expression is mainly useful when a device link
1645 step is also involved (see $<DEVICE_LINK:list> generator expres‐
1646 sion). This expression can only be used to specify link options.
1647 Target-Dependent Expressions
1649 These queries refer to a target tgt. Unless otherwise stated, this can
1650 be any runtime artifact, namely:
1651 • An executable target created by add_executable().
1653 • A shared library target (.so, .dll but not their .lib import library)
1655 created by add_library().
1656 • A static library target created by add_library().
1658 In the following, the phrase "the tgt filename" means the name of the
1660 tgt binary file. This has to be distinguished from the phrase "the tar‐
1661 get name", which is just the string tgt.
1662 $<TARGET_EXISTS:tgt>
1664 New in version 3.12.
1665 1 if tgt exists as a CMake target, else 0.
1668 $<TARGET_NAME_IF_EXISTS:tgt>
1670 New in version 3.12.
1671 The target name tgt if the target exists, an empty string other‐
1674 wise.
1675 Note that tgt is not added as a dependency of the target this
1677 expression is evaluated on.
1678 $<TARGET_NAME:...>
1680 Marks ... as being the name of a target. This is required if
1681 exporting targets to multiple dependent export sets. The ...
1682 must be a literal name of a target, it may not contain generator
1683 expressions.
1684 $<TARGET_PROPERTY:tgt,prop>
1686 Value of the property prop on the target tgt.
1687 Note that tgt is not added as a dependency of the target this
1689 expression is evaluated on.
1690 Changed in version 3.26: When encountered during evaluation of
1692 Transitive Usage Requirements, typically in an INTERFACE_* tar‐
1693 get property, lookup of the tgt name occurs in the directory of
1694 the target specifying the requirement, rather than the directory
1695 of the consuming target for which the expression is being evalu‐
1696 ated.
1697 $<TARGET_PROPERTY:prop>
1700 Value of the property prop on the target for which the expres‐
1701 sion is being evaluated. Note that for generator expressions in
1702 Transitive Usage Requirements this is the consuming target
1703 rather than the target specifying the requirement.
1704 $<TARGET_OBJECTS:tgt>
1706 New in version 3.1.
1707 List of objects resulting from building tgt. This would typi‐
1710 cally be used on object library targets.
1711 $<TARGET_POLICY:policy>
1713 1 if the policy was NEW when the 'head' target was created, else
1714 0. If the policy was not set, the warning message for the pol‐
1715 icy will be emitted. This generator expression only works for a
1716 subset of policies.
1717 $<TARGET_FILE:tgt>
1719 Full path to the tgt binary file.
1720 Note that tgt is not added as a dependency of the target this
1722 expression is evaluated on, unless the expression is being used
1723 in add_custom_command() or add_custom_target().
1724 $<TARGET_FILE_BASE_NAME:tgt>
1726 New in version 3.15.
1727 Base name of tgt, i.e. $<TARGET_FILE_NAME:tgt> without prefix
1730 and suffix. For example, if the tgt filename is libbase.so, the
1731 base name is base.
1732 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
1734 LIBRARY_OUTPUT_NAME and RUNTIME_OUTPUT_NAME target properties
1735 and their configuration specific variants OUTPUT_NAME_<CONFIG>,
1736 ARCHIVE_OUTPUT_NAME_<CONFIG>, LIBRARY_OUTPUT_NAME_<CONFIG> and
1737 RUNTIME_OUTPUT_NAME_<CONFIG>.
1738 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1740 also be considered.
1741 Note that tgt is not added as a dependency of the target this
1743 expression is evaluated on.
1744 $<TARGET_FILE_PREFIX:tgt>
1746 New in version 3.15.
1747 Prefix of the tgt filename (such as lib).
1750 See also the PREFIX target property.
1752 Note that tgt is not added as a dependency of the target this
1754 expression is evaluated on.
1755 $<TARGET_FILE_SUFFIX:tgt>
1757 New in version 3.15.
1758 Suffix of the tgt filename (extension such as .so or .exe).
1761 See also the SUFFIX target property.
1763 Note that tgt is not added as a dependency of the target this
1765 expression is evaluated on.
1766 $<TARGET_FILE_NAME:tgt>
1768 The tgt filename.
1769 Note that tgt is not added as a dependency of the target this
1771 expression is evaluated on (see policy CMP0112).
1772 $<TARGET_FILE_DIR:tgt>
1774 Directory of the tgt binary file.
1775 Note that tgt is not added as a dependency of the target this
1777 expression is evaluated on (see policy CMP0112).
1778 $<TARGET_IMPORT_FILE:tgt>
1780 New in version 3.27.
1781 Full path to the linker import file. On DLL platforms, it would
1784 be the .lib file. For executables on AIX, and for shared li‐
1785 braries on macOS, it could be, respectively, the .imp or .tbd
1786 import file, depending on the value of the ENABLE_EXPORTS prop‐
1787 erty.
1788 This expands to an empty string when there is no import file as‐
1790 sociated with the target.
1791 $<TARGET_IMPORT_FILE_BASE_NAME:tgt>
1793 New in version 3.27.
1794 Base name of the linker import file of the target tgt without
1797 prefix or suffix. For example, if the target file name is lib‐
1798 base.tbd, the base name is base.
1799 See also the OUTPUT_NAME and ARCHIVE_OUTPUT_NAME target proper‐
1801 ties and their configuration specific variants
1802 OUTPUT_NAME_<CONFIG> and ARCHIVE_OUTPUT_NAME_<CONFIG>.
1803 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1805 also be considered.
1806 Note that tgt is not added as a dependency of the target this
1808 expression is evaluated on.
1809 $<TARGET_IMPORT_FILE_PREFIX:tgt>
1811 New in version 3.27.
1812 Prefix of the import file of the target tgt.
1815 See also the IMPORT_PREFIX target property.
1817 Note that tgt is not added as a dependency of the target this
1819 expression is evaluated on.
1820 $<TARGET_IMPORT_FILE_SUFFIX:tgt>
1822 New in version 3.27.
1823 Suffix of the import file of the target tgt.
1826 The suffix corresponds to the file extension (such as .lib or
1828 .tbd).
1829 See also the IMPORT_SUFFIX target property.
1831 Note that tgt is not added as a dependency of the target this
1833 expression is evaluated on.
1834 $<TARGET_IMPORT_FILE_NAME:tgt>
1836 New in version 3.27.
1837 Name of the import file of the target tgt.
1840 Note that tgt is not added as a dependency of the target this
1842 expression is evaluated on.
1843 $<TARGET_IMPORT_FILE_DIR:tgt>
1845 New in version 3.27.
1846 Directory of the import file of the target tgt.
1849 Note that tgt is not added as a dependency of the target this
1851 expression is evaluated on.
1852 $<TARGET_LINKER_FILE:tgt>
1854 File used when linking to the tgt target. This will usually be
1855 the library that tgt represents (.a, .lib, .so), but for a
1856 shared library on DLL platforms, it would be the .lib import li‐
1857 brary associated with the DLL.
1858 New in version 3.27: On macOS, it could be the .tbd import file
1860 associated with the shared library, depending on the value of
1861 the ENABLE_EXPORTS property.
1862 This generator expression is equivalent to
1865 $<TARGET_LINKER_LIBRARY_FILE> or $<TARGET_LINKER_IMPORT_FILE>
1866 generator expressions, depending on the characteristics of the
1867 target and the platform.
1868 $<TARGET_LINKER_FILE_BASE_NAME:tgt>
1870 New in version 3.15.
1871 Base name of file used to link the target tgt, i.e.
1874 $<TARGET_LINKER_FILE_NAME:tgt> without prefix and suffix. For
1875 example, if target file name is libbase.a, the base name is
1876 base.
1877 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, and
1879 LIBRARY_OUTPUT_NAME target properties and their configuration
1880 specific variants OUTPUT_NAME_<CONFIG>,
1881 ARCHIVE_OUTPUT_NAME_<CONFIG> and LIBRARY_OUTPUT_NAME_<CONFIG>.
1882 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1884 also be considered.
1885 Note that tgt is not added as a dependency of the target this
1887 expression is evaluated on.
1888 $<TARGET_LINKER_FILE_PREFIX:tgt>
1890 New in version 3.15.
1891 Prefix of file used to link target tgt.
1894 See also the PREFIX and IMPORT_PREFIX target properties.
1896 Note that tgt is not added as a dependency of the target this
1898 expression is evaluated on.
1899 $<TARGET_LINKER_FILE_SUFFIX:tgt>
1901 New in version 3.15.
1902 Suffix of file used to link where tgt is the name of a target.
1905 The suffix corresponds to the file extension (such as ".so" or
1907 ".lib").
1908 See also the SUFFIX and IMPORT_SUFFIX target properties.
1910 Note that tgt is not added as a dependency of the target this
1912 expression is evaluated on.
1913 $<TARGET_LINKER_FILE_NAME:tgt>
1915 Name of file used to link target tgt.
1916 Note that tgt is not added as a dependency of the target this
1918 expression is evaluated on (see policy CMP0112).
1919 $<TARGET_LINKER_FILE_DIR:tgt>
1921 Directory of file used to link target tgt.
1922 Note that tgt is not added as a dependency of the target this
1924 expression is evaluated on (see policy CMP0112).
1925 $<TARGET_LINKER_LIBRARY_FILE:tgt>
1927 New in version 3.27.
1928 File used when linking o the tgt target is done using directly
1931 the library, and not an import file. This will usually be the
1932 library that tgt represents (.a, .so, .dylib). So, on DLL plat‐
1933 forms, it will be an empty string.
1934 $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt>
1936 New in version 3.27.
1937 Base name of library file used to link the target tgt, i.e.
1940 $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> without prefix and suf‐
1941 fix. For example, if target file name is libbase.a, the base
1942 name is base.
1943 See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, and
1945 LIBRARY_OUTPUT_NAME target properties and their configuration
1946 specific variants OUTPUT_NAME_<CONFIG>,
1947 ARCHIVE_OUTPUT_NAME_<CONFIG> and LIBRARY_OUTPUT_NAME_<CONFIG>.
1948 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
1950 also be considered.
1951 Note that tgt is not added as a dependency of the target this
1953 expression is evaluated on.
1954 $<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt>
1956 New in version 3.27.
1957 Prefix of the library file used to link target tgt.
1960 See also the PREFIX target property.
1962 Note that tgt is not added as a dependency of the target this
1964 expression is evaluated on.
1965 $<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt>
1967 New in version 3.27.
1968 Suffix of the library file used to link target tgt.
1971 The suffix corresponds to the file extension (such as ".a" or
1973 ".dylib").
1974 See also the SUFFIX target property.
1976 Note that tgt is not added as a dependency of the target this
1978 expression is evaluated on.
1979 $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>
1981 New in version 3.27.
1982 Name of the library file used to link target tgt.
1985 Note that tgt is not added as a dependency of the target this
1987 expression is evaluated on.
1988 $<TARGET_LINKER_LIBRARY_FILE_DIR:tgt>
1990 New in version 3.27.
1991 Directory of the library file used to link target tgt.
1994 Note that tgt is not added as a dependency of the target this
1996 expression is evaluated on.
1997 $<TARGET_LINKER_IMPORT_FILE:tgt>
1999 New in version 3.27.
2000 File used when linking to the tgt target is done using an import
2003 file. This will usually be the import file that tgt represents
2004 (.lib, .tbd). So, when no import file is involved in the link
2005 step, an empty string is returned.
2006 $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt>
2008 New in version 3.27.
2009 Base name of the import file used to link the target tgt, i.e.
2012 $<TARGET_LINKER_IMPORT_FILE_NAME:tgt> without prefix and suffix.
2013 For example, if target file name is libbase.tbd, the base name
2014 is base.
2015 See also the OUTPUT_NAME and ARCHIVE_OUTPUT_NAME, target proper‐
2017 ties and their configuration specific variants
2018 OUTPUT_NAME_<CONFIG> and ARCHIVE_OUTPUT_NAME_<CONFIG>.
2019 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
2021 also be considered.
2022 Note that tgt is not added as a dependency of the target this
2024 expression is evaluated on.
2025 $<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt>
2027 New in version 3.27.
2028 Prefix of the import file used to link target tgt.
2031 See also the IMPORT_PREFIX target property.
2033 Note that tgt is not added as a dependency of the target this
2035 expression is evaluated on.
2036 $<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt>
2038 New in version 3.27.
2039 Suffix of the import file used to link target tgt.
2042 The suffix corresponds to the file extension (such as ".lib" or
2044 ".tbd").
2045 See also the IMPORT_SUFFIX target property.
2047 Note that tgt is not added as a dependency of the target this
2049 expression is evaluated on.
2050 $<TARGET_LINKER_IMPORT_FILE_NAME:tgt>
2052 New in version 3.27.
2053 Name of the import file used to link target tgt.
2056 Note that tgt is not added as a dependency of the target this
2058 expression is evaluated on.
2059 $<TARGET_LINKER_IMPORT_FILE_DIR:tgt>
2061 New in version 3.27.
2062 Directory of the import file used to link target tgt.
2065 Note that tgt is not added as a dependency of the target this
2067 expression is evaluated on.
2068 $<TARGET_SONAME_FILE:tgt>
2070 File with soname (.so.3) where tgt is the name of a target.
2071 $<TARGET_SONAME_FILE_NAME:tgt>
2073 Name of file with soname (.so.3).
2074 Note that tgt is not added as a dependency of the target this
2076 expression is evaluated on (see policy CMP0112).
2077 $<TARGET_SONAME_FILE_DIR:tgt>
2079 Directory of file with soname (.so.3).
2080 Note that tgt is not added as a dependency of the target this
2082 expression is evaluated on (see policy CMP0112).
2083 $<TARGET_SONAME_IMPORT_FILE:tgt>
2085 New in version 3.27.
2086 Import file with soname (.3.tbd) where tgt is the name of a tar‐
2089 get.
2090 $<TARGET_SONAME_IMPORT_FILE_NAME:tgt>
2092 New in version 3.27.
2093 Name of the import file with soname (.3.tbd).
2096 Note that tgt is not added as a dependency of the target this
2098 expression is evaluated on.
2099 $<TARGET_SONAME_IMPORT_FILE_DIR:tgt>
2101 New in version 3.27.
2102 Directory of the import file with soname (.3.tbd).
2105 Note that tgt is not added as a dependency of the target this
2107 expression is evaluated on.
2108 $<TARGET_PDB_FILE:tgt>
2110 New in version 3.1.
2111 Full path to the linker generated program database file (.pdb)
2114 where tgt is the name of a target.
2115 See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
2117 and their configuration specific variants PDB_NAME_<CONFIG> and
2118 PDB_OUTPUT_DIRECTORY_<CONFIG>.
2119 $<TARGET_PDB_FILE_BASE_NAME:tgt>
2121 New in version 3.15.
2122 Base name of the linker generated program database file (.pdb)
2125 where tgt is the name of a target.
2126 The base name corresponds to the target PDB file name (see
2128 $<TARGET_PDB_FILE_NAME:tgt>) without prefix and suffix. For ex‐
2129 ample, if target file name is base.pdb, the base name is base.
2130 See also the PDB_NAME target property and its configuration spe‐
2132 cific variant PDB_NAME_<CONFIG>.
2133 The <CONFIG>_POSTFIX and DEBUG_POSTFIX target properties can
2135 also be considered.
2136 Note that tgt is not added as a dependency of the target this
2138 expression is evaluated on.
2139 $<TARGET_PDB_FILE_NAME:tgt>
2141 New in version 3.1.
2142 Name of the linker generated program database file (.pdb).
2145 Note that tgt is not added as a dependency of the target this
2147 expression is evaluated on (see policy CMP0112).
2148 $<TARGET_PDB_FILE_DIR:tgt>
2150 New in version 3.1.
2151 Directory of the linker generated program database file (.pdb).
2154 Note that tgt is not added as a dependency of the target this
2156 expression is evaluated on (see policy CMP0112).
2157 $<TARGET_BUNDLE_DIR:tgt>
2159 New in version 3.9.
2160 Full path to the bundle directory (/path/to/my.app,
2163 /path/to/my.framework, or /path/to/my.bundle), where tgt is the
2164 name of a target.
2165 Note that tgt is not added as a dependency of the target this
2167 expression is evaluated on (see policy CMP0112).
2168 $<TARGET_BUNDLE_DIR_NAME:tgt>
2170 New in version 3.24.
2171 Name of the bundle directory (my.app, my.framework, or my.bun‐
2174 dle), where tgt is the name of a target.
2175 Note that tgt is not added as a dependency of the target this
2177 expression is evaluated on (see policy CMP0112).
2178 $<TARGET_BUNDLE_CONTENT_DIR:tgt>
2180 New in version 3.9.
2181 Full path to the bundle content directory where tgt is the name
2184 of a target. For the macOS SDK it leads to /path/to/my.app/Con‐
2185 tents, /path/to/my.framework, or /path/to/my.bundle/Contents.
2186 For all other SDKs (e.g. iOS) it leads to /path/to/my.app,
2187 /path/to/my.framework, or /path/to/my.bundle due to the flat
2188 bundle structure.
2189 Note that tgt is not added as a dependency of the target this
2191 expression is evaluated on (see policy CMP0112).
2192 $<TARGET_RUNTIME_DLLS:tgt>
2194 New in version 3.21.
2195 List of DLLs that the target depends on at runtime. This is de‐
2198 termined by the locations of all the SHARED targets in the tar‐
2199 get's transitive dependencies. If only the directories of the
2200 DLLs are needed, see the TARGET_RUNTIME_DLL_DIRS generator ex‐
2201 pression. Using this generator expression on targets other than
2202 executables, SHARED libraries, and MODULE libraries is an error.
2203 On non-DLL platforms, this expression always evaluates to an
2204 empty string.
2205 This generator expression can be used to copy all of the DLLs
2207 that a target depends on into its output directory in a
2208 POST_BUILD custom command using the cmake -E copy -t command.
2209 For example:
2210 find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
2212 add_executable(exe main.c)
2214 target_link_libraries(exe PRIVATE foo::foo foo::bar)
2215 add_custom_command(TARGET exe POST_BUILD
2216 COMMAND ${CMAKE_COMMAND} -E copy -t $<TARGET_FILE_DIR:exe> $<TARGET_RUNTIME_DLLS:exe>
2217 COMMAND_EXPAND_LISTS
2218 )
2219 NOTE:
2221 Imported Targets are supported only if they know the location
2222 of their .dll files. An imported SHARED library must have
2223 IMPORTED_LOCATION set to its .dll file. See the add_library
2224 imported libraries section for details. Many Find Modules
2225 produce imported targets with the UNKNOWN type and therefore
2226 will be ignored.
2227 On platforms that support runtime paths (RPATH), refer to the
2229 INSTALL_RPATH target property. On Apple platforms, refer to the
2230 INSTALL_NAME_DIR target property.
2231 $<TARGET_RUNTIME_DLL_DIRS:tgt>
2233 New in version 3.27.
2234 List of the directories which contain the DLLs that the target
2237 depends on at runtime (see TARGET_RUNTIME_DLLS). This is deter‐
2238 mined by the locations of all the SHARED targets in the target's
2239 transitive dependencies. Using this generator expression on tar‐
2240 gets other than executables, SHARED libraries, and MODULE li‐
2241 braries is an error. On non-DLL platforms, this expression al‐
2242 ways evaluates to an empty string.
2243 This generator expression can e.g. be used to create a batch
2245 file using file(GENERATE) which sets the PATH environment vari‐
2246 able accordingly.
2247 Export And Install Expressions
2249 $<INSTALL_INTERFACE:...>
2250 Content of ... when the property is exported using
2251 install(EXPORT), and empty otherwise.
2252 $<BUILD_INTERFACE:...>
2254 Content of ... when the property is exported using export(), or
2255 when the target is used by another target in the same buildsys‐
2256 tem. Expands to the empty string otherwise.
2257 $<BUILD_LOCAL_INTERFACE:...>
2259 New in version 3.26.
2260 Content of ... when the target is used by another target in the
2263 same buildsystem. Expands to the empty string otherwise.
2264 $<INSTALL_PREFIX>
2266 Content of the install prefix when the target is exported via
2267 install(EXPORT), or when evaluated in the INSTALL_NAME_DIR prop‐
2268 erty, the INSTALL_NAME_DIR argument of
2269 install(RUNTIME_DEPENDENCY_SET), the code argument of
2270 install(CODE), or the file argument of install(SCRIPT), and
2271 empty otherwise.
2272 Multi-level Expression Evaluation
2274 $<GENEX_EVAL:expr>
2275 New in version 3.12.
2276 Content of expr evaluated as a generator expression in the cur‐
2279 rent context. This enables consumption of generator expressions
2280 whose evaluation results itself in generator expressions.
2281 $<TARGET_GENEX_EVAL:tgt,expr>
2283 New in version 3.12.
2284 Content of expr evaluated as a generator expression in the con‐
2287 text of tgt target. This enables consumption of custom target
2288 properties that themselves contain generator expressions.
2289 Having the capability to evaluate generator expressions is very
2291 useful when you want to manage custom properties supporting gen‐
2292 erator expressions. For example:
2293 add_library(foo ...)
2295 set_property(TARGET foo PROPERTY
2297 CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
2298 )
2299 add_custom_target(printFooKeys
2301 COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
2302 )
2303 This naive implementation of the printFooKeys custom command is
2305 wrong because CUSTOM_KEYS target property is not evaluated and
2306 the content is passed as is (i.e. $<$<CONFIG:DEBUG>:FOO_EX‐
2307 TRA_THINGS>).
2308 To have the expected result (i.e. FOO_EXTRA_THINGS if config is
2310 Debug), it is required to evaluate the output of $<TARGET_PROP‐
2311 ERTY:foo,CUSTOM_KEYS>:
2312 add_custom_target(printFooKeys
2314 COMMAND ${CMAKE_COMMAND} -E
2315 echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
2316 )
2317 Escaped Characters
2319 These expressions evaluate to specific string literals. Use them in
2320 place of the actual string literal where you need to prevent them from
2321 having their special meaning.
2322 $<ANGLE-R>
2324 A literal >. Used for example to compare strings that contain a
2325 >.
2326 $<COMMA>
2328 A literal ,. Used for example to compare strings which contain a
2329 ,.
2330 $<SEMICOLON>
2332 A literal ;. Used to prevent list expansion on an argument with
2333 ;.
2334 Deprecated Expressions
2336 $<CONFIGURATION>
2337 Configuration name. Deprecated since CMake 3.0. Use CONFIG in‐
2338 stead.
2339
2341 2000-2023 Kitware, Inc. and Contributors
23423.27.7 Oct 07, 2023 CMAKE-GENERATOR-EXPRESSIONS(7)