1CMAKE-GENERATOR-EXPRESSIONS(7)       CMake      CMAKE-GENERATOR-EXPRESSIONS(7)
2
3
4

NAME

6       cmake-generator-expressions - CMake Generator Expressions
7

INTRODUCTION

9       Generator  expressions  are evaluated during build system generation to
10       produce information specific to each build configuration.
11
12       Generator expressions are allowed in the context of many target proper‐
13       ties,  such as LINK_LIBRARIES, INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS
14       and others.  They may also be used  when  using  commands  to  populate
15       those  properties,  such as target_link_libraries(), target_include_di‐
16       rectories(), target_compile_definitions() and others.
17
18       They enable conditional linking, conditional definitions used when com‐
19       piling,  conditional include directories, and more.  The conditions may
20       be based on the build configuration, target properties, platform infor‐
21       mation or any other queryable information.
22
23       Generator  expressions  have the form $<...>.  To avoid confusion, this
24       page deviates from most of the CMake documentation in that it omits an‐
25       gular  brackets  <...> around placeholders like condition, string, tar‐
26       get, among others.
27
28       Generator expressions can be nested, as shown in most of  the  examples
29       below.
30

BOOLEAN GENERATOR EXPRESSIONS

32       Boolean expressions evaluate to either 0 or 1.  They are typically used
33       to construct the condition in a conditional generator expression.
34
35       Available boolean expressions are:
36
37   Logical Operators
38       $<BOOL:string>
39              Converts string to 0 or 1. Evaluates to 0 if any of the  follow‐
40              ing is true:
41
42string is empty,
43
44string  is  a  case-insensitive equal of 0, FALSE, OFF, N, NO,
45                IGNORE, or NOTFOUND, or
46
47string ends in the suffix -NOTFOUND (case-sensitive).
48
49              Otherwise evaluates to 1.
50
51       $<AND:conditions>
52              where conditions is a comma-separated list  of  boolean  expres‐
53              sions.  Evaluates to 1 if all conditions are 1.  Otherwise eval‐
54              uates to 0.
55
56       $<OR:conditions>
57              where conditions is a comma-separated list  of  boolean  expres‐
58              sions.   Evaluates  to 1 if at least one of the conditions is 1.
59              Otherwise evaluates to 0.
60
61       $<NOT:condition>
62              0 if condition is 1, else 1.
63
64   String Comparisons
65       $<STREQUAL:string1,string2>
66              1 if string1 and string2 are equal, else 0.  The  comparison  is
67              case-sensitive.  For a case-insensitive comparison, combine with
68              a string transforming generator expression,
69
70                 $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...
71
72       $<EQUAL:value1,value2>
73              1 if value1 and value2 are numerically equal, else 0.
74
75       $<IN_LIST:string,list>
76              New in version 3.12.
77
78
79              1 if string is member of the semicolon-separated list,  else  0.
80              Uses case-sensitive comparisons.
81
82       $<VERSION_LESS:v1,v2>
83              1 if v1 is a version less than v2, else 0.
84
85       $<VERSION_GREATER:v1,v2>
86              1 if v1 is a version greater than v2, else 0.
87
88       $<VERSION_EQUAL:v1,v2>
89              1 if v1 is the same version as v2, else 0.
90
91       $<VERSION_LESS_EQUAL:v1,v2>
92              New in version 3.7.
93
94
95              1 if v1 is a version less than or equal to v2, else 0.
96
97       $<VERSION_GREATER_EQUAL:v1,v2>
98              New in version 3.7.
99
100
101              1 if v1 is a version greater than or equal to v2, else 0.
102
103   Variable Queries
104       $<TARGET_EXISTS:target>
105              New in version 3.12.
106
107
108              1 if target exists, else 0.
109
110       $<CONFIG:cfgs>
111              1  if  config  is any one of the entries in comma-separated list
112              cfgs, else 0. This is a case-insensitive comparison. The mapping
113              in  MAP_IMPORTED_CONFIG_<CONFIG>  is also considered by this ex‐
114              pression when it is evaluated on a property on an IMPORTED  tar‐
115              get.
116
117       $<PLATFORM_ID:platform_ids>
118              where  platform_ids is a comma-separated list.  1 if the CMake's
119              platform id matches any one of the entries in platform_ids, oth‐
120              erwise 0.  See also the CMAKE_SYSTEM_NAME variable.
121
122       $<C_COMPILER_ID:compiler_ids>
123              where  compiler_ids is a comma-separated list.  1 if the CMake's
124              compiler id of the C compiler matches any one of the entries  in
125              compiler_ids,  otherwise  0.   See  also  the  CMAKE_<LANG>_COM‐
126              PILER_ID variable.
127
128       $<CXX_COMPILER_ID:compiler_ids>
129              where compiler_ids is a comma-separated list.  1 if the  CMake's
130              compiler  id  of the CXX compiler matches any one of the entries
131              in compiler_ids, otherwise 0.  See  also  the  CMAKE_<LANG>_COM‐
132              PILER_ID variable.
133
134       $<CUDA_COMPILER_ID:compiler_ids>
135              New in version 3.15.
136
137
138              where  compiler_ids is a comma-separated list.  1 if the CMake's
139              compiler id of the CUDA compiler matches any one of the  entries
140              in  compiler_ids,  otherwise  0.  See also the CMAKE_<LANG>_COM‐
141              PILER_ID variable.
142
143       $<OBJC_COMPILER_ID:compiler_ids>
144              New in version 3.16.
145
146
147              where compiler_ids is a comma-separated list.  1 if the  CMake's
148              compiler  id  of the Objective-C compiler matches any one of the
149              entries  in   compiler_ids,   otherwise   0.    See   also   the
150              CMAKE_<LANG>_COMPILER_ID variable.
151
152       $<OBJCXX_COMPILER_ID:compiler_ids>
153              New in version 3.16.
154
155
156              where  compiler_ids is a comma-separated list.  1 if the CMake's
157              compiler id of the Objective-C++ compiler matches any one of the
158              entries   in   compiler_ids,   otherwise   0.    See   also  the
159              CMAKE_<LANG>_COMPILER_ID variable.
160
161       $<Fortran_COMPILER_ID:compiler_ids>
162              where compiler_ids is a comma-separated list.  1 if the  CMake's
163              compiler  id  of the Fortran compiler matches any one of the en‐
164              tries   in   compiler_ids,   otherwise   0.    See   also    the
165              CMAKE_<LANG>_COMPILER_ID variable.
166
167       $<HIP_COMPILER_ID:compiler_ids>
168              where  compiler_ids is a comma-separated list.  1 if the CMake's
169              compiler id of the HIP compiler matches any one of  the  entries
170              in  compiler_ids,  otherwise  0.  See also the CMAKE_<LANG>_COM‐
171              PILER_ID variable.
172
173       $<ISPC_COMPILER_ID:compiler_ids>
174              New in version 3.19.
175
176
177              where compiler_ids is a comma-separated list.  1 if the  CMake's
178              compiler  id of the ISPC compiler matches any one of the entries
179              in compiler_ids, otherwise 0.  See  also  the  CMAKE_<LANG>_COM‐
180              PILER_ID variable.
181
182       $<C_COMPILER_VERSION:version>
183              1 if the version of the C compiler matches version, otherwise 0.
184              See also the CMAKE_<LANG>_COMPILER_VERSION variable.
185
186       $<CXX_COMPILER_VERSION:version>
187              1 if the version of the CXX compiler matches version,  otherwise
188              0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
189
190       $<CUDA_COMPILER_VERSION:version>
191              New in version 3.15.
192
193
194              1  if the version of the CXX compiler matches version, otherwise
195              0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
196
197       $<OBJC_COMPILER_VERSION:version>
198              New in version 3.16.
199
200
201              1 if the version of the OBJC compiler matches version, otherwise
202              0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
203
204       $<OBJCXX_COMPILER_VERSION:version>
205              New in version 3.16.
206
207
208              1  if the version of the OBJCXX compiler matches version, other‐
209              wise 0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
210
211       $<Fortran_COMPILER_VERSION:version>
212              1 if the version of the Fortran compiler matches version, other‐
213              wise 0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
214
215       $<HIP_COMPILER_VERSION:version>
216              1  if the version of the HIP compiler matches version, otherwise
217              0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
218
219       $<ISPC_COMPILER_VERSION:version>
220              New in version 3.19.
221
222
223              1 if the version of the ISPC compiler matches version, otherwise
224              0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
225
226       $<TARGET_POLICY:policy>
227              1 if the policy was NEW when the 'head' target was created, else
228              0.  If the policy was not set, the warning message for the  pol‐
229              icy  will be emitted. This generator expression only works for a
230              subset of policies.
231
232       $<COMPILE_FEATURES:features>
233              New in version 3.1.
234
235
236              where features is a comma-spearated list.  Evaluates to 1 if all
237              of  the features are available for the 'head' target, and 0 oth‐
238              erwise. If this expression is used while evaluating the link im‐
239              plementation  of a target and if any dependency transitively in‐
240              creases the required C_STANDARD or CXX_STANDARD for  the  'head'
241              target, an error is reported.  See the cmake-compile-features(7)
242              manual for information on compile features and a  list  of  sup‐
243              ported compilers.
244
245       $<COMPILE_LANG_AND_ID:language,compiler_ids>
246              New in version 3.15.
247
248
249              1  when  the language used for compilation unit matches language
250              and the CMake's compiler id of the language compiler matches any
251              one of the entries in compiler_ids, otherwise 0. This expression
252              is a short form for the combination  of  $<COMPILE_LANGUAGE:lan‐
253              guage> and $<LANG_COMPILER_ID:compiler_ids>. This expression may
254              be used to specify compile options, compile definitions, and in‐
255              clude  directories for source files of a particular language and
256              compiler combination in a target. For example:
257
258                 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
259                 target_compile_definitions(myapp
260                   PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
261                           $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
262                           $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
263                 )
264
265              This specifies the use of different compile definitions based on
266              both the compiler id and compilation language. This example will
267              have a COMPILING_CXX_WITH_CLANG compile definition when Clang is
268              the CXX compiler, and COMPILING_CXX_WITH_INTEL when Intel is the
269              CXX compiler.  Likewise when the C compiler  is  Clang  it  will
270              only see the  COMPILING_C_WITH_CLANG definition.
271
272              Without  the  COMPILE_LANG_AND_ID  generator expression the same
273              logic would be expressed as:
274
275                 target_compile_definitions(myapp
276                   PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
277                           $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
278                           $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
279                 )
280
281       $<COMPILE_LANGUAGE:languages>
282              New in version 3.3.
283
284
285              1 when the language used for compilation unit matches any of the
286              entries  in languages, otherwise 0.  This expression may be used
287              to specify compile options, compile definitions, and include di‐
288              rectories for source files of a particular language in a target.
289              For example:
290
291                 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
292                 target_compile_options(myapp
293                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
294                 )
295                 target_compile_definitions(myapp
296                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
297                           $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
298                 )
299                 target_include_directories(myapp
300                   PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
301                 )
302
303              This specifies the use of the  -fno-exceptions  compile  option,
304              COMPILING_CXX compile definition, and cxx_headers include direc‐
305              tory for C++ only (compiler id checks elided).  It  also  speci‐
306              fies a COMPILING_CUDA compile definition for CUDA.
307
308              Note  that  with  Visual Studio Generators and Xcode there is no
309              way to represent target-wide compile definitions or include  di‐
310              rectories separately for C and CXX languages.  Also, with Visual
311              Studio Generators there is no way to represent target-wide flags
312              separately for C and CXX languages.  Under these generators, ex‐
313              pressions for both C and C++ sources will be evaluated using CXX
314              if  there  are  any  C++ sources and otherwise using C.  A work‐
315              around is to create separate libraries for each source file lan‐
316              guage instead:
317
318                 add_library(myapp_c foo.c)
319                 add_library(myapp_cxx bar.cpp)
320                 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
321                 add_executable(myapp main.cpp)
322                 target_link_libraries(myapp myapp_c myapp_cxx)
323
324       $<LINK_LANG_AND_ID:language,compiler_ids>
325              New in version 3.18.
326
327
328              1  when the language used for link step matches language and the
329              CMake's compiler id of the language linker matches  any  one  of
330              the  entries  in compiler_ids, otherwise 0. This expression is a
331              short form for the combination of $<LINK_LANGUAGE:language>  and
332              $<LANG_COMPILER_ID:compiler_ids>. This expression may be used to
333              specify link libraries, link options, link directories and  link
334              dependencies  of a particular language and linker combination in
335              a target. For example:
336
337                 add_library(libC_Clang ...)
338                 add_library(libCXX_Clang ...)
339                 add_library(libC_Intel ...)
340                 add_library(libCXX_Intel ...)
341
342                 add_executable(myapp main.c)
343                 if (CXX_CONFIG)
344                   target_sources(myapp PRIVATE file.cxx)
345                 endif()
346                 target_link_libraries(myapp
347                   PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
348                           $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
349                           $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
350                           $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
351
352              This specifies the use of different link libraries based on both
353              the compiler id and link language. This example will have target
354              libCXX_Clang as link dependency when Clang or AppleClang is  the
355              CXX  linker,  and  libCXX_Intel  when  Intel  is the CXX linker.
356              Likewise when the  C  linker  is  Clang  or  AppleClang,  target
357              libC_Clang  will be added as link dependency and libC_Intel when
358              Intel is the C linker.
359
360              See the  note  related  to  $<LINK_LANGUAGE:language>  for  con‐
361              straints about the usage of this generator expression.
362
363       $<LINK_LANGUAGE:languages>
364              New in version 3.18.
365
366
367              1  when  the  language used for link step matches any of the en‐
368              tries in languages, otherwise 0.  This expression may be used to
369              specify  link libraries, link options, link directories and link
370              dependencies of a particular language in a target. For example:
371
372                 add_library(api_C ...)
373                 add_library(api_CXX ...)
374                 add_library(api INTERFACE)
375                 target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
376                                                     $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
377                 target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
378                                                     $<$<LINK_LANGUAGE:CXX>:api_CXX>)
379
380                 add_executable(myapp1 main.c)
381                 target_link_options(myapp1 PRIVATE api)
382
383                 add_executable(myapp2 main.cpp)
384                 target_link_options(myapp2 PRIVATE api)
385
386              This specifies to use the api target for linking targets  myapp1
387              and  myapp2. In practice, myapp1 will link with target api_C and
388              option -opt_c because it will use C as link language. And myapp2
389              will  link  with api_CXX and option -opt_cxx because CXX will be
390              the link language.
391
392              NOTE:
393                 To determine the link language of a target, it is required to
394                 collect,  transitively,  all the targets which will be linked
395                 to it. So, for link libraries properties, a double evaluation
396                 will  be  done.  During  the  first  evaluation,  $<LINK_LAN‐
397                 GUAGE:..> expressions will always return 0.   The  link  lan‐
398                 guage  computed  after this first pass will be used to do the
399                 second pass. To avoid inconsistency, it is required that  the
400                 second  pass  do  not  change the link language. Moreover, to
401                 avoid unexpected side-effects, it is required to specify com‐
402                 plete entities as part of the $<LINK_LANGUAGE:..> expression.
403                 For example:
404
405                     add_library(lib STATIC file.cxx)
406                     add_library(libother STATIC file.c)
407
408                     # bad usage
409                     add_executable(myapp1 main.c)
410                     target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
411
412                     # correct usage
413                     add_executable(myapp2 main.c)
414                     target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
415
416                 In this example, for myapp1, the first pass  will,  unexpect‐
417                 edly,  determine  that  the  link language is CXX because the
418                 evaluation of the  generator  expression  will  be  an  empty
419                 string  so myapp1 will depends on target lib which is C++. On
420                 the contrary, for myapp2, the first evaluation will give C as
421                 link  language,  so the second pass will correctly add target
422                 libother as link dependency.
423
424       $<DEVICE_LINK:list>
425              New in version 3.18.
426
427
428              Returns the list if it is the device link step,  an  empty  list
429              otherwise.   The  device link step is controlled by CUDA_SEPARA‐
430              BLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS  properties  and
431              policy CMP0105. This expression can only be used to specify link
432              options.
433
434       $<HOST_LINK:list>
435              New in version 3.18.
436
437
438              Returns the list if it is the normal link step,  an  empty  list
439              otherwise.   This expression is mainly useful when a device link
440              step is also involved (see $<DEVICE_LINK:list> generator expres‐
441              sion). This expression can only be used to specify link options.
442

STRING-VALUED GENERATOR EXPRESSIONS

444       These expressions expand to some string.  For example,
445
446          include_directories(/usr/include/$<CXX_COMPILER_ID>/)
447
448       expands  to  /usr/include/GNU/ or /usr/include/Clang/ etc, depending on
449       the compiler identifier.
450
451       String-valued expressions may also be combined with other  expressions.
452       Here an example for a string-valued expression within a boolean expres‐
453       sions within a conditional expression:
454
455          $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
456
457       expands to OLD_COMPILER if the CMAKE_CXX_COMPILER_VERSION is less  than
458       4.2.0.
459
460       And here two nested string-valued expressions:
461
462          -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
463
464       generates  a  string  of  the entries in the INCLUDE_DIRECTORIES target
465       property with each entry preceded by -I.
466
467       Expanding on the previous example, if one first wants to check  if  the
468       INCLUDE_DIRECTORIES  property is non-empty, then it is advisable to in‐
469       troduce a helper variable to keep the code readable:
470
471          set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
472          $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
473
474       The following string-valued generator expressions are available:
475
476   Escaped Characters
477       String literals to escape the special meaning a character would  other‐
478       wise have:
479
480       $<ANGLE-R>
481              A  literal >. Used for example to compare strings that contain a
482              >.
483
484       $<COMMA>
485              A literal ,. Used for example to compare strings which contain a
486              ,.
487
488       $<SEMICOLON>
489              A  literal ;. Used to prevent list expansion on an argument with
490              ;.
491
492   Conditional Expressions
493       Conditional generator expressions depend on a  boolean  condition  that
494       must be 0 or 1.
495
496       $<condition:true_string>
497              Evaluates to true_string if condition is 1.  Otherwise evaluates
498              to the empty string.
499
500       $<IF:condition,true_string,false_string>
501              New in version 3.8.
502
503
504              Evaluates to true_string if condition is 1.  Otherwise evaluates
505              to false_string.
506
507       Typically,  the  condition  is a boolean generator expression.  For in‐
508       stance,
509
510          $<$<CONFIG:Debug>:DEBUG_MODE>
511
512       expands to DEBUG_MODE when the Debug configuration is used, and  other‐
513       wise expands to the empty string.
514
515   String Transformations
516       $<JOIN:list,string>
517              Joins the list with the content of string.
518
519       $<REMOVE_DUPLICATES:list>
520              New in version 3.15.
521
522
523              Removes duplicated items in the given list.
524
525       $<FILTER:list,INCLUDE|EXCLUDE,regex>
526              New in version 3.15.
527
528
529              Includes  or  removes items from list that match the regular ex‐
530              pression regex.
531
532       $<LOWER_CASE:string>
533              Content of string converted to lower case.
534
535       $<UPPER_CASE:string>
536              Content of string converted to upper case.
537
538       $<GENEX_EVAL:expr>
539              New in version 3.12.
540
541
542              Content of expr evaluated as a generator expression in the  cur‐
543              rent  context. This enables consumption of generator expressions
544              whose evaluation results itself in generator expressions.
545
546       $<TARGET_GENEX_EVAL:tgt,expr>
547              New in version 3.12.
548
549
550              Content of expr evaluated as a generator expression in the  con‐
551              text  of  tgt  target. This enables consumption of custom target
552              properties that themselves contain generator expressions.
553
554              Having the capability to evaluate generator expressions is  very
555              useful when you want to manage custom properties supporting gen‐
556              erator expressions.  For example:
557
558                 add_library(foo ...)
559
560                 set_property(TARGET foo PROPERTY
561                   CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
562                 )
563
564                 add_custom_target(printFooKeys
565                   COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
566                 )
567
568              This naive implementation of the printFooKeys custom command  is
569              wrong  because  CUSTOM_KEYS target property is not evaluated and
570              the content is  passed  as  is  (i.e.  $<$<CONFIG:DEBUG>:FOO_EX‐
571              TRA_THINGS>).
572
573              To  have the expected result (i.e. FOO_EXTRA_THINGS if config is
574              Debug), it is required to evaluate the output of  $<TARGET_PROP‐
575              ERTY:foo,CUSTOM_KEYS>:
576
577                 add_custom_target(printFooKeys
578                   COMMAND ${CMAKE_COMMAND} -E
579                     echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
580                 )
581
582   Variable Queries
583       $<CONFIG>
584              Configuration name.
585
586       $<CONFIGURATION>
587              Configuration  name.  Deprecated since CMake 3.0. Use CONFIG in‐
588              stead.
589
590       $<PLATFORM_ID>
591              The current system's CMake platform id.  See also the CMAKE_SYS‐
592              TEM_NAME variable.
593
594       $<C_COMPILER_ID>
595              The  CMake's  compiler  id of the C compiler used.  See also the
596              CMAKE_<LANG>_COMPILER_ID variable.
597
598       $<CXX_COMPILER_ID>
599              The CMake's compiler id of the CXX compiler used.  See also  the
600              CMAKE_<LANG>_COMPILER_ID variable.
601
602       $<CUDA_COMPILER_ID>
603              The CMake's compiler id of the CUDA compiler used.  See also the
604              CMAKE_<LANG>_COMPILER_ID variable.
605
606       $<OBJC_COMPILER_ID>
607              New in version 3.16.
608
609
610              The CMake's compiler id of the OBJC compiler used.  See also the
611              CMAKE_<LANG>_COMPILER_ID variable.
612
613       $<OBJCXX_COMPILER_ID>
614              New in version 3.16.
615
616
617              The  CMake's  compiler id of the OBJCXX compiler used.  See also
618              the CMAKE_<LANG>_COMPILER_ID variable.
619
620       $<Fortran_COMPILER_ID>
621              The CMake's compiler id of the Fortran compiler used.  See  also
622              the CMAKE_<LANG>_COMPILER_ID variable.
623
624       $<HIP_COMPILER_ID>
625              The  CMake's compiler id of the HIP compiler used.  See also the
626              CMAKE_<LANG>_COMPILER_ID variable.
627
628       $<ISPC_COMPILER_ID>
629              New in version 3.19.
630
631
632              The CMake's compiler id of the ISPC compiler used.  See also the
633              CMAKE_<LANG>_COMPILER_ID variable.
634
635       $<C_COMPILER_VERSION>
636              The   version   of   the   C   compiler   used.   See  also  the
637              CMAKE_<LANG>_COMPILER_VERSION variable.
638
639       $<CXX_COMPILER_VERSION>
640              The  version  of  the  CXX  compiler   used.    See   also   the
641              CMAKE_<LANG>_COMPILER_VERSION variable.
642
643       $<CUDA_COMPILER_VERSION>
644              The   version   of   the  CUDA  compiler  used.   See  also  the
645              CMAKE_<LANG>_COMPILER_VERSION variable.
646
647       $<OBJC_COMPILER_VERSION>
648              New in version 3.16.
649
650
651              The  version  of  the  OBJC  compiler  used.    See   also   the
652              CMAKE_<LANG>_COMPILER_VERSION variable.
653
654       $<OBJCXX_COMPILER_VERSION>
655              New in version 3.16.
656
657
658              The   version  of  the  OBJCXX  compiler  used.   See  also  the
659              CMAKE_<LANG>_COMPILER_VERSION variable.
660
661       $<Fortran_COMPILER_VERSION>
662              The  version  of  the  Fortran  compiler  used.   See  also  the
663              CMAKE_<LANG>_COMPILER_VERSION variable.
664
665       $<HIP_COMPILER_VERSION>
666              The   version   of   the   HIP  compiler  used.   See  also  the
667              CMAKE_<LANG>_COMPILER_VERSION variable.
668
669       $<ISPC_COMPILER_VERSION>
670              New in version 3.19.
671
672
673              The  version  of  the  ISPC  compiler  used.    See   also   the
674              CMAKE_<LANG>_COMPILER_VERSION variable.
675
676       $<COMPILE_LANGUAGE>
677              New in version 3.3.
678
679
680              The compile language of source files when evaluating compile op‐
681              tions.   See  the  related  boolean  expression   $<COMPILE_LAN‐
682              GUAGE:language>  for notes about the portability of this genera‐
683              tor expression.
684
685       $<LINK_LANGUAGE>
686              New in version 3.18.
687
688
689              The link language of target when evaluating link  options.   See
690              the  related  boolean  expression  $<LINK_LANGUAGE:language> for
691              notes about the portability of this generator expression.
692
693              NOTE:
694                 This generator expression is not supported by  the  link  li‐
695                 braries  properties  to  avoid side-effects due to the double
696                 evaluation of these properties.
697
698   Target-Dependent Queries
699       These queries refer to a target tgt. This can be any runtime  artifact,
700       namely:
701
702       • an executable target created by add_executable()
703
704       • a shared library target (.so, .dll but not their .lib import library)
705         created by add_library()
706
707       • a static library target created by add_library()
708
709       In the following, "the tgt filename" means the name of the  tgt  binary
710       file.  This  has  to  be distinguished from "the target name", which is
711       just the string tgt.
712
713       $<TARGET_NAME_IF_EXISTS:tgt>
714              New in version 3.12.
715
716
717              The target name tgt if the target exists, an empty string other‐
718              wise.
719
720              Note  that  tgt  is not added as a dependency of the target this
721              expression is evaluated on.
722
723       $<TARGET_FILE:tgt>
724              Full path to the tgt binary file.
725
726       $<TARGET_FILE_BASE_NAME:tgt>
727              New in version 3.15.
728
729
730              Base name of tgt, i.e.  $<TARGET_FILE_NAME:tgt>  without  prefix
731              and suffix.  For example, if the tgt filename is libbase.so, the
732              base name is base.
733
734              See  also  the  OUTPUT_NAME,  ARCHIVE_OUTPUT_NAME,  LIBRARY_OUT‐
735              PUT_NAME  and  RUNTIME_OUTPUT_NAME  target  properties and their
736              configuration  specific   variants   OUTPUT_NAME_<CONFIG>,   AR‐
737              CHIVE_OUTPUT_NAME_<CONFIG>,   LIBRARY_OUTPUT_NAME_<CONFIG>   and
738              RUNTIME_OUTPUT_NAME_<CONFIG>.
739
740              The <CONFIG>_POSTFIX and  DEBUG_POSTFIX  target  properties  can
741              also be considered.
742
743              Note  that  tgt  is not added as a dependency of the target this
744              expression is evaluated on.
745
746       $<TARGET_FILE_PREFIX:tgt>
747              New in version 3.15.
748
749
750              Prefix of the tgt filename (such as lib).
751
752              See also the PREFIX target property.
753
754              Note that tgt is not added as a dependency of  the  target  this
755              expression is evaluated on.
756
757       $<TARGET_FILE_SUFFIX:tgt>
758              New in version 3.15.
759
760
761              Suffix of the tgt filename (extension such as .so or .exe).
762
763              See also the SUFFIX target property.
764
765              Note  that  tgt  is not added as a dependency of the target this
766              expression is evaluated on.
767
768       $<TARGET_FILE_NAME:tgt>
769              The tgt filename.
770
771              Note that tgt is not added as a dependency of  the  target  this
772              expression is evaluated on (see policy CMP0112).
773
774       $<TARGET_FILE_DIR:tgt>
775              Directory of the tgt binary file.
776
777              Note  that  tgt  is not added as a dependency of the target this
778              expression is evaluated on (see policy CMP0112).
779
780       $<TARGET_LINKER_FILE:tgt>
781              File used when linking to the tgt target.  This will usually  be
782              the  library  that  tgt  represents  (.a,  .lib, .so), but for a
783              shared library on DLL platforms, it would be the .lib import li‐
784              brary associated with the DLL.
785
786       $<TARGET_LINKER_FILE_BASE_NAME:tgt>
787              New in version 3.15.
788
789
790              Base  name  of  file  used  to link the target tgt, i.e.  $<TAR‐
791              GET_LINKER_FILE_NAME:tgt> without prefix and suffix.  For  exam‐
792              ple, if target file name is libbase.a, the base name is base.
793
794              See  also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, and LIBRARY_OUT‐
795              PUT_NAME target  properties  and  their  configuration  specific
796              variants  OUTPUT_NAME_<CONFIG>, ARCHIVE_OUTPUT_NAME_<CONFIG> and
797              LIBRARY_OUTPUT_NAME_<CONFIG>.
798
799              The <CONFIG>_POSTFIX and  DEBUG_POSTFIX  target  properties  can
800              also be considered.
801
802              Note  that  tgt  is not added as a dependency of the target this
803              expression is evaluated on.
804
805       $<TARGET_LINKER_FILE_PREFIX:tgt>
806              New in version 3.15.
807
808
809              Prefix of file used to link target tgt.
810
811              See also the PREFIX and IMPORT_PREFIX target properties.
812
813              Note that tgt is not added as a dependency of  the  target  this
814              expression is evaluated on.
815
816       $<TARGET_LINKER_FILE_SUFFIX:tgt>
817              New in version 3.15.
818
819
820              Suffix of file used to link where tgt is the name of a target.
821
822              The  suffix  corresponds to the file extension (such as ".so" or
823              ".lib").
824
825              See also the SUFFIX and IMPORT_SUFFIX target properties.
826
827              Note that tgt is not added as a dependency of  the  target  this
828              expression is evaluated on.
829
830       $<TARGET_LINKER_FILE_NAME:tgt>
831              Name of file used to link target tgt.
832
833              Note  that  tgt  is not added as a dependency of the target this
834              expression is evaluated on (see policy CMP0112).
835
836       $<TARGET_LINKER_FILE_DIR:tgt>
837              Directory of file used to link target tgt.
838
839              Note that tgt is not added as a dependency of  the  target  this
840              expression is evaluated on (see policy CMP0112).
841
842       $<TARGET_SONAME_FILE:tgt>
843              File with soname (.so.3) where tgt is the name of a target.
844
845       $<TARGET_SONAME_FILE_NAME:tgt>
846              Name of file with soname (.so.3).
847
848              Note  that  tgt  is not added as a dependency of the target this
849              expression is evaluated on (see policy CMP0112).
850
851       $<TARGET_SONAME_FILE_DIR:tgt>
852              Directory of with soname (.so.3).
853
854              Note that tgt is not added as a dependency of  the  target  this
855              expression is evaluated on (see policy CMP0112).
856
857       $<TARGET_PDB_FILE:tgt>
858              New in version 3.1.
859
860
861              Full  path  to the linker generated program database file (.pdb)
862              where tgt is the name of a target.
863
864              See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
865              and  their configuration specific variants PDB_NAME_<CONFIG> and
866              PDB_OUTPUT_DIRECTORY_<CONFIG>.
867
868       $<TARGET_PDB_FILE_BASE_NAME:tgt>
869              New in version 3.15.
870
871
872              Base name of the linker generated program database  file  (.pdb)
873              where tgt is the name of a target.
874
875              The  base  name  corresponds  to  the  target PDB file name (see
876              $<TARGET_PDB_FILE_NAME:tgt>) without prefix and suffix. For  ex‐
877              ample, if target file name is base.pdb, the base name is base.
878
879              See also the PDB_NAME target property and its configuration spe‐
880              cific variant PDB_NAME_<CONFIG>.
881
882              The <CONFIG>_POSTFIX and  DEBUG_POSTFIX  target  properties  can
883              also be considered.
884
885              Note  that  tgt  is not added as a dependency of the target this
886              expression is evaluated on.
887
888       $<TARGET_PDB_FILE_NAME:tgt>
889              New in version 3.1.
890
891
892              Name of the linker generated program database file (.pdb).
893
894              Note that tgt is not added as a dependency of  the  target  this
895              expression is evaluated on (see policy CMP0112).
896
897       $<TARGET_PDB_FILE_DIR:tgt>
898              New in version 3.1.
899
900
901              Directory of the linker generated program database file (.pdb).
902
903              Note  that  tgt  is not added as a dependency of the target this
904              expression is evaluated on (see policy CMP0112).
905
906       $<TARGET_BUNDLE_DIR:tgt>
907              New in version 3.9.
908
909
910              Full path to the  bundle  directory  (my.app,  my.framework,  or
911              my.bundle) where tgt is the name of a target.
912
913              Note  that  tgt  is not added as a dependency of the target this
914              expression is evaluated on (see policy CMP0112).
915
916       $<TARGET_BUNDLE_CONTENT_DIR:tgt>
917              New in version 3.9.
918
919
920              Full path to the bundle content directory where tgt is the  name
921              of  a  target.  For  the  macOS SDK it leads to my.app/Contents,
922              my.framework, or my.bundle/Contents. For all  other  SDKs  (e.g.
923              iOS)  it  leads to my.app, my.framework, or my.bundle due to the
924              flat bundle structure.
925
926              Note that tgt is not added as a dependency of  the  target  this
927              expression is evaluated on (see policy CMP0112).
928
929       $<TARGET_PROPERTY:tgt,prop>
930              Value of the property prop on the target tgt.
931
932              Note  that  tgt  is not added as a dependency of the target this
933              expression is evaluated on.
934
935       $<TARGET_PROPERTY:prop>
936              Value of the property prop on the target for which  the  expres‐
937              sion  is being evaluated. Note that for generator expressions in
938              Target Usage Requirements this is the  consuming  target  rather
939              than the target specifying the requirement.
940
941       $<TARGET_RUNTIME_DLLS:tgt>
942              New in version 3.21.
943
944
945              List  of DLLs that the target depends on at runtime. This is de‐
946              termined by the locations of all the SHARED and  MODULE  targets
947              in  the  target's  transitive dependencies. Using this generator
948              expression on targets other than executables, SHARED  libraries,
949              and  MODULE  libraries  is  an  error.  On non-DLL platforms, it
950              evaluates to an empty string.
951
952              This generator expression can be used to copy all  of  the  DLLs
953              that  a  target  depends  on  into  its  output  directory  in a
954              POST_BUILD custom command. For example:
955
956                 find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
957
958                 add_executable(exe main.c)
959                 target_link_libraries(exe PRIVATE foo::foo foo::bar)
960                 add_custom_command(TARGET exe POST_BUILD
961                   COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
962                   COMMAND_EXPAND_LISTS
963                   )
964
965              NOTE:
966                 Imported Targets are supported only if they know the location
967                 of  their  .dll  files.  An imported SHARED or MODULE library
968                 must have IMPORTED_LOCATION set to its .dll  file.   See  the
969                 add_library  imported  libraries  section  for details.  Many
970                 Find Modules produce imported targets with the  UNKNOWN  type
971                 and therefore will be ignored.
972
973       $<INSTALL_PREFIX>
974              Content  of  the  install prefix when the target is exported via
975              install(EXPORT), or when evaluated in the INSTALL_NAME_DIR prop‐
976              erty  or the INSTALL_NAME_DIR argument of install(RUNTIME_DEPEN‐
977              DENCY_SET), and empty otherwise.
978
979   Output-Related Expressions
980       $<TARGET_NAME:...>
981              Marks ... as being the name of a target.  This  is  required  if
982              exporting  targets  to  multiple dependent export sets.  The ...
983              must be a literal name of a target- it may not contain generator
984              expressions.
985
986       $<LINK_ONLY:...>
987              New in version 3.1.
988
989
990              Content  of  ... except when evaluated in a link interface while
991              propagating Target Usage Requirements, in which case it  is  the
992              empty  string.   Intended  for use only in an INTERFACE_LINK_LI‐
993              BRARIES target property, perhaps via the target_link_libraries()
994              command,  to specify private link dependencies without other us‐
995              age requirements.
996
997       $<INSTALL_INTERFACE:...>
998              Content of ... when the property is exported  using  install(EX‐
999              PORT), and empty otherwise.
1000
1001       $<BUILD_INTERFACE:...>
1002              Content  of ... when the property is exported using export(), or
1003              when the target is used by another target in the same  buildsys‐
1004              tem. Expands to the empty string otherwise.
1005
1006       $<MAKE_C_IDENTIFIER:...>
1007              Content of ... converted to a C identifier.  The conversion fol‐
1008              lows the same behavior as string(MAKE_C_IDENTIFIER).
1009
1010       $<TARGET_OBJECTS:objLib>
1011              New in version 3.1.
1012
1013
1014              List of objects resulting from build of objLib.
1015
1016       $<SHELL_PATH:...>
1017              New in version 3.4.
1018
1019
1020              Content of ... converted  to  shell  path  style.  For  example,
1021              slashes are converted to backslashes in Windows shells and drive
1022              letters are converted to posix paths in  MSYS  shells.  The  ...
1023              must be an absolute path.
1024
1025              New  in  version 3.14: The ... may be a semicolon-separated list
1026              of paths, in which case each path is converted individually  and
1027              a  result list is generated using the shell path separator (: on
1028              POSIX and ; on Windows).  Be sure to enclose the  argument  con‐
1029              taining this genex in double quotes in CMake source code so that
1030              ; does not split arguments.
1031
1032
1033       $<OUTPUT_CONFIG:...>
1034              New in version 3.20.
1035
1036
1037              Only valid in add_custom_command()  and  add_custom_target()  as
1038              the  outer-most  generator  expression in an argument.  With the
1039              Ninja Multi-Config generator, generator expressions in  ...  are
1040              evaluated  using  the  custom  command's  "output config".  With
1041              other generators, the content of ... is evaluated normally.
1042
1043       $<COMMAND_CONFIG:...>
1044              New in version 3.20.
1045
1046
1047              Only valid in add_custom_command()  and  add_custom_target()  as
1048              the  outer-most  generator  expression in an argument.  With the
1049              Ninja Multi-Config generator, generator expressions in  ...  are
1050              evaluated  using  the  custom  command's "command config".  With
1051              other generators, the content of ... is evaluated normally.
1052

DEBUGGING

1054       Since generator expressions are  evaluated  during  generation  of  the
1055       buildsystem,  and  not during processing of CMakeLists.txt files, it is
1056       not possible to inspect their result with the message() command.
1057
1058       One possible way to generate debug messages is to add a custom target,
1059
1060          add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
1061
1062       The shell command make genexdebug (invoked after  execution  of  cmake)
1063       would then print the result of $<...>.
1064
1065       Another way is to write debug messages to a file:
1066
1067          file(GENERATE OUTPUT filename CONTENT "$<...>")
1068
1070       2000-2021 Kitware, Inc. and Contributors
1071
1072
1073
1074
10753.22.0                           Dec 02, 2021   CMAKE-GENERATOR-EXPRESSIONS(7)
Impressum