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.
11 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 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
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 $<$<CONFIG:Debug>:DEBUG_MODE>
30 expands to DEBUG_MODE when the Debug configuration is used, and other‐
32 wise expands to nothing.
33 Available logical expressions are:
35 $<BOOL:...>
37 1 if the ... is true, else 0
38 $<AND:?[,?]...>
40 1 if all ? are 1, else 0
41 The ? must always be either 0 or 1 in boolean expressions.
43 $<OR:?[,?]...>
45 0 if all ? are 0, else 1
46 $<NOT:?>
48 0 if ? is 1, else 1
49 $<IF:?,true-value...,false-value...>`
51 true-value... if ? is 1, false-value... if ? is 0
52 $<STREQUAL:a,b>
54 1 if a is STREQUAL b, else 0
55 $<EQUAL:a,b>
57 1 if a is EQUAL b in a numeric comparison, else 0
58 $<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 $<PLATFORM_ID:comp>
66 1 if the CMake-id of the platform matches comp, otherwise 0.
67 $<C_COMPILER_ID:comp>
69 1 if the CMake-id of the C compiler matches comp, otherwise 0.
70 $<CXX_COMPILER_ID:comp>
72 1 if the CMake-id of the CXX compiler matches comp, otherwise 0.
73 $<VERSION_LESS:v1,v2>
75 1 if v1 is a version less than v2, else 0.
76 $<VERSION_GREATER:v1,v2>
78 1 if v1 is a version greater than v2, else 0.
79 $<VERSION_EQUAL:v1,v2>
81 1 if v1 is the same version as v2, else 0.
82 $<VERSION_LESS_EQUAL:v1,v2>
84 1 if v1 is a version less than or equal to v2, else 0.
85 $<VERSION_GREATER_EQUAL:v1,v2>
87 1 if v1 is a version greater than or equal to v2, else 0.
88 $<C_COMPILER_VERSION:ver>
90 1 if the version of the C compiler matches ver, otherwise 0.
91 $<CXX_COMPILER_VERSION:ver>
93 1 if the version of the CXX compiler matches ver, otherwise 0.
94 $<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 $<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 $<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 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 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 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 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
150 These expressions expand to some information. The information may be
151 used directly, eg:
152 include_directories(/usr/include/$<CXX_COMPILER_ID>/)
154 expands to /usr/include/GNU/ or /usr/include/Clang/ etc, depending on
156 the Id of the compiler.
157 These expressions may also may be combined with logical expressions:
159 $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
161 expands to OLD_COMPILER if the CMAKE_CXX_COMPILER_VERSION is less than
163 4.2.0.
164 Available informational expressions are:
166 $<CONFIGURATION>
168 Configuration name. Deprecated. Use CONFIG instead.
169 $<CONFIG>
171 Configuration name
172 $<PLATFORM_ID>
174 The CMake-id of the platform. See also the CMAKE_SYSTEM_NAME
175 variable.
176 $<C_COMPILER_ID>
178 The CMake-id of the C compiler used. See also the
179 CMAKE_<LANG>_COMPILER_ID variable.
180 $<CXX_COMPILER_ID>
182 The CMake-id of the CXX compiler used. See also the
183 CMAKE_<LANG>_COMPILER_ID variable.
184 $<C_COMPILER_VERSION>
186 The version of the C compiler used. See also the
187 CMAKE_<LANG>_COMPILER_VERSION variable.
188 $<CXX_COMPILER_VERSION>
190 The version of the CXX compiler used. See also the
191 CMAKE_<LANG>_COMPILER_VERSION variable.
192 $<TARGET_FILE:tgt>
194 Full path to main file (.exe, .so.1.2, .a) where tgt is the name
195 of a target.
196 $<TARGET_FILE_NAME:tgt>
198 Name of main file (.exe, .so.1.2, .a).
199 $<TARGET_FILE_DIR:tgt>
201 Directory of main file (.exe, .so.1.2, .a).
202 $<TARGET_LINKER_FILE:tgt>
204 File used to link (.a, .lib, .so) where tgt is the name of a
205 target.
206 $<TARGET_LINKER_FILE_NAME:tgt>
208 Name of file used to link (.a, .lib, .so).
209 $<TARGET_LINKER_FILE_DIR:tgt>
211 Directory of file used to link (.a, .lib, .so).
212 $<TARGET_SONAME_FILE:tgt>
214 File with soname (.so.3) where tgt is the name of a target.
215 $<TARGET_SONAME_FILE_NAME:tgt>
217 Name of file with soname (.so.3).
218 $<TARGET_SONAME_FILE_DIR:tgt>
220 Directory of with soname (.so.3).
221 $<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 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 $<TARGET_PDB_FILE_NAME:tgt>
231 Name of the linker generated program database file (.pdb).
232 $<TARGET_PDB_FILE_DIR:tgt>
234 Directory of the linker generated program database file (.pdb).
235 $<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 $<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 $<TARGET_PROPERTY:tgt,prop>
248 Value of the property prop on the target tgt.
249 Note that tgt is not added as a dependency of the target this
251 expression is evaluated on.
252 $<TARGET_PROPERTY:prop>
254 Value of the property prop on the target on which the generator
255 expression is evaluated.
256 $<INSTALL_PREFIX>
258 Content of the install prefix when the target is exported via
259 install(EXPORT) and empty otherwise.
260 $<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
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 -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
272 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 $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
279 where ${prop} refers to a helper variable:
281 set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>")
283 Available output expressions are:
285 $<0:...>
287 Empty string (ignores ...)
288 $<1:...>
290 Content of ...
291 $<JOIN:list,...>
293 Joins the list with the content of ...
294 $<ANGLE-R>
296 A literal >. Used to compare strings which contain a > for exam‐
297 ple.
298 $<COMMA>
300 A literal ,. Used to compare strings which contain a , for exam‐
301 ple.
302 $<SEMICOLON>
304 A literal ;. Used to prevent list expansion on an argument with
305 ;.
306 $<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 $<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 $<INSTALL_INTERFACE:...>
322 Content of ... when the property is exported using
323 install(EXPORT), and empty otherwise.
324 $<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 $<LOWER_CASE:...>
331 Content of ... converted to lower case.
332 $<UPPER_CASE:...>
334 Content of ... converted to upper case.
335 $<MAKE_C_IDENTIFIER:...>
337 Content of ... converted to a C identifier.
338 $<TARGET_OBJECTS:objLib>
340 List of objects resulting from build of objLib. objLib must be
341 an object of type OBJECT_LIBRARY.
342 $<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
3513.11.4 May 13, 2019 CMAKE-GENERATOR-EXPRESSIONS(7)