Help/manual/cmake-generator-expressions.7.rst

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