Ryan Prichard | f6283ab | 2022-01-13 17:30:19 -0800 | [diff] [blame] | 1 | .. cmake-manual-description: CMake Generator Expressions |
| 2 | |
| 3 | cmake-generator-expressions(7) |
| 4 | ****************************** |
| 5 | |
| 6 | .. only:: html |
| 7 | |
| 8 | .. contents:: |
| 9 | |
| 10 | Introduction |
| 11 | ============ |
| 12 | |
| 13 | Generator expressions are evaluated during build system generation to produce |
| 14 | information specific to each build configuration. |
| 15 | |
| 16 | Generator expressions are allowed in the context of many target properties, |
| 17 | such as :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`, |
| 18 | :prop_tgt:`COMPILE_DEFINITIONS` and others. They may also be used when using |
| 19 | commands to populate those properties, such as :command:`target_link_libraries`, |
| 20 | :command:`target_include_directories`, :command:`target_compile_definitions` |
| 21 | and others. |
| 22 | |
| 23 | They enable conditional linking, conditional definitions used when compiling, |
| 24 | conditional include directories, and more. The conditions may be based on |
| 25 | the build configuration, target properties, platform information or any other |
| 26 | queryable information. |
| 27 | |
| 28 | Generator expressions have the form ``$<...>``. To avoid confusion, this page |
| 29 | deviates from most of the CMake documentation in that it omits angular brackets |
| 30 | ``<...>`` around placeholders like ``condition``, ``string``, ``target``, |
| 31 | among others. |
| 32 | |
| 33 | Generator expressions can be nested, as shown in most of the examples below. |
| 34 | |
| 35 | .. _`Boolean Generator Expressions`: |
| 36 | |
| 37 | Boolean Generator Expressions |
| 38 | ============================= |
| 39 | |
| 40 | Boolean expressions evaluate to either ``0`` or ``1``. |
| 41 | They are typically used to construct the condition in a :ref:`conditional |
| 42 | generator expression<Conditional Generator Expressions>`. |
| 43 | |
| 44 | Available boolean expressions are: |
| 45 | |
| 46 | Logical Operators |
| 47 | ----------------- |
| 48 | |
| 49 | .. genex:: $<BOOL:string> |
| 50 | |
| 51 | Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the |
| 52 | following is true: |
| 53 | |
| 54 | * ``string`` is empty, |
| 55 | * ``string`` is a case-insensitive equal of |
| 56 | ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or |
| 57 | * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive). |
| 58 | |
| 59 | Otherwise evaluates to ``1``. |
| 60 | |
| 61 | .. genex:: $<AND:conditions> |
| 62 | |
| 63 | where ``conditions`` is a comma-separated list of boolean expressions. |
| 64 | Evaluates to ``1`` if all conditions are ``1``. |
| 65 | Otherwise evaluates to ``0``. |
| 66 | |
| 67 | .. genex:: $<OR:conditions> |
| 68 | |
| 69 | where ``conditions`` is a comma-separated list of boolean expressions. |
| 70 | Evaluates to ``1`` if at least one of the conditions is ``1``. |
| 71 | Otherwise evaluates to ``0``. |
| 72 | |
| 73 | .. genex:: $<NOT:condition> |
| 74 | |
| 75 | ``0`` if ``condition`` is ``1``, else ``1``. |
| 76 | |
| 77 | String Comparisons |
| 78 | ------------------ |
| 79 | |
| 80 | .. genex:: $<STREQUAL:string1,string2> |
| 81 | |
| 82 | ``1`` if ``string1`` and ``string2`` are equal, else ``0``. |
| 83 | The comparison is case-sensitive. For a case-insensitive comparison, |
| 84 | combine with a :ref:`string transforming generator expression |
| 85 | <String Transforming Generator Expressions>`, |
| 86 | |
| 87 | .. code-block:: cmake |
| 88 | |
| 89 | $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... |
| 90 | |
| 91 | .. genex:: $<EQUAL:value1,value2> |
| 92 | |
| 93 | ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. |
| 94 | |
| 95 | .. genex:: $<IN_LIST:string,list> |
| 96 | |
| 97 | .. versionadded:: 3.12 |
| 98 | |
| 99 | ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. |
| 100 | Uses case-sensitive comparisons. |
| 101 | |
| 102 | .. genex:: $<VERSION_LESS:v1,v2> |
| 103 | |
| 104 | ``1`` if ``v1`` is a version less than ``v2``, else ``0``. |
| 105 | |
| 106 | .. genex:: $<VERSION_GREATER:v1,v2> |
| 107 | |
| 108 | ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. |
| 109 | |
| 110 | .. genex:: $<VERSION_EQUAL:v1,v2> |
| 111 | |
| 112 | ``1`` if ``v1`` is the same version as ``v2``, else ``0``. |
| 113 | |
| 114 | .. genex:: $<VERSION_LESS_EQUAL:v1,v2> |
| 115 | |
| 116 | .. versionadded:: 3.7 |
| 117 | |
| 118 | ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. |
| 119 | |
| 120 | .. genex:: $<VERSION_GREATER_EQUAL:v1,v2> |
| 121 | |
| 122 | .. versionadded:: 3.7 |
| 123 | |
| 124 | ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. |
| 125 | |
| 126 | Variable Queries |
| 127 | ---------------- |
| 128 | |
| 129 | .. genex:: $<TARGET_EXISTS:target> |
| 130 | |
| 131 | .. versionadded:: 3.12 |
| 132 | |
| 133 | ``1`` if ``target`` exists, else ``0``. |
| 134 | |
| 135 | .. genex:: $<CONFIG:cfgs> |
| 136 | |
| 137 | ``1`` if config is any one of the entries in comma-separated list |
| 138 | ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in |
| 139 | :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this |
| 140 | expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` |
| 141 | target. |
| 142 | |
| 143 | .. genex:: $<PLATFORM_ID:platform_ids> |
| 144 | |
| 145 | where ``platform_ids`` is a comma-separated list. |
| 146 | ``1`` if the CMake's platform id matches any one of the entries in |
| 147 | ``platform_ids``, otherwise ``0``. |
| 148 | See also the :variable:`CMAKE_SYSTEM_NAME` variable. |
| 149 | |
| 150 | .. genex:: $<C_COMPILER_ID:compiler_ids> |
| 151 | |
| 152 | where ``compiler_ids`` is a comma-separated list. |
| 153 | ``1`` if the CMake's compiler id of the C compiler matches any one |
| 154 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 155 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 156 | |
| 157 | .. genex:: $<CXX_COMPILER_ID:compiler_ids> |
| 158 | |
| 159 | where ``compiler_ids`` is a comma-separated list. |
| 160 | ``1`` if the CMake's compiler id of the CXX compiler matches any one |
| 161 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 162 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 163 | |
| 164 | .. genex:: $<CUDA_COMPILER_ID:compiler_ids> |
| 165 | |
| 166 | .. versionadded:: 3.15 |
| 167 | |
| 168 | where ``compiler_ids`` is a comma-separated list. |
| 169 | ``1`` if the CMake's compiler id of the CUDA compiler matches any one |
| 170 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 171 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 172 | |
| 173 | .. genex:: $<OBJC_COMPILER_ID:compiler_ids> |
| 174 | |
| 175 | .. versionadded:: 3.16 |
| 176 | |
| 177 | where ``compiler_ids`` is a comma-separated list. |
| 178 | ``1`` if the CMake's compiler id of the Objective-C compiler matches any one |
| 179 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 180 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 181 | |
| 182 | .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> |
| 183 | |
| 184 | .. versionadded:: 3.16 |
| 185 | |
| 186 | where ``compiler_ids`` is a comma-separated list. |
| 187 | ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one |
| 188 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 189 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 190 | |
| 191 | .. genex:: $<Fortran_COMPILER_ID:compiler_ids> |
| 192 | |
| 193 | where ``compiler_ids`` is a comma-separated list. |
| 194 | ``1`` if the CMake's compiler id of the Fortran compiler matches any one |
| 195 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 196 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 197 | |
| 198 | .. genex:: $<HIP_COMPILER_ID:compiler_ids> |
| 199 | |
| 200 | where ``compiler_ids`` is a comma-separated list. |
| 201 | ``1`` if the CMake's compiler id of the HIP compiler matches any one |
| 202 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 203 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 204 | |
| 205 | .. genex:: $<ISPC_COMPILER_ID:compiler_ids> |
| 206 | |
| 207 | .. versionadded:: 3.19 |
| 208 | |
| 209 | where ``compiler_ids`` is a comma-separated list. |
| 210 | ``1`` if the CMake's compiler id of the ISPC compiler matches any one |
| 211 | of the entries in ``compiler_ids``, otherwise ``0``. |
| 212 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 213 | |
| 214 | .. genex:: $<C_COMPILER_VERSION:version> |
| 215 | |
| 216 | ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. |
| 217 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 218 | |
| 219 | .. genex:: $<CXX_COMPILER_VERSION:version> |
| 220 | |
| 221 | ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. |
| 222 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 223 | |
| 224 | .. genex:: $<CUDA_COMPILER_VERSION:version> |
| 225 | |
| 226 | .. versionadded:: 3.15 |
| 227 | |
| 228 | ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. |
| 229 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 230 | |
| 231 | .. genex:: $<OBJC_COMPILER_VERSION:version> |
| 232 | |
| 233 | .. versionadded:: 3.16 |
| 234 | |
| 235 | ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. |
| 236 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 237 | |
| 238 | .. genex:: $<OBJCXX_COMPILER_VERSION:version> |
| 239 | |
| 240 | .. versionadded:: 3.16 |
| 241 | |
| 242 | ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. |
| 243 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 244 | |
| 245 | .. genex:: $<Fortran_COMPILER_VERSION:version> |
| 246 | |
| 247 | ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. |
| 248 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 249 | |
| 250 | .. genex:: $<HIP_COMPILER_VERSION:version> |
| 251 | |
| 252 | ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. |
| 253 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 254 | |
| 255 | .. genex:: $<ISPC_COMPILER_VERSION:version> |
| 256 | |
| 257 | .. versionadded:: 3.19 |
| 258 | |
| 259 | ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. |
| 260 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 261 | |
| 262 | .. genex:: $<TARGET_POLICY:policy> |
| 263 | |
| 264 | ``1`` if the ``policy`` was NEW when the 'head' target was created, |
| 265 | else ``0``. If the ``policy`` was not set, the warning message for the policy |
| 266 | will be emitted. This generator expression only works for a subset of |
| 267 | policies. |
| 268 | |
| 269 | .. genex:: $<COMPILE_FEATURES:features> |
| 270 | |
| 271 | .. versionadded:: 3.1 |
| 272 | |
| 273 | where ``features`` is a comma-spearated list. |
| 274 | Evaluates to ``1`` if all of the ``features`` are available for the 'head' |
| 275 | target, and ``0`` otherwise. If this expression is used while evaluating |
| 276 | the link implementation of a target and if any dependency transitively |
| 277 | increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` |
| 278 | for the 'head' target, an error is reported. See the |
| 279 | :manual:`cmake-compile-features(7)` manual for information on |
| 280 | compile features and a list of supported compilers. |
| 281 | |
| 282 | .. _`Boolean COMPILE_LANGUAGE Generator Expression`: |
| 283 | |
| 284 | .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> |
| 285 | |
| 286 | .. versionadded:: 3.15 |
| 287 | |
| 288 | ``1`` when the language used for compilation unit matches ``language`` and |
| 289 | the CMake's compiler id of the language compiler matches any one of the |
| 290 | entries in ``compiler_ids``, otherwise ``0``. This expression is a short form |
| 291 | for the combination of ``$<COMPILE_LANGUAGE:language>`` and |
| 292 | ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify |
| 293 | compile options, compile definitions, and include directories for source files of a |
| 294 | particular language and compiler combination in a target. For example: |
| 295 | |
| 296 | .. code-block:: cmake |
| 297 | |
| 298 | add_executable(myapp main.cpp foo.c bar.cpp zot.cu) |
| 299 | target_compile_definitions(myapp |
| 300 | PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> |
| 301 | $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> |
| 302 | $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> |
| 303 | ) |
| 304 | |
| 305 | This specifies the use of different compile definitions based on both |
| 306 | the compiler id and compilation language. This example will have a |
| 307 | ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX |
| 308 | compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. |
| 309 | Likewise when the C compiler is Clang it will only see the ``COMPILING_C_WITH_CLANG`` |
| 310 | definition. |
| 311 | |
| 312 | Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic |
| 313 | would be expressed as: |
| 314 | |
| 315 | .. code-block:: cmake |
| 316 | |
| 317 | target_compile_definitions(myapp |
| 318 | PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> |
| 319 | $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> |
| 320 | $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> |
| 321 | ) |
| 322 | |
| 323 | .. genex:: $<COMPILE_LANGUAGE:languages> |
| 324 | |
| 325 | .. versionadded:: 3.3 |
| 326 | |
| 327 | ``1`` when the language used for compilation unit matches any of the entries |
| 328 | in ``languages``, otherwise ``0``. This expression may be used to specify |
| 329 | compile options, compile definitions, and include directories for source files of a |
| 330 | particular language in a target. For example: |
| 331 | |
| 332 | .. code-block:: cmake |
| 333 | |
| 334 | add_executable(myapp main.cpp foo.c bar.cpp zot.cu) |
| 335 | target_compile_options(myapp |
| 336 | PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> |
| 337 | ) |
| 338 | target_compile_definitions(myapp |
| 339 | PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> |
| 340 | $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA> |
| 341 | ) |
| 342 | target_include_directories(myapp |
| 343 | PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers> |
| 344 | ) |
| 345 | |
| 346 | This specifies the use of the ``-fno-exceptions`` compile option, |
| 347 | ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include |
| 348 | directory for C++ only (compiler id checks elided). It also specifies |
| 349 | a ``COMPILING_CUDA`` compile definition for CUDA. |
| 350 | |
| 351 | Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there |
| 352 | is no way to represent target-wide compile definitions or include directories |
| 353 | separately for ``C`` and ``CXX`` languages. |
| 354 | Also, with :ref:`Visual Studio Generators` there is no way to represent |
| 355 | target-wide flags separately for ``C`` and ``CXX`` languages. Under these |
| 356 | generators, expressions for both C and C++ sources will be evaluated |
| 357 | using ``CXX`` if there are any C++ sources and otherwise using ``C``. |
| 358 | A workaround is to create separate libraries for each source file language |
| 359 | instead: |
| 360 | |
| 361 | .. code-block:: cmake |
| 362 | |
| 363 | add_library(myapp_c foo.c) |
| 364 | add_library(myapp_cxx bar.cpp) |
| 365 | target_compile_options(myapp_cxx PUBLIC -fno-exceptions) |
| 366 | add_executable(myapp main.cpp) |
| 367 | target_link_libraries(myapp myapp_c myapp_cxx) |
| 368 | |
| 369 | .. _`Boolean LINK_LANGUAGE Generator Expression`: |
| 370 | |
| 371 | .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> |
| 372 | |
| 373 | .. versionadded:: 3.18 |
| 374 | |
| 375 | ``1`` when the language used for link step matches ``language`` and the |
| 376 | CMake's compiler id of the language linker matches any one of the entries |
| 377 | in ``compiler_ids``, otherwise ``0``. This expression is a short form for the |
| 378 | combination of ``$<LINK_LANGUAGE:language>`` and |
| 379 | ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify |
| 380 | link libraries, link options, link directories and link dependencies of a |
| 381 | particular language and linker combination in a target. For example: |
| 382 | |
| 383 | .. code-block:: cmake |
| 384 | |
| 385 | add_library(libC_Clang ...) |
| 386 | add_library(libCXX_Clang ...) |
| 387 | add_library(libC_Intel ...) |
| 388 | add_library(libCXX_Intel ...) |
| 389 | |
| 390 | add_executable(myapp main.c) |
| 391 | if (CXX_CONFIG) |
| 392 | target_sources(myapp PRIVATE file.cxx) |
| 393 | endif() |
| 394 | target_link_libraries(myapp |
| 395 | PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang> |
| 396 | $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang> |
| 397 | $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel> |
| 398 | $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>) |
| 399 | |
| 400 | This specifies the use of different link libraries based on both the |
| 401 | compiler id and link language. This example will have target ``libCXX_Clang`` |
| 402 | as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` |
| 403 | linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. |
| 404 | Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target |
| 405 | ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when |
| 406 | ``Intel`` is the ``C`` linker. |
| 407 | |
| 408 | See :ref:`the note related to |
| 409 | <Constraints LINK_LANGUAGE Generator Expression>` |
| 410 | ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this |
| 411 | generator expression. |
| 412 | |
| 413 | .. genex:: $<LINK_LANGUAGE:languages> |
| 414 | |
| 415 | .. versionadded:: 3.18 |
| 416 | |
| 417 | ``1`` when the language used for link step matches any of the entries |
| 418 | in ``languages``, otherwise ``0``. This expression may be used to specify |
| 419 | link libraries, link options, link directories and link dependencies of a |
| 420 | particular language in a target. For example: |
| 421 | |
| 422 | .. code-block:: cmake |
| 423 | |
| 424 | add_library(api_C ...) |
| 425 | add_library(api_CXX ...) |
| 426 | add_library(api INTERFACE) |
| 427 | target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c> |
| 428 | $<$<LINK_LANGUAGE:CXX>:-opt_cxx>) |
| 429 | target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C> |
| 430 | $<$<LINK_LANGUAGE:CXX>:api_CXX>) |
| 431 | |
| 432 | add_executable(myapp1 main.c) |
| 433 | target_link_options(myapp1 PRIVATE api) |
| 434 | |
| 435 | add_executable(myapp2 main.cpp) |
| 436 | target_link_options(myapp2 PRIVATE api) |
| 437 | |
| 438 | This specifies to use the ``api`` target for linking targets ``myapp1`` and |
| 439 | ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and |
| 440 | option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2`` |
| 441 | will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be |
| 442 | the link language. |
| 443 | |
| 444 | .. _`Constraints LINK_LANGUAGE Generator Expression`: |
| 445 | |
| 446 | .. note:: |
| 447 | |
| 448 | To determine the link language of a target, it is required to collect, |
| 449 | transitively, all the targets which will be linked to it. So, for link |
| 450 | libraries properties, a double evaluation will be done. During the first |
| 451 | evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``. |
| 452 | The link language computed after this first pass will be used to do the |
| 453 | second pass. To avoid inconsistency, it is required that the second pass |
| 454 | do not change the link language. Moreover, to avoid unexpected |
| 455 | side-effects, it is required to specify complete entities as part of the |
| 456 | ``$<LINK_LANGUAGE:..>`` expression. For example: |
| 457 | |
| 458 | .. code-block:: cmake |
| 459 | |
| 460 | add_library(lib STATIC file.cxx) |
| 461 | add_library(libother STATIC file.c) |
| 462 | |
| 463 | # bad usage |
| 464 | add_executable(myapp1 main.c) |
| 465 | target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>) |
| 466 | |
| 467 | # correct usage |
| 468 | add_executable(myapp2 main.c) |
| 469 | target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>) |
| 470 | |
| 471 | In this example, for ``myapp1``, the first pass will, unexpectedly, |
| 472 | determine that the link language is ``CXX`` because the evaluation of the |
| 473 | generator expression will be an empty string so ``myapp1`` will depends on |
| 474 | target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first |
| 475 | evaluation will give ``C`` as link language, so the second pass will |
| 476 | correctly add target ``libother`` as link dependency. |
| 477 | |
| 478 | .. genex:: $<DEVICE_LINK:list> |
| 479 | |
| 480 | .. versionadded:: 3.18 |
| 481 | |
| 482 | Returns the list if it is the device link step, an empty list otherwise. |
| 483 | The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` |
| 484 | and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and |
| 485 | policy :policy:`CMP0105`. This expression can only be used to specify link |
| 486 | options. |
| 487 | |
| 488 | .. genex:: $<HOST_LINK:list> |
| 489 | |
| 490 | .. versionadded:: 3.18 |
| 491 | |
| 492 | Returns the list if it is the normal link step, an empty list otherwise. |
| 493 | This expression is mainly useful when a device link step is also involved |
| 494 | (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only |
| 495 | be used to specify link options. |
| 496 | |
| 497 | String-Valued Generator Expressions |
| 498 | =================================== |
| 499 | |
| 500 | These expressions expand to some string. |
| 501 | For example, |
| 502 | |
| 503 | .. code-block:: cmake |
| 504 | |
| 505 | include_directories(/usr/include/$<CXX_COMPILER_ID>/) |
| 506 | |
| 507 | expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on |
| 508 | the compiler identifier. |
| 509 | |
| 510 | String-valued expressions may also be combined with other expressions. |
| 511 | Here an example for a string-valued expression within a boolean expressions |
| 512 | within a conditional expression: |
| 513 | |
| 514 | .. code-block:: cmake |
| 515 | |
| 516 | $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> |
| 517 | |
| 518 | expands to ``OLD_COMPILER`` if the |
| 519 | :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less |
| 520 | than 4.2.0. |
| 521 | |
| 522 | And here two nested string-valued expressions: |
| 523 | |
| 524 | .. code-block:: cmake |
| 525 | |
| 526 | -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> |
| 527 | |
| 528 | generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target |
| 529 | property with each entry preceded by ``-I``. |
| 530 | |
| 531 | Expanding on the previous example, if one first wants to check if the |
| 532 | ``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to |
| 533 | introduce a helper variable to keep the code readable: |
| 534 | |
| 535 | .. code-block:: cmake |
| 536 | |
| 537 | set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable |
| 538 | $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> |
| 539 | |
| 540 | The following string-valued generator expressions are available: |
| 541 | |
| 542 | Escaped Characters |
| 543 | ------------------ |
| 544 | |
| 545 | String literals to escape the special meaning a character would otherwise have: |
| 546 | |
| 547 | .. genex:: $<ANGLE-R> |
| 548 | |
| 549 | A literal ``>``. Used for example to compare strings that contain a ``>``. |
| 550 | |
| 551 | .. genex:: $<COMMA> |
| 552 | |
| 553 | A literal ``,``. Used for example to compare strings which contain a ``,``. |
| 554 | |
| 555 | .. genex:: $<SEMICOLON> |
| 556 | |
| 557 | A literal ``;``. Used to prevent list expansion on an argument with ``;``. |
| 558 | |
| 559 | .. _`Conditional Generator Expressions`: |
| 560 | |
| 561 | Conditional Expressions |
| 562 | ----------------------- |
| 563 | |
| 564 | Conditional generator expressions depend on a boolean condition |
| 565 | that must be ``0`` or ``1``. |
| 566 | |
| 567 | .. genex:: $<condition:true_string> |
| 568 | |
| 569 | Evaluates to ``true_string`` if ``condition`` is ``1``. |
| 570 | Otherwise evaluates to the empty string. |
| 571 | |
| 572 | .. genex:: $<IF:condition,true_string,false_string> |
| 573 | |
| 574 | .. versionadded:: 3.8 |
| 575 | |
| 576 | Evaluates to ``true_string`` if ``condition`` is ``1``. |
| 577 | Otherwise evaluates to ``false_string``. |
| 578 | |
| 579 | Typically, the ``condition`` is a :ref:`boolean generator expression |
| 580 | <Boolean Generator Expressions>`. For instance, |
| 581 | |
| 582 | .. code-block:: cmake |
| 583 | |
| 584 | $<$<CONFIG:Debug>:DEBUG_MODE> |
| 585 | |
| 586 | expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and |
| 587 | otherwise expands to the empty string. |
| 588 | |
| 589 | .. _`String Transforming Generator Expressions`: |
| 590 | |
| 591 | String Transformations |
| 592 | ---------------------- |
| 593 | |
| 594 | .. genex:: $<JOIN:list,string> |
| 595 | |
| 596 | Joins the list with the content of ``string``. |
| 597 | |
| 598 | .. genex:: $<REMOVE_DUPLICATES:list> |
| 599 | |
| 600 | .. versionadded:: 3.15 |
| 601 | |
| 602 | Removes duplicated items in the given ``list``. |
| 603 | |
| 604 | .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> |
| 605 | |
| 606 | .. versionadded:: 3.15 |
| 607 | |
| 608 | Includes or removes items from ``list`` that match the regular expression ``regex``. |
| 609 | |
| 610 | .. genex:: $<LOWER_CASE:string> |
| 611 | |
| 612 | Content of ``string`` converted to lower case. |
| 613 | |
| 614 | .. genex:: $<UPPER_CASE:string> |
| 615 | |
| 616 | Content of ``string`` converted to upper case. |
| 617 | |
| 618 | .. genex:: $<GENEX_EVAL:expr> |
| 619 | |
| 620 | .. versionadded:: 3.12 |
| 621 | |
| 622 | Content of ``expr`` evaluated as a generator expression in the current |
| 623 | context. This enables consumption of generator expressions whose |
| 624 | evaluation results itself in generator expressions. |
| 625 | |
| 626 | .. genex:: $<TARGET_GENEX_EVAL:tgt,expr> |
| 627 | |
| 628 | .. versionadded:: 3.12 |
| 629 | |
| 630 | Content of ``expr`` evaluated as a generator expression in the context of |
| 631 | ``tgt`` target. This enables consumption of custom target properties that |
| 632 | themselves contain generator expressions. |
| 633 | |
| 634 | Having the capability to evaluate generator expressions is very useful when |
| 635 | you want to manage custom properties supporting generator expressions. |
| 636 | For example: |
| 637 | |
| 638 | .. code-block:: cmake |
| 639 | |
| 640 | add_library(foo ...) |
| 641 | |
| 642 | set_property(TARGET foo PROPERTY |
| 643 | CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> |
| 644 | ) |
| 645 | |
| 646 | add_custom_target(printFooKeys |
| 647 | COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> |
| 648 | ) |
| 649 | |
| 650 | This naive implementation of the ``printFooKeys`` custom command is wrong |
| 651 | because ``CUSTOM_KEYS`` target property is not evaluated and the content |
| 652 | is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). |
| 653 | |
| 654 | To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is |
| 655 | ``Debug``), it is required to evaluate the output of |
| 656 | ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: |
| 657 | |
| 658 | .. code-block:: cmake |
| 659 | |
| 660 | add_custom_target(printFooKeys |
| 661 | COMMAND ${CMAKE_COMMAND} -E |
| 662 | echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> |
| 663 | ) |
| 664 | |
| 665 | Variable Queries |
| 666 | ---------------- |
| 667 | |
| 668 | .. genex:: $<CONFIG> |
| 669 | |
| 670 | Configuration name. |
| 671 | |
| 672 | .. genex:: $<CONFIGURATION> |
| 673 | |
| 674 | Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. |
| 675 | |
| 676 | .. genex:: $<PLATFORM_ID> |
| 677 | |
| 678 | The current system's CMake platform id. |
| 679 | See also the :variable:`CMAKE_SYSTEM_NAME` variable. |
| 680 | |
| 681 | .. genex:: $<C_COMPILER_ID> |
| 682 | |
| 683 | The CMake's compiler id of the C compiler used. |
| 684 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 685 | |
| 686 | .. genex:: $<CXX_COMPILER_ID> |
| 687 | |
| 688 | The CMake's compiler id of the CXX compiler used. |
| 689 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 690 | |
| 691 | .. genex:: $<CUDA_COMPILER_ID> |
| 692 | |
| 693 | The CMake's compiler id of the CUDA compiler used. |
| 694 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 695 | |
| 696 | .. genex:: $<OBJC_COMPILER_ID> |
| 697 | |
| 698 | .. versionadded:: 3.16 |
| 699 | |
| 700 | The CMake's compiler id of the OBJC compiler used. |
| 701 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 702 | |
| 703 | .. genex:: $<OBJCXX_COMPILER_ID> |
| 704 | |
| 705 | .. versionadded:: 3.16 |
| 706 | |
| 707 | The CMake's compiler id of the OBJCXX compiler used. |
| 708 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 709 | |
| 710 | .. genex:: $<Fortran_COMPILER_ID> |
| 711 | |
| 712 | The CMake's compiler id of the Fortran compiler used. |
| 713 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 714 | |
| 715 | .. genex:: $<HIP_COMPILER_ID> |
| 716 | |
| 717 | The CMake's compiler id of the HIP compiler used. |
| 718 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 719 | |
| 720 | .. genex:: $<ISPC_COMPILER_ID> |
| 721 | |
| 722 | .. versionadded:: 3.19 |
| 723 | |
| 724 | The CMake's compiler id of the ISPC compiler used. |
| 725 | See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. |
| 726 | |
| 727 | .. genex:: $<C_COMPILER_VERSION> |
| 728 | |
| 729 | The version of the C compiler used. |
| 730 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 731 | |
| 732 | .. genex:: $<CXX_COMPILER_VERSION> |
| 733 | |
| 734 | The version of the CXX compiler used. |
| 735 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 736 | |
| 737 | .. genex:: $<CUDA_COMPILER_VERSION> |
| 738 | |
| 739 | The version of the CUDA compiler used. |
| 740 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 741 | |
| 742 | .. genex:: $<OBJC_COMPILER_VERSION> |
| 743 | |
| 744 | .. versionadded:: 3.16 |
| 745 | |
| 746 | The version of the OBJC compiler used. |
| 747 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 748 | |
| 749 | .. genex:: $<OBJCXX_COMPILER_VERSION> |
| 750 | |
| 751 | .. versionadded:: 3.16 |
| 752 | |
| 753 | The version of the OBJCXX compiler used. |
| 754 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 755 | |
| 756 | .. genex:: $<Fortran_COMPILER_VERSION> |
| 757 | |
| 758 | The version of the Fortran compiler used. |
| 759 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 760 | |
| 761 | .. genex:: $<HIP_COMPILER_VERSION> |
| 762 | |
| 763 | The version of the HIP compiler used. |
| 764 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 765 | |
| 766 | .. genex:: $<ISPC_COMPILER_VERSION> |
| 767 | |
| 768 | .. versionadded:: 3.19 |
| 769 | |
| 770 | The version of the ISPC compiler used. |
| 771 | See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. |
| 772 | |
| 773 | .. genex:: $<COMPILE_LANGUAGE> |
| 774 | |
| 775 | .. versionadded:: 3.3 |
| 776 | |
| 777 | The compile language of source files when evaluating compile options. |
| 778 | See :ref:`the related boolean expression |
| 779 | <Boolean COMPILE_LANGUAGE Generator Expression>` |
| 780 | ``$<COMPILE_LANGUAGE:language>`` |
| 781 | for notes about the portability of this generator expression. |
| 782 | |
| 783 | .. genex:: $<LINK_LANGUAGE> |
| 784 | |
| 785 | .. versionadded:: 3.18 |
| 786 | |
| 787 | The link language of target when evaluating link options. |
| 788 | See :ref:`the related boolean expression |
| 789 | <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` |
| 790 | for notes about the portability of this generator expression. |
| 791 | |
| 792 | .. note:: |
| 793 | |
| 794 | This generator expression is not supported by the link libraries |
| 795 | properties to avoid side-effects due to the double evaluation of |
| 796 | these properties. |
| 797 | |
| 798 | .. _`Target-Dependent Queries`: |
| 799 | |
| 800 | Target-Dependent Queries |
| 801 | ------------------------ |
| 802 | |
| 803 | These queries refer to a target ``tgt``. This can be any runtime artifact, |
| 804 | namely: |
| 805 | |
| 806 | * an executable target created by :command:`add_executable` |
| 807 | * a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library) |
| 808 | created by :command:`add_library` |
| 809 | * a static library target created by :command:`add_library` |
| 810 | |
| 811 | In the following, "the ``tgt`` filename" means the name of the ``tgt`` |
| 812 | binary file. This has to be distinguished from "the target name", |
| 813 | which is just the string ``tgt``. |
| 814 | |
| 815 | .. genex:: $<TARGET_NAME_IF_EXISTS:tgt> |
| 816 | |
| 817 | .. versionadded:: 3.12 |
| 818 | |
| 819 | The target name ``tgt`` if the target exists, an empty string otherwise. |
| 820 | |
| 821 | Note that ``tgt`` is not added as a dependency of the target this |
| 822 | expression is evaluated on. |
| 823 | |
| 824 | .. genex:: $<TARGET_FILE:tgt> |
| 825 | |
| 826 | Full path to the ``tgt`` binary file. |
| 827 | |
| 828 | .. genex:: $<TARGET_FILE_BASE_NAME:tgt> |
| 829 | |
| 830 | .. versionadded:: 3.15 |
| 831 | |
| 832 | Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and |
| 833 | suffix. |
| 834 | For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. |
| 835 | |
| 836 | See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, |
| 837 | :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` |
| 838 | target properties and their configuration specific variants |
| 839 | :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, |
| 840 | :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and |
| 841 | :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. |
| 842 | |
| 843 | The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target |
| 844 | properties can also be considered. |
| 845 | |
| 846 | Note that ``tgt`` is not added as a dependency of the target this |
| 847 | expression is evaluated on. |
| 848 | |
| 849 | .. genex:: $<TARGET_FILE_PREFIX:tgt> |
| 850 | |
| 851 | .. versionadded:: 3.15 |
| 852 | |
| 853 | Prefix of the ``tgt`` filename (such as ``lib``). |
| 854 | |
| 855 | See also the :prop_tgt:`PREFIX` target property. |
| 856 | |
| 857 | Note that ``tgt`` is not added as a dependency of the target this |
| 858 | expression is evaluated on. |
| 859 | |
| 860 | .. genex:: $<TARGET_FILE_SUFFIX:tgt> |
| 861 | |
| 862 | .. versionadded:: 3.15 |
| 863 | |
| 864 | Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). |
| 865 | |
| 866 | See also the :prop_tgt:`SUFFIX` target property. |
| 867 | |
| 868 | Note that ``tgt`` is not added as a dependency of the target this |
| 869 | expression is evaluated on. |
| 870 | |
| 871 | .. genex:: $<TARGET_FILE_NAME:tgt> |
| 872 | |
| 873 | The ``tgt`` filename. |
| 874 | |
| 875 | Note that ``tgt`` is not added as a dependency of the target this |
| 876 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 877 | |
| 878 | .. genex:: $<TARGET_FILE_DIR:tgt> |
| 879 | |
| 880 | Directory of the ``tgt`` binary file. |
| 881 | |
| 882 | Note that ``tgt`` is not added as a dependency of the target this |
| 883 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 884 | |
| 885 | .. genex:: $<TARGET_LINKER_FILE:tgt> |
| 886 | |
| 887 | File used when linking to the ``tgt`` target. This will usually |
| 888 | be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), |
| 889 | but for a shared library on DLL platforms, it would be the ``.lib`` |
| 890 | import library associated with the DLL. |
| 891 | |
| 892 | .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> |
| 893 | |
| 894 | .. versionadded:: 3.15 |
| 895 | |
| 896 | Base name of file used to link the target ``tgt``, i.e. |
| 897 | ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, |
| 898 | if target file name is ``libbase.a``, the base name is ``base``. |
| 899 | |
| 900 | See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, |
| 901 | and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration |
| 902 | specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, |
| 903 | :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and |
| 904 | :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. |
| 905 | |
| 906 | The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target |
| 907 | properties can also be considered. |
| 908 | |
| 909 | Note that ``tgt`` is not added as a dependency of the target this |
| 910 | expression is evaluated on. |
| 911 | |
| 912 | .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt> |
| 913 | |
| 914 | .. versionadded:: 3.15 |
| 915 | |
| 916 | Prefix of file used to link target ``tgt``. |
| 917 | |
| 918 | See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target |
| 919 | properties. |
| 920 | |
| 921 | Note that ``tgt`` is not added as a dependency of the target this |
| 922 | expression is evaluated on. |
| 923 | |
| 924 | .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt> |
| 925 | |
| 926 | .. versionadded:: 3.15 |
| 927 | |
| 928 | Suffix of file used to link where ``tgt`` is the name of a target. |
| 929 | |
| 930 | The suffix corresponds to the file extension (such as ".so" or ".lib"). |
| 931 | |
| 932 | See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target |
| 933 | properties. |
| 934 | |
| 935 | Note that ``tgt`` is not added as a dependency of the target this |
| 936 | expression is evaluated on. |
| 937 | |
| 938 | .. genex:: $<TARGET_LINKER_FILE_NAME:tgt> |
| 939 | |
| 940 | Name of file used to link target ``tgt``. |
| 941 | |
| 942 | Note that ``tgt`` is not added as a dependency of the target this |
| 943 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 944 | |
| 945 | .. genex:: $<TARGET_LINKER_FILE_DIR:tgt> |
| 946 | |
| 947 | Directory of file used to link target ``tgt``. |
| 948 | |
| 949 | Note that ``tgt`` is not added as a dependency of the target this |
| 950 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 951 | |
| 952 | .. genex:: $<TARGET_SONAME_FILE:tgt> |
| 953 | |
| 954 | File with soname (``.so.3``) where ``tgt`` is the name of a target. |
| 955 | .. genex:: $<TARGET_SONAME_FILE_NAME:tgt> |
| 956 | |
| 957 | Name of file with soname (``.so.3``). |
| 958 | |
| 959 | Note that ``tgt`` is not added as a dependency of the target this |
| 960 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 961 | |
| 962 | .. genex:: $<TARGET_SONAME_FILE_DIR:tgt> |
| 963 | |
| 964 | Directory of with soname (``.so.3``). |
| 965 | |
| 966 | Note that ``tgt`` is not added as a dependency of the target this |
| 967 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 968 | |
| 969 | .. genex:: $<TARGET_PDB_FILE:tgt> |
| 970 | |
| 971 | .. versionadded:: 3.1 |
| 972 | |
| 973 | Full path to the linker generated program database file (.pdb) |
| 974 | where ``tgt`` is the name of a target. |
| 975 | |
| 976 | See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` |
| 977 | target properties and their configuration specific variants |
| 978 | :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. |
| 979 | |
| 980 | .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt> |
| 981 | |
| 982 | .. versionadded:: 3.15 |
| 983 | |
| 984 | Base name of the linker generated program database file (.pdb) |
| 985 | where ``tgt`` is the name of a target. |
| 986 | |
| 987 | The base name corresponds to the target PDB file name (see |
| 988 | ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, |
| 989 | if target file name is ``base.pdb``, the base name is ``base``. |
| 990 | |
| 991 | See also the :prop_tgt:`PDB_NAME` target property and its configuration |
| 992 | specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. |
| 993 | |
| 994 | The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target |
| 995 | properties can also be considered. |
| 996 | |
| 997 | Note that ``tgt`` is not added as a dependency of the target this |
| 998 | expression is evaluated on. |
| 999 | |
| 1000 | .. genex:: $<TARGET_PDB_FILE_NAME:tgt> |
| 1001 | |
| 1002 | .. versionadded:: 3.1 |
| 1003 | |
| 1004 | Name of the linker generated program database file (.pdb). |
| 1005 | |
| 1006 | Note that ``tgt`` is not added as a dependency of the target this |
| 1007 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 1008 | |
| 1009 | .. genex:: $<TARGET_PDB_FILE_DIR:tgt> |
| 1010 | |
| 1011 | .. versionadded:: 3.1 |
| 1012 | |
| 1013 | Directory of the linker generated program database file (.pdb). |
| 1014 | |
| 1015 | Note that ``tgt`` is not added as a dependency of the target this |
| 1016 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 1017 | |
| 1018 | .. genex:: $<TARGET_BUNDLE_DIR:tgt> |
| 1019 | |
| 1020 | .. versionadded:: 3.9 |
| 1021 | |
| 1022 | Full path to the bundle directory (``my.app``, ``my.framework``, or |
| 1023 | ``my.bundle``) where ``tgt`` is the name of a target. |
| 1024 | |
| 1025 | Note that ``tgt`` is not added as a dependency of the target this |
| 1026 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 1027 | |
| 1028 | .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> |
| 1029 | |
| 1030 | .. versionadded:: 3.9 |
| 1031 | |
| 1032 | Full path to the bundle content directory where ``tgt`` is the name of a |
| 1033 | target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, |
| 1034 | or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to |
| 1035 | ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle |
| 1036 | structure. |
| 1037 | |
| 1038 | Note that ``tgt`` is not added as a dependency of the target this |
| 1039 | expression is evaluated on (see policy :policy:`CMP0112`). |
| 1040 | |
| 1041 | .. genex:: $<TARGET_PROPERTY:tgt,prop> |
| 1042 | |
| 1043 | Value of the property ``prop`` on the target ``tgt``. |
| 1044 | |
| 1045 | Note that ``tgt`` is not added as a dependency of the target this |
| 1046 | expression is evaluated on. |
| 1047 | |
| 1048 | .. genex:: $<TARGET_PROPERTY:prop> |
| 1049 | |
| 1050 | Value of the property ``prop`` on the target for which the expression |
| 1051 | is being evaluated. Note that for generator expressions in |
| 1052 | :ref:`Target Usage Requirements` this is the consuming target rather |
| 1053 | than the target specifying the requirement. |
| 1054 | |
| 1055 | .. genex:: $<TARGET_RUNTIME_DLLS:tgt> |
| 1056 | |
| 1057 | .. versionadded:: 3.21 |
| 1058 | |
| 1059 | List of DLLs that the target depends on at runtime. This is determined by |
| 1060 | the locations of all the ``SHARED`` and ``MODULE`` targets in the target's |
| 1061 | transitive dependencies. Using this generator expression on targets other |
| 1062 | than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. |
| 1063 | On non-DLL platforms, it evaluates to an empty string. |
| 1064 | |
| 1065 | This generator expression can be used to copy all of the DLLs that a target |
| 1066 | depends on into its output directory in a ``POST_BUILD`` custom command. For |
| 1067 | example: |
| 1068 | |
| 1069 | .. code-block:: cmake |
| 1070 | |
| 1071 | find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) |
| 1072 | |
| 1073 | add_executable(exe main.c) |
| 1074 | target_link_libraries(exe PRIVATE foo::foo foo::bar) |
| 1075 | add_custom_command(TARGET exe POST_BUILD |
| 1076 | COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> |
| 1077 | COMMAND_EXPAND_LISTS |
| 1078 | ) |
| 1079 | |
| 1080 | .. note:: |
| 1081 | |
| 1082 | :ref:`Imported Targets` are supported only if they know the location |
| 1083 | of their ``.dll`` files. An imported ``SHARED`` or ``MODULE`` library |
| 1084 | must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See |
| 1085 | the :ref:`add_library imported libraries <add_library imported libraries>` |
| 1086 | section for details. Many :ref:`Find Modules` produce imported targets |
| 1087 | with the ``UNKNOWN`` type and therefore will be ignored. |
| 1088 | |
| 1089 | .. genex:: $<INSTALL_PREFIX> |
| 1090 | |
| 1091 | Content of the install prefix when the target is exported via |
| 1092 | :command:`install(EXPORT)`, or when evaluated in the |
| 1093 | :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of |
| 1094 | :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. |
| 1095 | |
| 1096 | Output-Related Expressions |
| 1097 | -------------------------- |
| 1098 | |
| 1099 | .. genex:: $<TARGET_NAME:...> |
| 1100 | |
| 1101 | Marks ``...`` as being the name of a target. This is required if exporting |
| 1102 | targets to multiple dependent export sets. The ``...`` must be a literal |
| 1103 | name of a target- it may not contain generator expressions. |
| 1104 | |
| 1105 | .. genex:: $<LINK_ONLY:...> |
| 1106 | |
| 1107 | .. versionadded:: 3.1 |
| 1108 | |
| 1109 | Content of ``...`` except when evaluated in a link interface while |
| 1110 | propagating :ref:`Target Usage Requirements`, in which case it is the |
| 1111 | empty string. |
| 1112 | Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target |
| 1113 | property, perhaps via the :command:`target_link_libraries` command, |
| 1114 | to specify private link dependencies without other usage requirements. |
| 1115 | |
| 1116 | .. genex:: $<INSTALL_INTERFACE:...> |
| 1117 | |
| 1118 | Content of ``...`` when the property is exported using :command:`install(EXPORT)`, |
| 1119 | and empty otherwise. |
| 1120 | |
| 1121 | .. genex:: $<BUILD_INTERFACE:...> |
| 1122 | |
| 1123 | Content of ``...`` when the property is exported using :command:`export`, or |
| 1124 | when the target is used by another target in the same buildsystem. Expands to |
| 1125 | the empty string otherwise. |
| 1126 | |
| 1127 | .. genex:: $<MAKE_C_IDENTIFIER:...> |
| 1128 | |
| 1129 | Content of ``...`` converted to a C identifier. The conversion follows the |
| 1130 | same behavior as :command:`string(MAKE_C_IDENTIFIER)`. |
| 1131 | |
| 1132 | .. genex:: $<TARGET_OBJECTS:objLib> |
| 1133 | |
| 1134 | .. versionadded:: 3.1 |
| 1135 | |
| 1136 | List of objects resulting from build of ``objLib``. |
| 1137 | |
| 1138 | .. genex:: $<SHELL_PATH:...> |
| 1139 | |
| 1140 | .. versionadded:: 3.4 |
| 1141 | |
| 1142 | Content of ``...`` converted to shell path style. For example, slashes are |
| 1143 | converted to backslashes in Windows shells and drive letters are converted |
| 1144 | to posix paths in MSYS shells. The ``...`` must be an absolute path. |
| 1145 | |
| 1146 | .. versionadded:: 3.14 |
| 1147 | The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` |
| 1148 | of paths, in which case each path is converted individually and a result |
| 1149 | list is generated using the shell path separator (``:`` on POSIX and |
| 1150 | ``;`` on Windows). Be sure to enclose the argument containing this genex |
| 1151 | in double quotes in CMake source code so that ``;`` does not split arguments. |
| 1152 | |
| 1153 | .. genex:: $<OUTPUT_CONFIG:...> |
| 1154 | |
| 1155 | .. versionadded:: 3.20 |
| 1156 | |
| 1157 | Only valid in :command:`add_custom_command` and :command:`add_custom_target` |
| 1158 | as the outer-most generator expression in an argument. |
| 1159 | With the :generator:`Ninja Multi-Config` generator, generator expressions |
| 1160 | in ``...`` are evaluated using the custom command's "output config". |
| 1161 | With other generators, the content of ``...`` is evaluated normally. |
| 1162 | |
| 1163 | .. genex:: $<COMMAND_CONFIG:...> |
| 1164 | |
| 1165 | .. versionadded:: 3.20 |
| 1166 | |
| 1167 | Only valid in :command:`add_custom_command` and :command:`add_custom_target` |
| 1168 | as the outer-most generator expression in an argument. |
| 1169 | With the :generator:`Ninja Multi-Config` generator, generator expressions |
| 1170 | in ``...`` are evaluated using the custom command's "command config". |
| 1171 | With other generators, the content of ``...`` is evaluated normally. |
| 1172 | |
| 1173 | Debugging |
| 1174 | ========= |
| 1175 | |
| 1176 | Since generator expressions are evaluated during generation of the buildsystem, |
| 1177 | and not during processing of ``CMakeLists.txt`` files, it is not possible to |
| 1178 | inspect their result with the :command:`message()` command. |
| 1179 | |
| 1180 | One possible way to generate debug messages is to add a custom target, |
| 1181 | |
| 1182 | .. code-block:: cmake |
| 1183 | |
| 1184 | add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") |
| 1185 | |
| 1186 | The shell command ``make genexdebug`` (invoked after execution of ``cmake``) |
| 1187 | would then print the result of ``$<...>``. |
| 1188 | |
| 1189 | Another way is to write debug messages to a file: |
| 1190 | |
| 1191 | .. code-block:: cmake |
| 1192 | |
| 1193 | file(GENERATE OUTPUT filename CONTENT "$<...>") |