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(),    tar‐
16       get_include_directories(), 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
25       angular 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 according to the  rules  of  the  if()
40              command.  Evaluates to 0 if any of the following is true:
41
42              · string is empty,
43
44              · string  is  a  case-insensitive equal of 0, FALSE, OFF, N, NO,
45                IGNORE, or NOTFOUND, or
46
47              · string 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              1 if string is member of the comma-separated list, else 0.  Uses
77              case-sensitive comparisons.
78
79       $<VERSION_LESS:v1,v2>
80              1 if v1 is a version less than v2, else 0.
81
82       $<VERSION_GREATER:v1,v2>
83              1 if v1 is a version greater than v2, else 0.
84
85       $<VERSION_EQUAL:v1,v2>
86              1 if v1 is the same version as v2, else 0.
87
88       $<VERSION_LESS_EQUAL:v1,v2>
89              1 if v1 is a version less than or equal to v2, else 0.
90
91       $<VERSION_GREATER_EQUAL:v1,v2>
92              1 if v1 is a version greater than or equal to v2, else 0.
93
94   Variable Queries
95       $<TARGET_EXISTS:target>
96              1 if target exists, else 0.
97
98       $<CONFIG:cfg>
99              1  if config is cfg, else 0. This is a case-insensitive compari‐
100              son.  The mapping in MAP_IMPORTED_CONFIG_<CONFIG> is  also  con‐
101              sidered by this expression when it is evaluated on a property on
102              an IMPORTED target.
103
104       $<PLATFORM_ID:platform_id>
105              1 if the CMake-id of the platform matches platform_id  otherwise
106              0.  See also the CMAKE_SYSTEM_NAME variable.
107
108       $<C_COMPILER_ID:compiler_id>
109              1  if the CMake-id of the C compiler matches compiler_id, other‐
110              wise 0.  See also the CMAKE_<LANG>_COMPILER_ID variable.
111
112       $<CXX_COMPILER_ID:compiler_id>
113              1 if the CMake-id of the CXX compiler matches compiler_id,  oth‐
114              erwise 0.  See also the CMAKE_<LANG>_COMPILER_ID variable.
115
116       $<Fortran_COMPILER_ID:compiler_id>
117              1  if  the CMake-id of the Fortran compiler matches compiler_id,
118              otherwise 0.  See also the CMAKE_<LANG>_COMPILER_ID variable.
119
120       $<C_COMPILER_VERSION:version>
121              1 if the version of the C compiler matches version, otherwise 0.
122              See also the CMAKE_<LANG>_COMPILER_VERSION variable.
123
124       $<CXX_COMPILER_VERSION:version>
125              1  if the version of the CXX compiler matches version, otherwise
126              0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
127
128       $<Fortran_COMPILER_VERSION:version>
129              1 if the version of the Fortran compiler matches version, other‐
130              wise 0.  See also the CMAKE_<LANG>_COMPILER_VERSION variable.
131
132       $<TARGET_POLICY:policy>
133              1 if the policy was NEW when the ‘head’ target was created, else
134              0.  If the policy was not set, the warning message for the  pol‐
135              icy  will be emitted. This generator expression only works for a
136              subset of policies.
137
138       $<COMPILE_FEATURES:features>
139              where features is a comma-spearated list.  Evaluates to 1 if all
140              of  the features are available for the ‘head’ target, and 0 oth‐
141              erwise. If this expression is used  while  evaluating  the  link
142              implementation  of  a  target and if any dependency transitively
143              increases the required C_STANDARD or CXX_STANDARD for the ‘head’
144              target, an error is reported.  See the cmake-compile-features(7)
145              manual for information on compile features and a  list  of  sup‐
146              ported compilers.
147
148       $<COMPILE_LANGUAGE:language>
149              1  when the language used for compilation unit matches language,
150              otherwise 0.  This expression may be  used  to  specify  compile
151              options, compile definitions, and include directories for source
152              files of a particular language in a target. For example:
153
154                 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
155                 target_compile_options(myapp
156                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
157                 )
158                 target_compile_definitions(myapp
159                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
160                           $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
161                 )
162                 target_include_directories(myapp
163                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
164                 )
165
166              This specifies the use of the  -fno-exceptions  compile  option,
167              COMPILING_CXX compile definition, and cxx_headers include direc‐
168              tory for C++ only (compiler id checks elided).  It  also  speci‐
169              fies a COMPILING_CUDA compile definition for CUDA.
170
171              Note  that  with  Visual Studio Generators and Xcode there is no
172              way to represent  target-wide  compile  definitions  or  include
173              directories separately for C and CXX languages.  Also, with Vis‐
174              ual Studio Generators there is no way to  represent  target-wide
175              flags  separately  for C and CXX languages.  Under these genera‐
176              tors, expressions for both C and C++ sources will  be  evaluated
177              using CXX if there are any C++ sources and otherwise using C.  A
178              workaround is to create separate libraries for each source  file
179              language instead:
180
181                 add_library(myapp_c foo.c)
182                 add_library(myapp_cxx bar.cpp)
183                 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
184                 add_executable(myapp main.cpp)
185                 target_link_libraries(myapp myapp_c myapp_cxx)
186

STRING-VALUED GENERATOR EXPRESSIONS

188       These expressions expand to some string.  For example,
189
190          include_directories(/usr/include/$<CXX_COMPILER_ID>/)
191
192       expands  to  /usr/include/GNU/ or /usr/include/Clang/ etc, depending on
193       the compiler identifier.
194
195       String-valued expressions may also be combined with other  expressions.
196       Here an example for a string-valued expression within a boolean expres‐
197       sions within a conditional expression:
198
199          $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
200
201       expands to OLD_COMPILER if the CMAKE_CXX_COMPILER_VERSION is less  than
202       4.2.0.
203
204       And here two nested string-valued expressions:
205
206          -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
207
208       generates  a  string  of  the entries in the INCLUDE_DIRECTORIES target
209       property with each entry preceded by -I.
210
211       Expanding on the previous example, if one first wants to check  if  the
212       INCLUDE_DIRECTORIES  property  is  non-empty,  then  it is advisable to
213       introduce a helper variable to keep the code readable:
214
215          set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
216          $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
217
218       The following string-valued generator expressions are available:
219
220   Escaped Characters
221       String literals to escape the special meaning a character would  other‐
222       wise have:
223
224       $<ANGLE-R>
225              A  literal >. Used for example to compare strings that contain a
226              >.
227
228       $<COMMA>
229              A literal ,. Used for example to compare strings which contain a
230              ,.
231
232       $<SEMICOLON>
233              A  literal ;. Used to prevent list expansion on an argument with
234              ;.
235
236   Conditional Expressions
237       Conditional generator expressions depend on a  boolean  condition  that
238       must be 0 or 1.
239
240       $<condition:true_string>
241              Evaluates to true_string if condition is 1.  Otherwise evaluates
242              to the empty string.
243
244       $<IF:condition,true_string,false_string>
245              Evaluates to true_string if condition is 1.  Otherwise evaluates
246              to false_string.
247
248       Typically,  the  condition  is  a  boolean  generator  expression.  For
249       instance,
250
251          $<$<CONFIG:Debug>:DEBUG_MODE>
252
253       expands to DEBUG_MODE when the Debug configuration is used, and  other‐
254       wise expands to the empty string.
255
256   String Transformations
257       $<JOIN:list,string>
258              Joins the list with the content of string.
259
260       $<LOWER_CASE:string>
261              Content of string converted to lower case.
262
263       $<UPPER_CASE:string>
264              Content of string converted to upper case.
265
266       $<GENEX_EVAL:expr>
267              Content  of expr evaluated as a generator expression in the cur‐
268              rent context. This enables consumption of generator  expressions
269              whose evaluation results itself in generator expressions.
270
271       $<TARGET_GENEX_EVAL:tgt,expr>
272              Content  of expr evaluated as a generator expression in the con‐
273              text of tgt target. This enables consumption  of  custom  target
274              properties that themselves contain generator expressions.
275
276              Having  the capability to evaluate generator expressions is very
277              useful when you want to manage custom properties supporting gen‐
278              erator expressions.  For example:
279
280                 add_library(foo ...)
281
282                 set_property(TARGET foo PROPERTY
283                   CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
284                 )
285
286                 add_custom_target(printFooKeys
287                   COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
288                 )
289
290              This  naive implementation of the printFooKeys custom command is
291              wrong because CUSTOM_KEYS target property is not  evaluated  and
292              the     content    is    passed    as    is    (i.e.    $<$<CON‐
293              FIG:DEBUG>:FOO_EXTRA_THINGS>).
294
295              To have the expected result (i.e. FOO_EXTRA_THINGS if config  is
296              Debug),  it is required to evaluate the output of $<TARGET_PROP‐
297              ERTY:foo,CUSTOM_KEYS>:
298
299                 add_custom_target(printFooKeys
300                   COMMAND ${CMAKE_COMMAND} -E
301                     echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
302                 )
303
304   Variable Queries
305       $<CONFIG>
306              Configuration name.
307
308       $<CONFIGURATION>
309              Configuration name.  Deprecated  since  CMake  3.0.  Use  CONFIG
310              instead.
311
312       $<PLATFORM_ID>
313              The  CMake-id  of  the platform.  See also the CMAKE_SYSTEM_NAME
314              variable.
315
316       $<C_COMPILER_ID>
317              The  CMake-id  of  the  C   compiler   used.    See   also   the
318              CMAKE_<LANG>_COMPILER_ID variable.
319
320       $<CXX_COMPILER_ID>
321              The   CMake-id   of   the  CXX  compiler  used.   See  also  the
322              CMAKE_<LANG>_COMPILER_ID variable.
323
324       $<Fortran_COMPILER_ID>
325              The CMake-id  of  the  Fortran  compiler  used.   See  also  the
326              CMAKE_<LANG>_COMPILER_ID variable.
327
328       $<C_COMPILER_VERSION>
329              The   version   of   the   C   compiler   used.   See  also  the
330              CMAKE_<LANG>_COMPILER_VERSION variable.
331
332       $<CXX_COMPILER_VERSION>
333              The  version  of  the  CXX  compiler   used.    See   also   the
334              CMAKE_<LANG>_COMPILER_VERSION variable.
335
336       $<Fortran_COMPILER_VERSION>
337              The  version  of  the  Fortran  compiler  used.   See  also  the
338              CMAKE_<LANG>_COMPILER_VERSION variable.
339
340       $<COMPILE_LANGUAGE>
341              The compile language of source  files  when  evaluating  compile
342              options.   See  the  related  boolean  expression $<COMPILE_LAN‐
343              GUAGE:language> for notes about the portability of this  genera‐
344              tor expression.
345
346   Target-Dependent Queries
347       $<TARGET_NAME_IF_EXISTS:tgt>
348              Expands  to  the tgt if the given target exists, an empty string
349              otherwise.
350
351       $<TARGET_FILE:tgt>
352              Full path to main file (.exe, .so.1.2, .a) where tgt is the name
353              of a target.
354
355       $<TARGET_FILE_NAME:tgt>
356              Name of main file (.exe, .so.1.2, .a).
357
358       $<TARGET_FILE_DIR:tgt>
359              Directory of main file (.exe, .so.1.2, .a).
360
361       $<TARGET_LINKER_FILE:tgt>
362              File  used  to  link  (.a, .lib, .so) where tgt is the name of a
363              target.
364
365       $<TARGET_LINKER_FILE_NAME:tgt>
366              Name of file used to link (.a, .lib, .so).
367
368       $<TARGET_LINKER_FILE_DIR:tgt>
369              Directory of file used to link (.a, .lib, .so).
370
371       $<TARGET_SONAME_FILE:tgt>
372              File with soname (.so.3) where tgt is the name of a target.
373
374       $<TARGET_SONAME_FILE_NAME:tgt>
375              Name of file with soname (.so.3).
376
377       $<TARGET_SONAME_FILE_DIR:tgt>
378              Directory of with soname (.so.3).
379
380       $<TARGET_PDB_FILE:tgt>
381              Full path to the linker generated program database  file  (.pdb)
382              where tgt is the name of a target.
383
384              See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
385              and their configuration specific variants PDB_NAME_<CONFIG>  and
386              PDB_OUTPUT_DIRECTORY_<CONFIG>.
387
388       $<TARGET_PDB_FILE_NAME:tgt>
389              Name of the linker generated program database file (.pdb).
390
391       $<TARGET_PDB_FILE_DIR:tgt>
392              Directory of the linker generated program database file (.pdb).
393
394       $<TARGET_BUNDLE_DIR:tgt>
395              Full  path  to  the  bundle  directory (my.app, my.framework, or
396              my.bundle) where tgt is the name of a target.
397
398       $<TARGET_BUNDLE_CONTENT_DIR:tgt>
399              Full path to the bundle content directory where tgt is the  name
400              of  a  target.  For  the  macOS SDK it leads to my.app/Contents,
401              my.framework, or my.bundle/Contents. For all  other  SDKs  (e.g.
402              iOS)  it  leads to my.app, my.framework, or my.bundle due to the
403              flat bundle structure.
404
405       $<TARGET_PROPERTY:tgt,prop>
406              Value of the property prop on the target tgt.
407
408              Note that tgt is not added as a dependency of  the  target  this
409              expression is evaluated on.
410
411       $<TARGET_PROPERTY:prop>
412              Value  of the property prop on the target on which the generator
413              expression is evaluated. Note that for generator expressions  in
414              Target  Usage  Requirements this is the value of the property on
415              the consuming target  rather  than  the  target  specifying  the
416              requirement.
417
418       $<INSTALL_PREFIX>
419              Content  of  the  install prefix when the target is exported via
420              install(EXPORT) and empty otherwise.
421
422   Output-Related Expressions
423       $<TARGET_NAME:...>
424              Marks ... as being the name of a target.  This  is  required  if
425              exporting  targets  to  multiple dependent export sets.  The ...
426              must be a literal name of a target- it may not contain generator
427              expressions.
428
429       $<LINK_ONLY:...>
430              Content  of  ... except when evaluated in a link interface while
431              propagating Target Usage Requirements, in which case it  is  the
432              empty   string.    Intended   for   use   only   in   an  INTER‐
433              FACE_LINK_LIBRARIES  target  property,  perhaps  via  the   tar‐
434              get_link_libraries()  command, to specify private link dependen‐
435              cies without other usage requirements.
436
437       $<INSTALL_INTERFACE:...>
438              Content  of  ...   when   the   property   is   exported   using
439              install(EXPORT), and empty otherwise.
440
441       $<BUILD_INTERFACE:...>
442              Content  of ... when the property is exported using export(), or
443              when the target is used by another target in the same  buildsys‐
444              tem. Expands to the empty string otherwise.
445
446       $<MAKE_C_IDENTIFIER:...>
447              Content of ... converted to a C identifier.  The conversion fol‐
448              lows the same behavior as string(MAKE_C_IDENTIFIER).
449
450       $<TARGET_OBJECTS:objLib>
451              List of objects resulting from build of objLib. objLib  must  be
452              an object of type OBJECT_LIBRARY.
453
454       $<SHELL_PATH:...>
455              Content  of  ...  converted  to  shell  path style. For example,
456              slashes are converted to backslashes in Windows shells and drive
457              letters  are  converted  to  posix paths in MSYS shells. The ...
458              must be an absolute path.
459

DEBUGGING

461       Since generator expressions are  evaluated  during  generation  of  the
462       buildsystem,  and  not during processing of CMakeLists.txt files, it is
463       not possible to inspect their result with the message() command.
464
465       One possible way to generate debug messages is to add a custom target,
466
467          add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
468
469       The shell command make genexdebug (invoked after  execution  of  cmake)
470       would then print the result of $<...>.
471
472       Another way is to write debug messages to a file:
473
474          file(GENERATE OUTPUT filename CONTENT "$<...>")
475
477       2000-2019 Kitware, Inc. and Contributors
478
479
480
481
4823.14.5                           Jun 01, 2019   CMAKE-GENERATOR-EXPRESSIONS(7)
Impressum