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.  They have the form
  15 ``$<...>``.  For example:
  16
  17 .. code-block:: cmake
  18
  19   target_include_directories(tgt PRIVATE /opt/include/$<CXX_COMPILER_ID>)
  20
  21 This would expand to ``/opt/include/GNU``, ``/opt/include/Clang``, etc.
  22 depending on the C++ compiler used.
  23
  24 Generator expressions are allowed in the context of many target properties,
  25 such as :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`,
  26 :prop_tgt:`COMPILE_DEFINITIONS` and others.  They may also be used when using
  27 commands to populate those properties, such as :command:`target_link_libraries`,
  28 :command:`target_include_directories`, :command:`target_compile_definitions`
  29 and others.  They enable conditional linking, conditional definitions used when
  30 compiling, conditional include directories, and more.  The conditions may be
  31 based on the build configuration, target properties, platform information,
  32 or any other queryable information.
  33
  34 Generator expressions can be nested:
  35
  36 .. code-block:: cmake
  37
  38   target_compile_definitions(tgt PRIVATE
  39     $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
  40   )
  41
  42 The above would expand to ``OLD_COMPILER`` if the
  43 :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less
  44 than 4.2.0.
  45
  46 Whitespace And Quoting
  47 ======================
  48
  49 Generator expressions are typically parsed after command arguments.
  50 If a generator expression contains spaces, new lines, semicolons or
  51 other characters that may be interpreted as command argument separators,
  52 the whole expression should be surrounded by quotes when passed to a
  53 command.  Failure to do so may result in the expression being split and
  54 it may no longer be recognized as a generator expression.
  55
  56 When using :command:`add_custom_command` or :command:`add_custom_target`,
  57 use the ``VERBATIM`` and ``COMMAND_EXPAND_LISTS`` options to obtain robust
  58 argument splitting and quoting.
  59
  60 .. code-block:: cmake
  61
  62   # WRONG: Embedded space will be treated as an argument separator.
  63   # This ends up not being seen as a generator expression at all.
  64   add_custom_target(run_some_tool
  65     COMMAND some_tool -I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>
  66     VERBATIM
  67   )
  68
  69 .. code-block:: cmake
  70
  71   # Better, but still not robust. Quotes prevent the space from splitting the
  72   # expression. However, the tool will receive the expanded value as a single
  73   # argument.
  74   add_custom_target(run_some_tool
  75     COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>"
  76     VERBATIM
  77   )
  78
  79 .. code-block:: cmake
  80
  81   # Nearly correct. Using a semicolon to separate arguments and adding the
  82   # COMMAND_EXPAND_LISTS option means that paths with spaces will be handled
  83   # correctly. Quoting the whole expression ensures it is seen as a generator
  84   # expression. But if the target property is empty, we will get a bare -I
  85   # with nothing after it.
  86   add_custom_target(run_some_tool
  87     COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,;-I>"
  88     COMMAND_EXPAND_LISTS
  89     VERBATIM
  90   )
  91
  92 Using variables to build up a more complex generator expression is also a
  93 good way to reduce errors and improve readability.  The above example can be
  94 improved further like so:
  95
  96 .. code-block:: cmake
  97
  98   # The $<BOOL:...> check prevents adding anything if the property is empty,
  99   # assuming the property value cannot be one of CMake's false constants.
 100   set(prop "$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>")
 101   add_custom_target(run_some_tool
 102     COMMAND some_tool "$<$<BOOL:${prop}>:-I$<JOIN:${prop},;-I>>"
 103     COMMAND_EXPAND_LISTS
 104     VERBATIM
 105   )
 106
 107 A common mistake is to try to split a generator expression across multiple
 108 lines with indenting:
 109
 110 .. code-block:: cmake
 111
 112   # WRONG: New lines and spaces all treated as argument separators, so the
 113   # generator expression is split and not recognized correctly.
 114   target_compile_definitions(tgt PRIVATE
 115     $<$<AND:
 116         $<CXX_COMPILER_ID:GNU>,
 117         $<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
 118       >:HAVE_5_OR_LATER>
 119   )
 120
 121 Again, use helper variables with well-chosen names to build up a readable
 122 expression instead:
 123
 124 .. code-block:: cmake
 125
 126   set(is_gnu "$<CXX_COMPILER_ID:GNU>")
 127   set(v5_or_later "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>")
 128   set(meet_requirements "$<AND:${is_gnu},${v5_or_later}>")
 129   target_compile_definitions(tgt PRIVATE
 130     "$<${meet_requirements}:HAVE_5_OR_LATER>"
 131   )
 132
 133 Debugging
 134 =========
 135
 136 Since generator expressions are evaluated during generation of the buildsystem,
 137 and not during processing of ``CMakeLists.txt`` files, it is not possible to
 138 inspect their result with the :command:`message()` command.  One possible way
 139 to generate debug messages is to add a custom target:
 140
 141 .. code-block:: cmake
 142
 143   add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")
 144
 145 After running ``cmake``, you can then build the ``genexdebug`` target to print
 146 the result of the ``$<...>`` expression (i.e. run the command
 147 ``cmake --build ... --target genexdebug``).
 148
 149 Another way is to write debug messages to a file with :command:`file(GENERATE)`:
 150
 151 .. code-block:: cmake
 152
 153   file(GENERATE OUTPUT filename CONTENT "$<...>")
 154
 155 Generator Expression Reference
 156 ==============================
 157
 158 .. note::
 159
 160   This reference deviates from most of the CMake documentation in that it
 161   omits angular brackets ``<...>`` around placeholders like ``condition``,
 162   ``string``, ``target``, etc.  This is to prevent an opportunity for those
 163   placeholders to be misinterpreted as generator expressions.
 164
 165 .. _`Conditional Generator Expressions`:
 166
 167 Conditional Expressions
 168 -----------------------
 169
 170 A fundamental category of generator expressions relates to conditional logic.
 171 Two forms of conditional generator expressions are supported:
 172
 173 .. genex:: $<condition:true_string>
 174
 175   Evaluates to ``true_string`` if ``condition`` is ``1``, or an empty string
 176   if ``condition`` evaluates to ``0``.  Any other value for ``condition``
 177   results in an error.
 178
 179 .. genex:: $<IF:condition,true_string,false_string>
 180
 181   .. versionadded:: 3.8
 182
 183   Evaluates to ``true_string`` if ``condition`` is ``1``, or ``false_string``
 184   if ``condition`` is ``0``.  Any other value for ``condition`` results in an
 185   error.
 186
 187 Typically, the ``condition`` is itself a generator expression.  For instance,
 188 the following expression expands to ``DEBUG_MODE`` when the ``Debug``
 189 configuration is used, and the empty string for all other configurations:
 190
 191 .. code-block:: cmake
 192
 193   $<$<CONFIG:Debug>:DEBUG_MODE>
 194
 195 Boolean-like ``condition`` values other than ``1`` or ``0`` can be handled
 196 by wrapping them with the ``$<BOOL:...>`` generator expression:
 197
 198 .. genex:: $<BOOL:string>
 199
 200   Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the
 201   following is true:
 202
 203   * ``string`` is empty,
 204   * ``string`` is a case-insensitive equal of
 205     ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or
 206   * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive).
 207
 208   Otherwise evaluates to ``1``.
 209
 210 The ``$<BOOL:...>`` generator expression is often used when a ``condition``
 211 is provided by a CMake variable:
 212
 213 .. code-block:: cmake
 214
 215   $<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE>
 216
 217
 218 .. _`Boolean Generator Expressions`:
 219
 220 Logical Operators
 221 -----------------
 222
 223 The common boolean logic operators are supported:
 224
 225 .. genex:: $<AND:conditions>
 226
 227   where ``conditions`` is a comma-separated list of boolean expressions,
 228   all of which must evaluate to either ``1`` or ``0``.  The whole expression
 229   evaluates to ``1`` if all conditions are ``1``.  If any condition is ``0``,
 230   the whole expression evaluates to ``0``.
 231
 232 .. genex:: $<OR:conditions>
 233
 234   where ``conditions`` is a comma-separated list of boolean expressions.
 235   all of which must evaluate to either ``1`` or ``0``.  The whole expression
 236   evaluates to ``1`` if at least one of the ``conditions`` is ``1``.  If all
 237   ``conditions`` evaluate to ``0``, the whole expression evaluates to ``0``.
 238
 239 .. genex:: $<NOT:condition>
 240
 241   ``condition`` must be ``0`` or ``1``.  The result of the expression is
 242   ``0`` if ``condition`` is ``1``, else ``1``.
 243
 244 .. _`Comparison Expressions`:
 245
 246 Primary Comparison Expressions
 247 ------------------------------
 248
 249 CMake supports a variety of generator expressions that compare things.
 250 This section covers the primary and most widely used comparison types.
 251 Other more specific comparison types are documented in their own separate
 252 sections further below.
 253
 254 String Comparisons
 255 ^^^^^^^^^^^^^^^^^^
 256
 257 .. genex:: $<STREQUAL:string1,string2>
 258
 259   ``1`` if ``string1`` and ``string2`` are equal, else ``0``.
 260   The comparison is case-sensitive.  For a case-insensitive comparison,
 261   combine with a :ref:`string transforming generator expression
 262   <String Transforming Generator Expressions>`.  For example, the following
 263   evaluates to ``1`` if ``${foo}`` is any of ``BAR``, ``Bar``, ``bar``, etc.
 264
 265   .. code-block:: cmake
 266
 267     $<STREQUAL:$<UPPER_CASE:${foo}>,BAR>
 268
 269 .. genex:: $<EQUAL:value1,value2>
 270
 271   ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``.
 272
 273 Version Comparisons
 274 ^^^^^^^^^^^^^^^^^^^
 275
 276 .. genex:: $<VERSION_LESS:v1,v2>
 277
 278   ``1`` if ``v1`` is a version less than ``v2``, else ``0``.
 279
 280 .. genex:: $<VERSION_GREATER:v1,v2>
 281
 282   ``1`` if ``v1`` is a version greater than ``v2``, else ``0``.
 283
 284 .. genex:: $<VERSION_EQUAL:v1,v2>
 285
 286   ``1`` if ``v1`` is the same version as ``v2``, else ``0``.
 287
 288 .. genex:: $<VERSION_LESS_EQUAL:v1,v2>
 289
 290   .. versionadded:: 3.7
 291
 292   ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``.
 293
 294 .. genex:: $<VERSION_GREATER_EQUAL:v1,v2>
 295
 296   .. versionadded:: 3.7
 297
 298   ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``.
 299
 300 .. _`String Transforming Generator Expressions`:
 301
 302 String Transformations
 303 ----------------------
 304
 305 .. genex:: $<LOWER_CASE:string>
 306
 307   Content of ``string`` converted to lower case.
 308
 309 .. genex:: $<UPPER_CASE:string>
 310
 311   Content of ``string`` converted to upper case.
 312
 313 .. genex:: $<MAKE_C_IDENTIFIER:...>
 314
 315   Content of ``...`` converted to a C identifier.  The conversion follows the
 316   same behavior as :command:`string(MAKE_C_IDENTIFIER)`.
 317
 318 List Expressions
 319 ----------------
 320
 321 .. genex:: $<IN_LIST:string,list>
 322
 323   .. versionadded:: 3.12
 324
 325   ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``.
 326   It uses case-sensitive comparisons.
 327
 328 .. genex:: $<JOIN:list,string>
 329
 330   Joins the list with the content of ``string`` inserted between each item.
 331
 332 .. genex:: $<REMOVE_DUPLICATES:list>
 333
 334   .. versionadded:: 3.15
 335
 336   Removes duplicated items in the given ``list``. The relative order of items
 337   is preserved, but if duplicates are encountered, only the first instance is
 338   preserved.
 339
 340 .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex>
 341
 342   .. versionadded:: 3.15
 343
 344   Includes or removes items from ``list`` that match the regular expression
 345   ``regex``.
 346
 347 Path Expressions
 348 ----------------
 349
 350 Most of the expressions in this section are closely associated with the
 351 :command:`cmake_path` command, providing the same capabilities, but in
 352 the form of a generator expression.
 353
 354 For all generator expressions in this section, paths are expected to be in
 355 cmake-style format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>`
 356 generator expression can be used to convert a native path to a cmake-style
 357 one.
 358
 359 .. _GenEx Path Comparisons:
 360
 361 Path Comparisons
 362 ^^^^^^^^^^^^^^^^
 363
 364 .. genex:: $<PATH_EQUAL:path1,path2>
 365
 366   .. versionadded:: 3.24
 367
 368   Compares the lexical representations of two paths. No normalization is
 369   performed on either path. Returns ``1`` if the paths are equal, ``0``
 370   otherwise.
 371
 372   See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details.
 373
 374 .. _GenEx Path Queries:
 375
 376 Path Queries
 377 ^^^^^^^^^^^^
 378
 379 These expressions provide the generation-time capabilities equivalent to the
 380 :ref:`Query <Path Query>` options of the :command:`cmake_path` command.
 381 All paths are expected to be in cmake-style format.
 382
 383 .. genex:: $<PATH:HAS_*,path>
 384
 385   .. versionadded:: 3.24
 386
 387   The following operations return ``1`` if the particular path component is
 388   present, ``0`` otherwise. See :ref:`Path Structure And Terminology` for the
 389   meaning of each path component.
 390
 391   ::
 392
 393     $<PATH:HAS_ROOT_NAME,path>
 394     $<PATH:HAS_ROOT_DIRECTORY,path>
 395     $<PATH:HAS_ROOT_PATH,path>
 396     $<PATH:HAS_FILENAME,path>
 397     $<PATH:HAS_EXTENSION,path>
 398     $<PATH:HAS_STEM,path>
 399     $<PATH:HAS_RELATIVE_PART,path>
 400     $<PATH:HAS_PARENT_PATH,path>
 401
 402   Note the following special cases:
 403
 404   * For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
 405     of ``root-name`` or ``root-directory`` is non-empty.
 406
 407   * For ``HAS_PARENT_PATH``, the root directory is also considered to have a
 408     parent, which will be itself.  The result is true except if the path
 409     consists of just a :ref:`filename <FILENAME_DEF>`.
 410
 411 .. genex:: $<PATH:IS_ABSOLUTE,path>
 412
 413   .. versionadded:: 3.24
 414
 415   Returns ``1`` if the path is :ref:`absolute <IS_ABSOLUTE>`, ``0`` otherwise.
 416
 417 .. genex:: $<PATH:IS_RELATIVE,path>
 418
 419   .. versionadded:: 3.24
 420
 421   This will return the opposite of ``IS_ABSOLUTE``.
 422
 423 .. genex:: $<PATH:IS_PREFIX[,NORMALIZE],path,input>
 424
 425   .. versionadded:: 3.24
 426
 427   Returns ``1`` if ``path`` is the prefix of ``input``, ``0`` otherwise.
 428
 429   When the ``NORMALIZE`` option is specified, ``path`` and ``input`` are
 430   :ref:`normalized <Normalization>` before the check.
 431
 432 .. _GenEx Path Decomposition:
 433
 434 Path Decomposition
 435 ^^^^^^^^^^^^^^^^^^
 436
 437 These expressions provide the generation-time capabilities equivalent to the
 438 :ref:`Decomposition <Path Decomposition>` options of the :command:`cmake_path`
 439 command.  All paths are expected to be in cmake-style format.
 440
 441 .. genex:: $<PATH:GET_*,...>
 442
 443   .. versionadded:: 3.24
 444
 445   The following operations retrieve a different component or group of
 446   components from a path. See :ref:`Path Structure And Terminology` for the
 447   meaning of each path component.
 448
 449   ::
 450
 451     $<PATH:GET_ROOT_NAME,path>
 452     $<PATH:GET_ROOT_DIRECTORY,path>
 453     $<PATH:GET_ROOT_PATH,path>
 454     $<PATH:GET_FILENAME,path>
 455     $<PATH:GET_EXTENSION[,LAST_ONLY],path>
 456     $<PATH:GET_STEM[,LAST_ONLY],path>
 457     $<PATH:GET_RELATIVE_PART,path>
 458     $<PATH:GET_PARENT_PATH,path>
 459
 460   If a requested component is not present in the path, an empty string is
 461   returned.
 462
 463 .. _GenEx Path Transformations:
 464
 465 Path Transformations
 466 ^^^^^^^^^^^^^^^^^^^^
 467
 468 These expressions provide the generation-time capabilities equivalent to the
 469 :ref:`Modification <Path Modification>` and :ref:`Generation <Path Generation>`
 470 options of the :command:`cmake_path` command.  All paths are expected to be
 471 in cmake-style format.
 472
 473 .. _GenEx PATH-CMAKE_PATH:
 474
 475 .. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path>
 476
 477   .. versionadded:: 3.24
 478
 479   Returns ``path``. If ``path`` is a native path, it is converted into a
 480   cmake-style path with forward-slashes (``/``). On Windows, the long filename
 481   marker is taken into account.
 482
 483   When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
 484   <Normalization>` after the conversion.
 485
 486 .. genex:: $<PATH:APPEND,path,input,...>
 487
 488   .. versionadded:: 3.24
 489
 490   Returns all the ``input`` arguments appended to ``path`` using ``/`` as the
 491   ``directory-separator``. Depending on the ``input``, the value of ``path``
 492   may be discarded.
 493
 494   See :ref:`cmake_path(APPEND) <APPEND>` for more details.
 495
 496 .. genex:: $<PATH:REMOVE_FILENAME,path>
 497
 498   .. versionadded:: 3.24
 499
 500   Returns ``path`` with filename component (as returned by
 501   ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing
 502   ``directory-separator`` is left alone, if present.
 503
 504   See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details.
 505
 506 .. genex:: $<PATH:REPLACE_FILENAME,path,input>
 507
 508   .. versionadded:: 3.24
 509
 510   Returns ``path`` with the filename component replaced by ``input``. If
 511   ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns
 512   ``0``), ``path`` is unchanged.
 513
 514   See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details.
 515
 516 .. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path>
 517
 518   .. versionadded:: 3.24
 519
 520   Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any.
 521
 522   See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details.
 523
 524 .. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path,input>
 525
 526   .. versionadded:: 3.24
 527
 528   Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by
 529   ``input``, if any.
 530
 531   See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details.
 532
 533 .. genex:: $<PATH:NORMAL_PATH,path>
 534
 535   .. versionadded:: 3.24
 536
 537   Returns ``path`` normalized according to the steps described in
 538   :ref:`Normalization`.
 539
 540 .. genex:: $<PATH:RELATIVE_PATH,path,base_directory>
 541
 542   .. versionadded:: 3.24
 543
 544   Returns ``path``, modified to make it relative to the ``base_directory``
 545   argument.
 546
 547   See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more
 548   details.
 549
 550 .. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory>
 551
 552   .. versionadded:: 3.24
 553
 554   Returns ``path`` as absolute. If ``path`` is a relative path
 555   (``$<PATH:IS_RELATIVE>`` returns ``1``), it is evaluated relative to the
 556   given base directory specified by ``base_directory`` argument.
 557
 558   When the ``NORMALIZE`` option is specified, the path is
 559   :ref:`normalized <Normalization>` after the path computation.
 560
 561   See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details.
 562
 563 Shell Paths
 564 ^^^^^^^^^^^
 565
 566 .. genex:: $<SHELL_PATH:...>
 567
 568   .. versionadded:: 3.4
 569
 570   Content of ``...`` converted to shell path style. For example, slashes are
 571   converted to backslashes in Windows shells and drive letters are converted
 572   to posix paths in MSYS shells. The ``...`` must be an absolute path.
 573
 574   .. versionadded:: 3.14
 575     The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>`
 576     of paths, in which case each path is converted individually and a result
 577     list is generated using the shell path separator (``:`` on POSIX and
 578     ``;`` on Windows).  Be sure to enclose the argument containing this genex
 579     in double quotes in CMake source code so that ``;`` does not split arguments.
 580
 581 Configuration Expressions
 582 -------------------------
 583
 584 .. genex:: $<CONFIG>
 585
 586   Configuration name. Use this instead of the deprecated :genex:`CONFIGURATION`
 587   generator expression.
 588
 589 .. genex:: $<CONFIG:cfgs>
 590
 591   ``1`` if config is any one of the entries in comma-separated list
 592   ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in
 593   :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this
 594   expression when it is evaluated on a property of an :prop_tgt:`IMPORTED`
 595   target.
 596
 597   .. versionchanged:: 3.19
 598     Multiple configurations can be specified for ``cfgs``.
 599     CMake 3.18 and earlier only accepted a single configuration.
 600
 601 .. genex:: $<OUTPUT_CONFIG:...>
 602
 603   .. versionadded:: 3.20
 604
 605   Only valid in :command:`add_custom_command` and :command:`add_custom_target`
 606   as the outer-most generator expression in an argument.
 607   With the :generator:`Ninja Multi-Config` generator, generator expressions
 608   in ``...`` are evaluated using the custom command's "output config".
 609   With other generators, the content of ``...`` is evaluated normally.
 610
 611 .. genex:: $<COMMAND_CONFIG:...>
 612
 613   .. versionadded:: 3.20
 614
 615   Only valid in :command:`add_custom_command` and :command:`add_custom_target`
 616   as the outer-most generator expression in an argument.
 617   With the :generator:`Ninja Multi-Config` generator, generator expressions
 618   in ``...`` are evaluated using the custom command's "command config".
 619   With other generators, the content of ``...`` is evaluated normally.
 620
 621 Toolchain And Language Expressions
 622 ----------------------------------
 623
 624 Platform
 625 ^^^^^^^^
 626
 627 .. genex:: $<PLATFORM_ID>
 628
 629   The current system's CMake platform id.
 630   See also the :variable:`CMAKE_SYSTEM_NAME` variable.
 631
 632 .. genex:: $<PLATFORM_ID:platform_ids>
 633
 634   ``1`` if CMake's platform id matches any one of the entries in
 635   comma-separated list ``platform_ids``, otherwise ``0``.
 636   See also the :variable:`CMAKE_SYSTEM_NAME` variable.
 637
 638 Compiler Version
 639 ^^^^^^^^^^^^^^^^
 640
 641 See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable, which is
 642 closely related to the expressions in this sub-section.
 643
 644 .. genex:: $<C_COMPILER_VERSION>
 645
 646   The version of the C compiler used.
 647
 648 .. genex:: $<C_COMPILER_VERSION:version>
 649
 650   ``1`` if the version of the C compiler matches ``version``, otherwise ``0``.
 651
 652 .. genex:: $<CXX_COMPILER_VERSION>
 653
 654   The version of the CXX compiler used.
 655
 656 .. genex:: $<CXX_COMPILER_VERSION:version>
 657
 658   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
 659
 660 .. genex:: $<CUDA_COMPILER_VERSION>
 661
 662   .. versionadded:: 3.15
 663
 664   The version of the CUDA compiler used.
 665
 666 .. genex:: $<CUDA_COMPILER_VERSION:version>
 667
 668   .. versionadded:: 3.15
 669
 670   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
 671
 672 .. genex:: $<OBJC_COMPILER_VERSION>
 673
 674   .. versionadded:: 3.16
 675
 676   The version of the OBJC compiler used.
 677
 678 .. genex:: $<OBJC_COMPILER_VERSION:version>
 679
 680   .. versionadded:: 3.16
 681
 682   ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``.
 683
 684 .. genex:: $<OBJCXX_COMPILER_VERSION>
 685
 686   .. versionadded:: 3.16
 687
 688   The version of the OBJCXX compiler used.
 689
 690 .. genex:: $<OBJCXX_COMPILER_VERSION:version>
 691
 692   .. versionadded:: 3.16
 693
 694   ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``.
 695
 696 .. genex:: $<Fortran_COMPILER_VERSION>
 697
 698   The version of the Fortran compiler used.
 699
 700 .. genex:: $<Fortran_COMPILER_VERSION:version>
 701
 702   ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``.
 703
 704 .. genex:: $<HIP_COMPILER_VERSION>
 705
 706   .. versionadded:: 3.21
 707
 708   The version of the HIP compiler used.
 709
 710 .. genex:: $<HIP_COMPILER_VERSION:version>
 711
 712   .. versionadded:: 3.21
 713
 714   ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``.
 715
 716 .. genex:: $<ISPC_COMPILER_VERSION>
 717
 718   .. versionadded:: 3.19
 719
 720   The version of the ISPC compiler used.
 721
 722 .. genex:: $<ISPC_COMPILER_VERSION:version>
 723
 724   .. versionadded:: 3.19
 725
 726   ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``.
 727
 728 Compiler Language And ID
 729 ^^^^^^^^^^^^^^^^^^^^^^^^
 730
 731 See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable, which is closely
 732 related to most of the expressions in this sub-section.
 733
 734 .. genex:: $<C_COMPILER_ID>
 735
 736   CMake's compiler id of the C compiler used.
 737
 738 .. genex:: $<C_COMPILER_ID:compiler_ids>
 739
 740   where ``compiler_ids`` is a comma-separated list.
 741   ``1`` if CMake's compiler id of the C compiler matches any one
 742   of the entries in ``compiler_ids``, otherwise ``0``.
 743
 744 .. genex:: $<CXX_COMPILER_ID>
 745
 746   CMake's compiler id of the CXX compiler used.
 747
 748 .. genex:: $<CXX_COMPILER_ID:compiler_ids>
 749
 750   where ``compiler_ids`` is a comma-separated list.
 751   ``1`` if CMake's compiler id of the CXX compiler matches any one
 752   of the entries in ``compiler_ids``, otherwise ``0``.
 753
 754 .. genex:: $<CUDA_COMPILER_ID>
 755
 756   .. versionadded:: 3.15
 757
 758   CMake's compiler id of the CUDA compiler used.
 759
 760 .. genex:: $<CUDA_COMPILER_ID:compiler_ids>
 761
 762   .. versionadded:: 3.15
 763
 764   where ``compiler_ids`` is a comma-separated list.
 765   ``1`` if CMake's compiler id of the CUDA compiler matches any one
 766   of the entries in ``compiler_ids``, otherwise ``0``.
 767
 768 .. genex:: $<OBJC_COMPILER_ID>
 769
 770   .. versionadded:: 3.16
 771
 772   CMake's compiler id of the OBJC compiler used.
 773
 774 .. genex:: $<OBJC_COMPILER_ID:compiler_ids>
 775
 776   .. versionadded:: 3.16
 777
 778   where ``compiler_ids`` is a comma-separated list.
 779   ``1`` if CMake's compiler id of the Objective-C compiler matches any one
 780   of the entries in ``compiler_ids``, otherwise ``0``.
 781
 782 .. genex:: $<OBJCXX_COMPILER_ID>
 783
 784   .. versionadded:: 3.16
 785
 786   CMake's compiler id of the OBJCXX compiler used.
 787
 788 .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids>
 789
 790   .. versionadded:: 3.16
 791
 792   where ``compiler_ids`` is a comma-separated list.
 793   ``1`` if CMake's compiler id of the Objective-C++ compiler matches any one
 794   of the entries in ``compiler_ids``, otherwise ``0``.
 795
 796 .. genex:: $<Fortran_COMPILER_ID>
 797
 798   CMake's compiler id of the Fortran compiler used.
 799
 800 .. genex:: $<Fortran_COMPILER_ID:compiler_ids>
 801
 802   where ``compiler_ids`` is a comma-separated list.
 803   ``1`` if CMake's compiler id of the Fortran compiler matches any one
 804   of the entries in ``compiler_ids``, otherwise ``0``.
 805
 806 .. genex:: $<HIP_COMPILER_ID>
 807
 808   .. versionadded:: 3.21
 809
 810   CMake's compiler id of the HIP compiler used.
 811
 812 .. genex:: $<HIP_COMPILER_ID:compiler_ids>
 813
 814   .. versionadded:: 3.21
 815
 816   where ``compiler_ids`` is a comma-separated list.
 817   ``1`` if CMake's compiler id of the HIP compiler matches any one
 818   of the entries in ``compiler_ids``, otherwise ``0``.
 819
 820 .. genex:: $<ISPC_COMPILER_ID>
 821
 822   .. versionadded:: 3.19
 823
 824   CMake's compiler id of the ISPC compiler used.
 825
 826 .. genex:: $<ISPC_COMPILER_ID:compiler_ids>
 827
 828   .. versionadded:: 3.19
 829
 830   where ``compiler_ids`` is a comma-separated list.
 831   ``1`` if CMake's compiler id of the ISPC compiler matches any one
 832   of the entries in ``compiler_ids``, otherwise ``0``.
 833
 834 .. genex:: $<COMPILE_LANGUAGE>
 835
 836   .. versionadded:: 3.3
 837
 838   The compile language of source files when evaluating compile options.
 839   See :ref:`the related boolean expression
 840   <Boolean COMPILE_LANGUAGE Generator Expression>`
 841   ``$<COMPILE_LANGUAGE:language>``
 842   for notes about the portability of this generator expression.
 843
 844 .. _`Boolean COMPILE_LANGUAGE Generator Expression`:
 845
 846 .. genex:: $<COMPILE_LANGUAGE:languages>
 847
 848   .. versionadded:: 3.3
 849
 850   .. versionchanged:: 3.15
 851     Multiple languages can be specified for ``languages``.
 852     CMake 3.14 and earlier only accepted a single language.
 853
 854   ``1`` when the language used for compilation unit matches any of the
 855   comma-separated entries in ``languages``, otherwise ``0``. This expression
 856   may be used to specify compile options, compile definitions, and include
 857   directories for source files of a particular language in a target. For
 858   example:
 859
 860   .. code-block:: cmake
 861
 862     add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
 863     target_compile_options(myapp
 864       PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
 865     )
 866     target_compile_definitions(myapp
 867       PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
 868               $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
 869     )
 870     target_include_directories(myapp
 871       PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
 872     )
 873
 874   This specifies the use of the ``-fno-exceptions`` compile option,
 875   ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include
 876   directory for C++ only (compiler id checks elided).  It also specifies
 877   a ``COMPILING_CUDA`` compile definition for CUDA.
 878
 879   Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there
 880   is no way to represent target-wide compile definitions or include directories
 881   separately for ``C`` and ``CXX`` languages.
 882   Also, with :ref:`Visual Studio Generators` there is no way to represent
 883   target-wide flags separately for ``C`` and ``CXX`` languages.  Under these
 884   generators, expressions for both C and C++ sources will be evaluated
 885   using ``CXX`` if there are any C++ sources and otherwise using ``C``.
 886   A workaround is to create separate libraries for each source file language
 887   instead:
 888
 889   .. code-block:: cmake
 890
 891     add_library(myapp_c foo.c)
 892     add_library(myapp_cxx bar.cpp)
 893     target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
 894     add_executable(myapp main.cpp)
 895     target_link_libraries(myapp myapp_c myapp_cxx)
 896
 897 .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids>
 898
 899   .. versionadded:: 3.15
 900
 901   ``1`` when the language used for compilation unit matches ``language`` and
 902   CMake's compiler id of the ``language`` compiler matches any one of the
 903   comma-separated entries in ``compiler_ids``, otherwise ``0``. This expression
 904   is a short form for the combination of ``$<COMPILE_LANGUAGE:language>`` and
 905   ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
 906   compile options, compile definitions, and include directories for source
 907   files of a particular language and compiler combination in a target.
 908   For example:
 909
 910   .. code-block:: cmake
 911
 912     add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
 913     target_compile_definitions(myapp
 914       PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
 915               $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
 916               $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
 917     )
 918
 919   This specifies the use of different compile definitions based on both
 920   the compiler id and compilation language. This example will have a
 921   ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX
 922   compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler.
 923   Likewise, when the C compiler is Clang, it will only see the
 924   ``COMPILING_C_WITH_CLANG`` definition.
 925
 926   Without the ``COMPILE_LANG_AND_ID`` generator expression, the same logic
 927   would be expressed as:
 928
 929   .. code-block:: cmake
 930
 931     target_compile_definitions(myapp
 932       PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
 933               $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
 934               $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
 935     )
 936
 937 Compile Features
 938 ^^^^^^^^^^^^^^^^
 939
 940 .. genex:: $<COMPILE_FEATURES:features>
 941
 942   .. versionadded:: 3.1
 943
 944   where ``features`` is a comma-separated list.
 945   Evaluates to ``1`` if all of the ``features`` are available for the 'head'
 946   target, and ``0`` otherwise. If this expression is used while evaluating
 947   the link implementation of a target and if any dependency transitively
 948   increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
 949   for the 'head' target, an error is reported.  See the
 950   :manual:`cmake-compile-features(7)` manual for information on
 951   compile features and a list of supported compilers.
 952
 953 Linker Language And ID
 954 ^^^^^^^^^^^^^^^^^^^^^^
 955
 956 .. genex:: $<LINK_LANGUAGE>
 957
 958   .. versionadded:: 3.18
 959
 960   The link language of the target when evaluating link options.
 961   See :ref:`the related boolean expression
 962   <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:languages>``
 963   for notes about the portability of this generator expression.
 964
 965   .. note::
 966
 967     This generator expression is not supported by the link libraries
 968     properties to avoid side-effects due to the double evaluation of
 969     these properties.
 970
 971
 972 .. _`Boolean LINK_LANGUAGE Generator Expression`:
 973
 974 .. genex:: $<LINK_LANGUAGE:languages>
 975
 976   .. versionadded:: 3.18
 977
 978   ``1`` when the language used for link step matches any of the comma-separated
 979   entries in ``languages``, otherwise ``0``.  This expression may be used to
 980   specify link libraries, link options, link directories and link dependencies
 981   of a particular language in a target. For example:
 982
 983   .. code-block:: cmake
 984
 985     add_library(api_C ...)
 986     add_library(api_CXX ...)
 987     add_library(api INTERFACE)
 988     target_link_options(api   INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
 989                                         $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
 990     target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
 991                                         $<$<LINK_LANGUAGE:CXX>:api_CXX>)
 992
 993     add_executable(myapp1 main.c)
 994     target_link_options(myapp1 PRIVATE api)
 995
 996     add_executable(myapp2 main.cpp)
 997     target_link_options(myapp2 PRIVATE api)
 998
 999   This specifies to use the ``api`` target for linking targets ``myapp1`` and
1000   ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and
1001   option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2``
1002   will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be
1003   the link language.
1004
1005   .. _`Constraints LINK_LANGUAGE Generator Expression`:
1006
1007   .. note::
1008
1009     To determine the link language of a target, it is required to collect,
1010     transitively, all the targets which will be linked to it. So, for link
1011     libraries properties, a double evaluation will be done. During the first
1012     evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``.
1013     The link language computed after this first pass will be used to do the
1014     second pass. To avoid inconsistency, it is required that the second pass
1015     do not change the link language. Moreover, to avoid unexpected
1016     side-effects, it is required to specify complete entities as part of the
1017     ``$<LINK_LANGUAGE:..>`` expression. For example:
1018
1019     .. code-block:: cmake
1020
1021       add_library(lib STATIC file.cxx)
1022       add_library(libother STATIC file.c)
1023
1024       # bad usage
1025       add_executable(myapp1 main.c)
1026       target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
1027
1028       # correct usage
1029       add_executable(myapp2 main.c)
1030       target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
1031
1032     In this example, for ``myapp1``, the first pass will, unexpectedly,
1033     determine that the link language is ``CXX`` because the evaluation of the
1034     generator expression will be an empty string so ``myapp1`` will depends on
1035     target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first
1036     evaluation will give ``C`` as link language, so the second pass will
1037     correctly add target ``libother`` as link dependency.
1038
1039 .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids>
1040
1041   .. versionadded:: 3.18
1042
1043   ``1`` when the language used for link step matches ``language`` and the
1044   CMake's compiler id of the language linker matches any one of the comma-separated
1045   entries in ``compiler_ids``, otherwise ``0``. This expression is a short form
1046   for the combination of ``$<LINK_LANGUAGE:language>`` and
1047   ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
1048   link libraries, link options, link directories and link dependencies of a
1049   particular language and linker combination in a target. For example:
1050
1051   .. code-block:: cmake
1052
1053     add_library(libC_Clang ...)
1054     add_library(libCXX_Clang ...)
1055     add_library(libC_Intel ...)
1056     add_library(libCXX_Intel ...)
1057
1058     add_executable(myapp main.c)
1059     if (CXX_CONFIG)
1060       target_sources(myapp PRIVATE file.cxx)
1061     endif()
1062     target_link_libraries(myapp
1063       PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
1064               $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
1065               $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
1066               $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
1067
1068   This specifies the use of different link libraries based on both the
1069   compiler id and link language. This example will have target ``libCXX_Clang``
1070   as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX``
1071   linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker.
1072   Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target
1073   ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when
1074   ``Intel`` is the ``C`` linker.
1075
1076   See :ref:`the note related to
1077   <Constraints LINK_LANGUAGE Generator Expression>`
1078   ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
1079   generator expression.
1080
1081 Link Features
1082 ^^^^^^^^^^^^^
1083
1084 .. genex:: $<LINK_LIBRARY:feature,library-list>
1085
1086   .. versionadded:: 3.24
1087
1088   Specify a set of libraries to link to a target, along with a ``feature``
1089   which provides details about *how* they should be linked.  For example:
1090
1091   .. code-block:: cmake
1092
1093     add_library(lib1 STATIC ...)
1094     add_library(lib2 ...)
1095     target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")
1096
1097   This specifies that ``lib2`` should link to ``lib1`` and use the
1098   ``WHOLE_ARCHIVE`` feature when doing so.
1099
1100   Feature names are case-sensitive and may only contain letters, numbers and
1101   underscores.  Feature names defined in all uppercase are reserved for CMake's
1102   own built-in features.  The pre-defined built-in library features are:
1103
1104   .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
1105
1106   Built-in and custom library features are defined in terms of the following
1107   variables:
1108
1109   * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
1110   * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
1111   * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
1112   * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`
1113
1114   The value used for each of these variables is the value as set at the end of
1115   the directory scope in which the target was created.  The usage is as follows:
1116
1117   1. If the language-specific
1118      :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable
1119      is true, the ``feature`` must be defined by the corresponding
1120      :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable.
1121   2. If no language-specific ``feature`` is supported, then the
1122      :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable must be
1123      true and the ``feature`` must be defined by the corresponding
1124      :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable.
1125
1126   The following limitations should be noted:
1127
1128   * The ``library-list`` can specify CMake targets or libraries.
1129     Any CMake target of type :ref:`OBJECT <Object Libraries>`
1130     or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
1131     of the expression and instead be linked in the standard way.
1132
1133   * The ``$<LINK_LIBRARY:...>`` generator expression can only be used to
1134     specify link libraries.  In practice, this means it can appear in the
1135     :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
1136     :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`  target properties, and be
1137     specified in :command:`target_link_libraries` and :command:`link_libraries`
1138     commands.
1139
1140   * If a ``$<LINK_LIBRARY:...>`` generator expression appears in the
1141     :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
1142     included in the imported target generated by a :command:`install(EXPORT)`
1143     command.  It is the responsibility of the environment consuming this
1144     import to define the link feature used by this expression.
1145
1146   * Each target or library involved in the link step must have at most only
1147     one kind of library feature.  The absence of a feature is also incompatible
1148     with all other features.  For example:
1149
1150     .. code-block:: cmake
1151
1152       add_library(lib1 ...)
1153       add_library(lib2 ...)
1154       add_library(lib3 ...)
1155
1156       # lib1 will be associated with feature1
1157       target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
1158
1159       # lib1 is being linked with no feature here. This conflicts with the
1160       # use of feature1 in the line above and would result in an error.
1161       target_link_libraries(lib3 PRIVATE lib1 lib2)
1162
1163     Where it isn't possible to use the same feature throughout a build for a
1164     given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
1165     :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be
1166     used to resolve such incompatibilities.
1167
1168   * The ``$<LINK_LIBRARY:...>`` generator expression does not guarantee
1169     that the list of specified targets and libraries will be kept grouped
1170     together.  To manage constructs like ``--start-group`` and ``--end-group``,
1171     as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP`
1172     generator expression instead.
1173
1174 .. genex:: $<LINK_GROUP:feature,library-list>
1175
1176   .. versionadded:: 3.24
1177
1178   Specify a group of libraries to link to a target, along with a ``feature``
1179   which defines how that group should be linked.  For example:
1180
1181   .. code-block:: cmake
1182
1183     add_library(lib1 STATIC ...)
1184     add_library(lib2 ...)
1185     target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
1186
1187   This specifies that ``lib2`` should link to ``lib1`` and ``external``, and
1188   that both of those two libraries should be included on the linker command
1189   line according to the definition of the ``RESCAN`` feature.
1190
1191   Feature names are case-sensitive and may only contain letters, numbers and
1192   underscores.  Feature names defined in all uppercase are reserved for CMake's
1193   own built-in features.  Currently, there is only one pre-defined built-in
1194   group feature:
1195
1196   .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt
1197
1198   Built-in and custom group features are defined in terms of the following
1199   variables:
1200
1201   * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
1202   * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`
1203   * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
1204   * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`
1205
1206   The value used for each of these variables is the value as set at the end of
1207   the directory scope in which the target was created.  The usage is as follows:
1208
1209   1. If the language-specific
1210      :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable
1211      is true, the ``feature`` must be defined by the corresponding
1212      :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable.
1213   2. If no language-specific ``feature`` is supported, then the
1214      :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable must be
1215      true and the ``feature`` must be defined by the corresponding
1216      :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable.
1217
1218   The ``LINK_GROUP`` generator expression is compatible with the
1219   :genex:`LINK_LIBRARY` generator expression. The libraries involved in a
1220   group can be specified using the :genex:`LINK_LIBRARY` generator expression.
1221
1222   Each target or external library involved in the link step is allowed to be
1223   part of multiple groups, but only if all the groups involved specify the
1224   same ``feature``.  Such groups will not be merged on the linker command line,
1225   the individual groups will still be preserved.  Mixing different group
1226   features for the same target or library is forbidden.
1227
1228   .. code-block:: cmake
1229
1230     add_library(lib1 ...)
1231     add_library(lib2 ...)
1232     add_library(lib3 ...)
1233     add_library(lib4 ...)
1234     add_library(lib5 ...)
1235
1236     target_link_libraries(lib3 PUBLIC  "$<LINK_GROUP:feature1,lib1,lib2>")
1237     target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
1238     # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
1239     # Both groups specify the same feature, so this is fine.
1240
1241     target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
1242     # An error will be raised here because both lib1 and lib3 are part of two
1243     # groups with different features.
1244
1245   When a target or an external library is involved in the link step as part of
1246   a group and also as not part of any group, any occurrence of the non-group
1247   link item will be replaced by the groups it belongs to.
1248
1249   .. code-block:: cmake
1250
1251     add_library(lib1 ...)
1252     add_library(lib2 ...)
1253     add_library(lib3 ...)
1254     add_library(lib4 ...)
1255
1256     target_link_libraries(lib3 PUBLIC lib1)
1257
1258     target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
1259     # lib4 will only be linked with lib3 and the group {lib1,lib2}
1260
1261   Because ``lib1`` is part of the group defined for ``lib4``, that group then
1262   gets applied back to the use of ``lib1`` for ``lib3``.  The end result will
1263   be as though the linking relationship for ``lib3`` had been specified as:
1264
1265   .. code-block:: cmake
1266
1267     target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
1268
1269   Be aware that the precedence of the group over the non-group link item can
1270   result in circular dependencies between groups.  If this occurs, a fatal
1271   error is raised because circular dependencies are not allowed for groups.
1272
1273   .. code-block:: cmake
1274
1275     add_library(lib1A ...)
1276     add_library(lib1B ...)
1277     add_library(lib2A ...)
1278     add_library(lib2B ...)
1279     add_library(lib3 ...)
1280
1281     # Non-group linking relationships, these are non-circular so far
1282     target_link_libraries(lib1A PUBLIC lib2A)
1283     target_link_libraries(lib2B PUBLIC lib1B)
1284
1285     # The addition of these groups creates circular dependencies
1286     target_link_libraries(lib3 PRIVATE
1287       "$<LINK_GROUP:feat,lib1A,lib1B>"
1288       "$<LINK_GROUP:feat,lib2A,lib2B>"
1289     )
1290
1291   Because of the groups defined for ``lib3``, the linking relationships for
1292   ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of:
1293
1294   .. code-block:: cmake
1295
1296     target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
1297     target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
1298
1299   This creates a circular dependency between groups:
1300   ``lib1A --> lib2B --> lib1A``.
1301
1302   The following limitations should also be noted:
1303
1304   * The ``library-list`` can specify CMake targets or libraries.
1305     Any CMake target of type :ref:`OBJECT <Object Libraries>`
1306     or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
1307     of the expression and instead be linked in the standard way.
1308
1309   * The ``$<LINK_GROUP:...>`` generator expression can only be used to
1310     specify link libraries.  In practice, this means it can appear in the
1311     :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and
1312     :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be
1313     specified in :command:`target_link_libraries` and :command:`link_libraries`
1314     commands.
1315
1316   * If a ``$<LINK_GROUP:...>`` generator expression appears in the
1317     :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
1318     included in the imported target generated by a :command:`install(EXPORT)`
1319     command.  It is the responsibility of the environment consuming this
1320     import to define the link feature used by this expression.
1321
1322 Link Context
1323 ^^^^^^^^^^^^
1324
1325 .. genex:: $<LINK_ONLY:...>
1326
1327   .. versionadded:: 3.1
1328
1329   Content of ``...``, except while collecting :ref:`Target Usage Requirements`,
1330   in which case it is the empty string.  This is intended for use in an
1331   :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated
1332   via the :command:`target_link_libraries` command, to specify private link
1333   dependencies without other usage requirements.
1334
1335   .. versionadded:: 3.24
1336     ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target
1337     property.  See policy :policy:`CMP0131`.
1338
1339 .. genex:: $<DEVICE_LINK:list>
1340
1341   .. versionadded:: 3.18
1342
1343   Returns the list if it is the device link step, an empty list otherwise.
1344   The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
1345   and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and
1346   policy :policy:`CMP0105`. This expression can only be used to specify link
1347   options.
1348
1349 .. genex:: $<HOST_LINK:list>
1350
1351   .. versionadded:: 3.18
1352
1353   Returns the list if it is the normal link step, an empty list otherwise.
1354   This expression is mainly useful when a device link step is also involved
1355   (see :genex:`$<DEVICE_LINK:list>` generator expression). This expression can
1356   only be used to specify link options.
1357
1358
1359 .. _`Target-Dependent Queries`:
1360
1361 Target-Dependent Expressions
1362 ----------------------------
1363
1364 These queries refer to a target ``tgt``. Unless otherwise stated, this can
1365 be any runtime artifact, namely:
1366
1367 * An executable target created by :command:`add_executable`.
1368 * A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
1369   library) created by :command:`add_library`.
1370 * A static library target created by :command:`add_library`.
1371
1372 In the following, the phrase "the ``tgt`` filename" means the name of the
1373 ``tgt`` binary file. This has to be distinguished from the phrase
1374 "the target name", which is just the string ``tgt``.
1375
1376 .. genex:: $<TARGET_EXISTS:tgt>
1377
1378   .. versionadded:: 3.12
1379
1380   ``1`` if ``tgt`` exists as a CMake target, else ``0``.
1381
1382 .. genex:: $<TARGET_NAME_IF_EXISTS:tgt>
1383
1384   .. versionadded:: 3.12
1385
1386   The target name ``tgt`` if the target exists, an empty string otherwise.
1387
1388   Note that ``tgt`` is not added as a dependency of the target this
1389   expression is evaluated on.
1390
1391 .. genex:: $<TARGET_NAME:...>
1392
1393   Marks ``...`` as being the name of a target.  This is required if exporting
1394   targets to multiple dependent export sets.  The ``...`` must be a literal
1395   name of a target, it may not contain generator expressions.
1396
1397 .. genex:: $<TARGET_PROPERTY:tgt,prop>
1398
1399   Value of the property ``prop`` on the target ``tgt``.
1400
1401   Note that ``tgt`` is not added as a dependency of the target this
1402   expression is evaluated on.
1403
1404 .. genex:: $<TARGET_PROPERTY:prop>
1405
1406   Value of the property ``prop`` on the target for which the expression
1407   is being evaluated. Note that for generator expressions in
1408   :ref:`Target Usage Requirements` this is the consuming target rather
1409   than the target specifying the requirement.
1410
1411 .. genex:: $<TARGET_OBJECTS:tgt>
1412
1413   .. versionadded:: 3.1
1414
1415   List of objects resulting from building ``tgt``.  This would typically be
1416   used on :ref:`object library <Object Libraries>` targets.
1417
1418 .. genex:: $<TARGET_POLICY:policy>
1419
1420   ``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
1421   else ``0``.  If the ``policy`` was not set, the warning message for the policy
1422   will be emitted. This generator expression only works for a subset of
1423   policies.
1424
1425 .. genex:: $<TARGET_FILE:tgt>
1426
1427   Full path to the ``tgt`` binary file.
1428
1429   Note that ``tgt`` is not added as a dependency of the target this
1430   expression is evaluated on, unless the expression is being used in
1431   :command:`add_custom_command` or :command:`add_custom_target`.
1432
1433 .. genex:: $<TARGET_FILE_BASE_NAME:tgt>
1434
1435   .. versionadded:: 3.15
1436
1437   Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and
1438   suffix.
1439   For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``.
1440
1441   See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
1442   :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
1443   target properties and their configuration specific variants
1444   :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`,
1445   :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and
1446   :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`.
1447
1448   The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
1449   properties can also be considered.
1450
1451   Note that ``tgt`` is not added as a dependency of the target this
1452   expression is evaluated on.
1453
1454 .. genex:: $<TARGET_FILE_PREFIX:tgt>
1455
1456   .. versionadded:: 3.15
1457
1458   Prefix of the ``tgt`` filename (such as ``lib``).
1459
1460   See also the :prop_tgt:`PREFIX` target property.
1461
1462   Note that ``tgt`` is not added as a dependency of the target this
1463   expression is evaluated on.
1464
1465 .. genex:: $<TARGET_FILE_SUFFIX:tgt>
1466
1467   .. versionadded:: 3.15
1468
1469   Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``).
1470
1471   See also the :prop_tgt:`SUFFIX` target property.
1472
1473   Note that ``tgt`` is not added as a dependency of the target this
1474   expression is evaluated on.
1475
1476 .. genex:: $<TARGET_FILE_NAME:tgt>
1477
1478   The ``tgt`` filename.
1479
1480   Note that ``tgt`` is not added as a dependency of the target this
1481   expression is evaluated on (see policy :policy:`CMP0112`).
1482
1483 .. genex:: $<TARGET_FILE_DIR:tgt>
1484
1485   Directory of the ``tgt`` binary file.
1486
1487   Note that ``tgt`` is not added as a dependency of the target this
1488   expression is evaluated on (see policy :policy:`CMP0112`).
1489
1490 .. genex:: $<TARGET_LINKER_FILE:tgt>
1491
1492   File used when linking to the ``tgt`` target.  This will usually
1493   be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``),
1494   but for a shared library on DLL platforms, it would be the ``.lib``
1495   import library associated with the DLL.
1496
1497 .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt>
1498
1499   .. versionadded:: 3.15
1500
1501   Base name of file used to link the target ``tgt``, i.e.
1502   ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example,
1503   if target file name is ``libbase.a``, the base name is ``base``.
1504
1505   See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
1506   and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration
1507   specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`,
1508   :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and
1509   :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`.
1510
1511   The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
1512   properties can also be considered.
1513
1514   Note that ``tgt`` is not added as a dependency of the target this
1515   expression is evaluated on.
1516
1517 .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt>
1518
1519   .. versionadded:: 3.15
1520
1521   Prefix of file used to link target ``tgt``.
1522
1523   See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target
1524   properties.
1525
1526   Note that ``tgt`` is not added as a dependency of the target this
1527   expression is evaluated on.
1528
1529 .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt>
1530
1531   .. versionadded:: 3.15
1532
1533   Suffix of file used to link where ``tgt`` is the name of a target.
1534
1535   The suffix corresponds to the file extension (such as ".so" or ".lib").
1536
1537   See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target
1538   properties.
1539
1540   Note that ``tgt`` is not added as a dependency of the target this
1541   expression is evaluated on.
1542
1543 .. genex:: $<TARGET_LINKER_FILE_NAME:tgt>
1544
1545   Name of file used to link target ``tgt``.
1546
1547   Note that ``tgt`` is not added as a dependency of the target this
1548   expression is evaluated on (see policy :policy:`CMP0112`).
1549
1550 .. genex:: $<TARGET_LINKER_FILE_DIR:tgt>
1551
1552   Directory of file used to link target ``tgt``.
1553
1554   Note that ``tgt`` is not added as a dependency of the target this
1555   expression is evaluated on (see policy :policy:`CMP0112`).
1556
1557 .. genex:: $<TARGET_SONAME_FILE:tgt>
1558
1559   File with soname (``.so.3``) where ``tgt`` is the name of a target.
1560 .. genex:: $<TARGET_SONAME_FILE_NAME:tgt>
1561
1562   Name of file with soname (``.so.3``).
1563
1564   Note that ``tgt`` is not added as a dependency of the target this
1565   expression is evaluated on (see policy :policy:`CMP0112`).
1566
1567 .. genex:: $<TARGET_SONAME_FILE_DIR:tgt>
1568
1569   Directory of with soname (``.so.3``).
1570
1571   Note that ``tgt`` is not added as a dependency of the target this
1572   expression is evaluated on (see policy :policy:`CMP0112`).
1573
1574 .. genex:: $<TARGET_PDB_FILE:tgt>
1575
1576   .. versionadded:: 3.1
1577
1578   Full path to the linker generated program database file (.pdb)
1579   where ``tgt`` is the name of a target.
1580
1581   See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
1582   target properties and their configuration specific variants
1583   :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`.
1584
1585 .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt>
1586
1587   .. versionadded:: 3.15
1588
1589   Base name of the linker generated program database file (.pdb)
1590   where ``tgt`` is the name of a target.
1591
1592   The base name corresponds to the target PDB file name (see
1593   ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example,
1594   if target file name is ``base.pdb``, the base name is ``base``.
1595
1596   See also the :prop_tgt:`PDB_NAME` target property and its configuration
1597   specific variant :prop_tgt:`PDB_NAME_<CONFIG>`.
1598
1599   The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
1600   properties can also be considered.
1601
1602   Note that ``tgt`` is not added as a dependency of the target this
1603   expression is evaluated on.
1604
1605 .. genex:: $<TARGET_PDB_FILE_NAME:tgt>
1606
1607   .. versionadded:: 3.1
1608
1609   Name of the linker generated program database file (.pdb).
1610
1611   Note that ``tgt`` is not added as a dependency of the target this
1612   expression is evaluated on (see policy :policy:`CMP0112`).
1613
1614 .. genex:: $<TARGET_PDB_FILE_DIR:tgt>
1615
1616   .. versionadded:: 3.1
1617
1618   Directory of the linker generated program database file (.pdb).
1619
1620   Note that ``tgt`` is not added as a dependency of the target this
1621   expression is evaluated on (see policy :policy:`CMP0112`).
1622
1623 .. genex:: $<TARGET_BUNDLE_DIR:tgt>
1624
1625   .. versionadded:: 3.9
1626
1627   Full path to the bundle directory (``/path/to/my.app``,
1628   ``/path/to/my.framework``, or ``/path/to/my.bundle``),
1629   where ``tgt`` is the name of a target.
1630
1631   Note that ``tgt`` is not added as a dependency of the target this
1632   expression is evaluated on (see policy :policy:`CMP0112`).
1633
1634 .. genex:: $<TARGET_BUNDLE_DIR_NAME:tgt>
1635
1636   .. versionadded:: 3.24
1637
1638   Name of the bundle directory (``my.app``, ``my.framework``, or
1639   ``my.bundle``), where ``tgt`` is the name of a target.
1640
1641   Note that ``tgt`` is not added as a dependency of the target this
1642   expression is evaluated on (see policy :policy:`CMP0112`).
1643
1644 .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt>
1645
1646   .. versionadded:: 3.9
1647
1648   Full path to the bundle content directory where ``tgt`` is the name of a
1649   target.  For the macOS SDK it leads to ``/path/to/my.app/Contents``,
1650   ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``.
1651   For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``,
1652   ``/path/to/my.framework``, or ``/path/to/my.bundle`` due to the flat
1653   bundle structure.
1654
1655   Note that ``tgt`` is not added as a dependency of the target this
1656   expression is evaluated on (see policy :policy:`CMP0112`).
1657
1658 .. genex:: $<TARGET_RUNTIME_DLLS:tgt>
1659
1660   .. versionadded:: 3.21
1661
1662   List of DLLs that the target depends on at runtime. This is determined by
1663   the locations of all the ``SHARED`` targets in the target's transitive
1664   dependencies. Using this generator expression on targets other than
1665   executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error.
1666   **On non-DLL platforms, this expression always evaluates to an empty string**.
1667
1668   This generator expression can be used to copy all of the DLLs that a target
1669   depends on into its output directory in a ``POST_BUILD`` custom command. For
1670   example:
1671
1672   .. code-block:: cmake
1673
1674     find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
1675
1676     add_executable(exe main.c)
1677     target_link_libraries(exe PRIVATE foo::foo foo::bar)
1678     add_custom_command(TARGET exe POST_BUILD
1679       COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
1680       COMMAND_EXPAND_LISTS
1681     )
1682
1683   .. note::
1684
1685     :ref:`Imported Targets` are supported only if they know the location
1686     of their ``.dll`` files.  An imported ``SHARED`` library must have
1687     :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file.  See the
1688     :ref:`add_library imported libraries <add_library imported libraries>`
1689     section for details.  Many :ref:`Find Modules` produce imported targets
1690     with the ``UNKNOWN`` type and therefore will be ignored.
1691
1692
1693 Export And Install Expressions
1694 ------------------------------
1695
1696 .. genex:: $<INSTALL_INTERFACE:...>
1697
1698   Content of ``...`` when the property is exported using
1699   :command:`install(EXPORT)`, and empty otherwise.
1700
1701 .. genex:: $<BUILD_INTERFACE:...>
1702
1703   Content of ``...`` when the property is exported using :command:`export`, or
1704   when the target is used by another target in the same buildsystem. Expands to
1705   the empty string otherwise.
1706
1707 .. genex:: $<INSTALL_PREFIX>
1708
1709   Content of the install prefix when the target is exported via
1710   :command:`install(EXPORT)`, or when evaluated in the
1711   :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of
1712   :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise.
1713
1714 Multi-level Expression Evaluation
1715 ---------------------------------
1716
1717 .. genex:: $<GENEX_EVAL:expr>
1718
1719   .. versionadded:: 3.12
1720
1721   Content of ``expr`` evaluated as a generator expression in the current
1722   context. This enables consumption of generator expressions whose
1723   evaluation results itself in generator expressions.
1724
1725 .. genex:: $<TARGET_GENEX_EVAL:tgt,expr>
1726
1727   .. versionadded:: 3.12
1728
1729   Content of ``expr`` evaluated as a generator expression in the context of
1730   ``tgt`` target. This enables consumption of custom target properties that
1731   themselves contain generator expressions.
1732
1733   Having the capability to evaluate generator expressions is very useful when
1734   you want to manage custom properties supporting generator expressions.
1735   For example:
1736
1737   .. code-block:: cmake
1738
1739     add_library(foo ...)
1740
1741     set_property(TARGET foo PROPERTY
1742       CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
1743     )
1744
1745     add_custom_target(printFooKeys
1746       COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
1747     )
1748
1749   This naive implementation of the ``printFooKeys`` custom command is wrong
1750   because ``CUSTOM_KEYS`` target property is not evaluated and the content
1751   is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``).
1752
1753   To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is
1754   ``Debug``), it is required to evaluate the output of
1755   ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``:
1756
1757   .. code-block:: cmake
1758
1759     add_custom_target(printFooKeys
1760       COMMAND ${CMAKE_COMMAND} -E
1761         echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
1762     )
1763
1764 Escaped Characters
1765 ------------------
1766
1767 These expressions evaluate to specific string literals. Use them in place of
1768 the actual string literal where you need to prevent them from having their
1769 special meaning.
1770
1771 .. genex:: $<ANGLE-R>
1772
1773   A literal ``>``. Used for example to compare strings that contain a ``>``.
1774
1775 .. genex:: $<COMMA>
1776
1777   A literal ``,``. Used for example to compare strings which contain a ``,``.
1778
1779 .. genex:: $<SEMICOLON>
1780
1781   A literal ``;``. Used to prevent list expansion on an argument with ``;``.
1782
1783 Deprecated Expressions
1784 ----------------------
1785
1786 .. genex:: $<CONFIGURATION>
1787
1788   Configuration name. Deprecated since CMake 3.0. Use :genex:`CONFIG` instead.