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       This means that they enable conditional  linking,  conditional  defini‐
19       tions  used  when  compiling,  and  conditional include directories and
20       more.  The conditions may be based on the build  configuration,  target
21       properties, platform information or any other queryable information.
22

LOGICAL EXPRESSIONS

24       Logical  expressions  are used to create conditional output.  The basic
25       expressions are the 0 and 1 expressions.  Because other logical expres‐
26       sions  evaluate to either 0 or 1, they can be composed to create condi‐
27       tional output:
28
29          $<$<CONFIG:Debug>:DEBUG_MODE>
30
31       expands to DEBUG_MODE when the Debug configuration is used, and  other‐
32       wise expands to nothing.
33
34       Available logical expressions are:
35
36       $<BOOL:...>
37              1 if the ... is true, else 0
38
39       $<AND:?[,?]...>
40              1 if all ? are 1, else 0
41
42              The ? must always be either 0 or 1 in boolean expressions.
43
44       $<OR:?[,?]...>
45              0 if all ? are 0, else 1
46
47       $<NOT:?>
48              0 if ? is 1, else 1
49
50       $<IF:?,true-value...,false-value...>`
51              true-value... if ? is 1, false-value... if ? is 0
52
53       $<STREQUAL:a,b>
54              1 if a is STREQUAL b, else 0
55
56       $<EQUAL:a,b>
57              1 if a is EQUAL b in a numeric comparison, else 0
58
59       $<CONFIG:cfg>
60              1  if config is cfg, else 0. This is a case-insensitive compari‐
61              son.  The mapping in MAP_IMPORTED_CONFIG_<CONFIG> is  also  con‐
62              sidered by this expression when it is evaluated on a property on
63              an IMPORTED target.
64
65       $<PLATFORM_ID:comp>
66              1 if the CMake-id of the platform matches comp, otherwise 0.
67
68       $<C_COMPILER_ID:comp>
69              1 if the CMake-id of the C compiler matches comp, otherwise 0.
70
71       $<CXX_COMPILER_ID:comp>
72              1 if the CMake-id of the CXX compiler matches comp, otherwise 0.
73
74       $<VERSION_LESS:v1,v2>
75              1 if v1 is a version less than v2, else 0.
76
77       $<VERSION_GREATER:v1,v2>
78              1 if v1 is a version greater than v2, else 0.
79
80       $<VERSION_EQUAL:v1,v2>
81              1 if v1 is the same version as v2, else 0.
82
83       $<VERSION_LESS_EQUAL:v1,v2>
84              1 if v1 is a version less than or equal to v2, else 0.
85
86       $<VERSION_GREATER_EQUAL:v1,v2>
87              1 if v1 is a version greater than or equal to v2, else 0.
88
89       $<C_COMPILER_VERSION:ver>
90              1 if the version of the C compiler matches ver, otherwise 0.
91
92       $<CXX_COMPILER_VERSION:ver>
93              1 if the version of the CXX compiler matches ver, otherwise 0.
94
95       $<TARGET_POLICY:pol>
96              1 if the policy pol was NEW when the ‘head’ target was  created,
97              else  0.  If the policy was not set, the warning message for the
98              policy will be emitted. This generator expression only works for
99              a subset of policies.
100
101       $<COMPILE_FEATURES:feature[,feature]...>
102              1  if  all  of the feature features are available for the ‘head’
103              target, and 0 otherwise. If this expression is used while evalu‐
104              ating  the link implementation of a target and if any dependency
105              transitively increases the required C_STANDARD  or  CXX_STANDARD
106              for the ‘head’ target, an error is reported.  See the cmake-com‐
107              pile-features(7) manual for information on compile features  and
108              a list of supported compilers.
109
110       $<COMPILE_LANGUAGE:lang>
111              1 when the language used for compilation unit matches lang, oth‐
112              erwise 0.  This  expression  may  be  used  to  specify  compile
113              options, compile definitions, and include directories for source
114              files of a particular language in a target. For example:
115
116                 add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
117                 target_compile_options(myapp
118                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
119                 )
120                 target_compile_definitions(myapp
121                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
122                           $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
123                 )
124                 target_include_directories(myapp
125                   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
126                 )
127
128              This specifies the use of the  -fno-exceptions  compile  option,
129              COMPILING_CXX compile definition, and cxx_headers include direc‐
130              tory for C++ only (compiler id checks elided).  It  also  speci‐
131              fies a COMPILING_CUDA compile definition for CUDA.
132
133              Note  that  with  Visual Studio Generators and Xcode there is no
134              way to represent  target-wide  compile  definitions  or  include
135              directories separately for C and CXX languages.  Also, with Vis‐
136              ual Studio Generators there is no way to  represent  target-wide
137              flags  separately  for C and CXX languages.  Under these genera‐
138              tors, expressions for both C and C++ sources will  be  evaluated
139              using CXX if there are any C++ sources and otherwise using C.  A
140              workaround is to create separate libraries for each source  file
141              language instead:
142
143                 add_library(myapp_c foo.c)
144                 add_library(myapp_cxx bar.cpp)
145                 target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
146                 add_executable(myapp main.cpp)
147                 target_link_libraries(myapp myapp_c myapp_cxx)
148

INFORMATIONAL EXPRESSIONS

150       These  expressions  expand  to some information. The information may be
151       used directly, eg:
152
153          include_directories(/usr/include/$<CXX_COMPILER_ID>/)
154
155       expands to /usr/include/GNU/ or /usr/include/Clang/ etc,  depending  on
156       the Id of the compiler.
157
158       These expressions may also may be combined with logical expressions:
159
160          $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
161
162       expands  to OLD_COMPILER if the CMAKE_CXX_COMPILER_VERSION is less than
163       4.2.0.
164
165       Available informational expressions are:
166
167       $<CONFIGURATION>
168              Configuration name. Deprecated. Use CONFIG instead.
169
170       $<CONFIG>
171              Configuration name
172
173       $<PLATFORM_ID>
174              The CMake-id of the platform.  See  also  the  CMAKE_SYSTEM_NAME
175              variable.
176
177       $<C_COMPILER_ID>
178              The   CMake-id   of   the   C   compiler  used.   See  also  the
179              CMAKE_<LANG>_COMPILER_ID variable.
180
181       $<CXX_COMPILER_ID>
182              The  CMake-id  of  the  CXX  compiler  used.    See   also   the
183              CMAKE_<LANG>_COMPILER_ID variable.
184
185       $<C_COMPILER_VERSION>
186              The   version   of   the   C   compiler   used.   See  also  the
187              CMAKE_<LANG>_COMPILER_VERSION variable.
188
189       $<CXX_COMPILER_VERSION>
190              The  version  of  the  CXX  compiler   used.    See   also   the
191              CMAKE_<LANG>_COMPILER_VERSION variable.
192
193       $<TARGET_FILE:tgt>
194              Full path to main file (.exe, .so.1.2, .a) where tgt is the name
195              of a target.
196
197       $<TARGET_FILE_NAME:tgt>
198              Name of main file (.exe, .so.1.2, .a).
199
200       $<TARGET_FILE_DIR:tgt>
201              Directory of main file (.exe, .so.1.2, .a).
202
203       $<TARGET_LINKER_FILE:tgt>
204              File used to link (.a, .lib, .so) where tgt is  the  name  of  a
205              target.
206
207       $<TARGET_LINKER_FILE_NAME:tgt>
208              Name of file used to link (.a, .lib, .so).
209
210       $<TARGET_LINKER_FILE_DIR:tgt>
211              Directory of file used to link (.a, .lib, .so).
212
213       $<TARGET_SONAME_FILE:tgt>
214              File with soname (.so.3) where tgt is the name of a target.
215
216       $<TARGET_SONAME_FILE_NAME:tgt>
217              Name of file with soname (.so.3).
218
219       $<TARGET_SONAME_FILE_DIR:tgt>
220              Directory of with soname (.so.3).
221
222       $<TARGET_PDB_FILE:tgt>
223              Full  path  to the linker generated program database file (.pdb)
224              where tgt is the name of a target.
225
226              See also the PDB_NAME and PDB_OUTPUT_DIRECTORY target properties
227              and  their configuration specific variants PDB_NAME_<CONFIG> and
228              PDB_OUTPUT_DIRECTORY_<CONFIG>.
229
230       $<TARGET_PDB_FILE_NAME:tgt>
231              Name of the linker generated program database file (.pdb).
232
233       $<TARGET_PDB_FILE_DIR:tgt>
234              Directory of the linker generated program database file (.pdb).
235
236       $<TARGET_BUNDLE_DIR:tgt>
237              Full path to the  bundle  directory  (my.app,  my.framework,  or
238              my.bundle) where tgt is the name of a target.
239
240       $<TARGET_BUNDLE_CONTENT_DIR:tgt>
241              Full  path to the bundle content directory where tgt is the name
242              of a target. For the macOS  SDK  it  leads  to  my.app/Contents,
243              my.framework,  or  my.bundle/Contents.  For all other SDKs (e.g.
244              iOS) it leads to my.app, my.framework, or my.bundle due  to  the
245              flat bundle structure.
246
247       $<TARGET_PROPERTY:tgt,prop>
248              Value of the property prop on the target tgt.
249
250              Note  that  tgt  is not added as a dependency of the target this
251              expression is evaluated on.
252
253       $<TARGET_PROPERTY:prop>
254              Value of the property prop on the target on which the  generator
255              expression is evaluated.
256
257       $<INSTALL_PREFIX>
258              Content  of  the  install prefix when the target is exported via
259              install(EXPORT) and empty otherwise.
260
261       $<COMPILE_LANGUAGE>
262              The compile language of source  files  when  evaluating  compile
263              options.  See  the  unary version for notes about portability of
264              this generator expression.
265

OUTPUT EXPRESSIONS

267       These expressions generate output, in some cases depending on an input.
268       These  expressions  may be combined with other expressions for informa‐
269       tion or logical comparison:
270
271          -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
272
273       generates a string of the entries  in  the  INCLUDE_DIRECTORIES  target
274       property  with each entry preceded by -I. Note that a more-complete use
275       in this situation would require first checking if the  INCLUDE_DIRECTO‐
276       RIES property is non-empty:
277
278          $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
279
280       where ${prop} refers to a helper variable:
281
282          set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>")
283
284       Available output expressions are:
285
286       $<0:...>
287              Empty string (ignores ...)
288
289       $<1:...>
290              Content of ...
291
292       $<JOIN:list,...>
293              Joins the list with the content of ...
294
295       $<ANGLE-R>
296              A literal >. Used to compare strings which contain a > for exam‐
297              ple.
298
299       $<COMMA>
300              A literal ,. Used to compare strings which contain a , for exam‐
301              ple.
302
303       $<SEMICOLON>
304              A  literal ;. Used to prevent list expansion on an argument with
305              ;.
306
307       $<TARGET_NAME:...>
308              Marks ... as being the name of a target.  This  is  required  if
309              exporting  targets  to  multiple dependent export sets.  The ...
310              must be a literal name of a target- it may not contain generator
311              expressions.
312
313       $<LINK_ONLY:...>
314              Content  of  ... except when evaluated in a link interface while
315              propagating Target Usage Requirements, in which case it  is  the
316              empty   string.    Intended   for   use   only   in   an  INTER‐
317              FACE_LINK_LIBRARIES  target  property,  perhaps  via  the   tar‐
318              get_link_libraries()  command, to specify private link dependen‐
319              cies without other usage requirements.
320
321       $<INSTALL_INTERFACE:...>
322              Content  of  ...   when   the   property   is   exported   using
323              install(EXPORT), and empty otherwise.
324
325       $<BUILD_INTERFACE:...>
326              Content  of ... when the property is exported using export(), or
327              when the target is used by another target in the same  buildsys‐
328              tem. Expands to the empty string otherwise.
329
330       $<LOWER_CASE:...>
331              Content of ... converted to lower case.
332
333       $<UPPER_CASE:...>
334              Content of ... converted to upper case.
335
336       $<MAKE_C_IDENTIFIER:...>
337              Content of ... converted to a C identifier.
338
339       $<TARGET_OBJECTS:objLib>
340              List  of  objects resulting from build of objLib. objLib must be
341              an object of type OBJECT_LIBRARY.
342
343       $<SHELL_PATH:...>
344              Content of ... converted  to  shell  path  style.  For  example,
345              slashes are converted to backslashes in Windows shells and drive
346              letters are converted to posix paths in  MSYS  shells.  The  ...
347              must be an absolute path.
348
350       2000-2018 Kitware, Inc. and Contributors
351
352
353
354
3553.11.4                           May 13, 2019   CMAKE-GENERATOR-EXPRESSIONS(7)
Impressum