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 .. genex:: $<OUTPUT_CONFIG:...>
 598
 599   .. versionadded:: 3.20
 600
 601   Only valid in :command:`add_custom_command` and :command:`add_custom_target`
 602   as the outer-most generator expression in an argument.
 603   With the :generator:`Ninja Multi-Config` generator, generator expressions
 604   in ``...`` are evaluated using the custom command's "output config".
 605   With other generators, the content of ``...`` is evaluated normally.
 606
 607 .. genex:: $<COMMAND_CONFIG:...>
 608
 609   .. versionadded:: 3.20
 610
 611   Only valid in :command:`add_custom_command` and :command:`add_custom_target`
 612   as the outer-most generator expression in an argument.
 613   With the :generator:`Ninja Multi-Config` generator, generator expressions
 614   in ``...`` are evaluated using the custom command's "command config".
 615   With other generators, the content of ``...`` is evaluated normally.
 616
 617 Toolchain And Language Expressions
 618 ----------------------------------
 619
 620 Platform
 621 ^^^^^^^^
 622
 623 .. genex:: $<PLATFORM_ID>
 624
 625   The current system's CMake platform id.
 626   See also the :variable:`CMAKE_SYSTEM_NAME` variable.
 627
 628 .. genex:: $<PLATFORM_ID:platform_ids>
 629
 630   where ``platform_ids`` is a comma-separated list.
 631   ``1`` if CMake's platform id matches any one of the entries in
 632   ``platform_ids``, otherwise ``0``.
 633   See also the :variable:`CMAKE_SYSTEM_NAME` variable.
 634
 635 Compiler Version
 636 ^^^^^^^^^^^^^^^^
 637
 638 See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable, which is
 639 closely related to the expressions in this sub-section.
 640
 641 .. genex:: $<C_COMPILER_VERSION>
 642
 643   The version of the C compiler used.
 644
 645 .. genex:: $<C_COMPILER_VERSION:version>
 646
 647   ``1`` if the version of the C compiler matches ``version``, otherwise ``0``.
 648
 649 .. genex:: $<CXX_COMPILER_VERSION>
 650
 651   The version of the CXX compiler used.
 652
 653 .. genex:: $<CXX_COMPILER_VERSION:version>
 654
 655   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
 656
 657 .. genex:: $<CUDA_COMPILER_VERSION>
 658
 659   .. versionadded:: 3.15
 660
 661   The version of the CUDA compiler used.
 662
 663 .. genex:: $<CUDA_COMPILER_VERSION:version>
 664
 665   .. versionadded:: 3.15
 666
 667   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
 668
 669 .. genex:: $<OBJC_COMPILER_VERSION>
 670
 671   .. versionadded:: 3.16
 672
 673   The version of the OBJC compiler used.
 674
 675 .. genex:: $<OBJC_COMPILER_VERSION:version>
 676
 677   .. versionadded:: 3.16
 678
 679   ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``.
 680
 681 .. genex:: $<OBJCXX_COMPILER_VERSION>
 682
 683   .. versionadded:: 3.16
 684
 685   The version of the OBJCXX compiler used.
 686
 687 .. genex:: $<OBJCXX_COMPILER_VERSION:version>
 688
 689   .. versionadded:: 3.16
 690
 691   ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``.
 692
 693 .. genex:: $<Fortran_COMPILER_VERSION>
 694
 695   The version of the Fortran compiler used.
 696
 697 .. genex:: $<Fortran_COMPILER_VERSION:version>
 698
 699   ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``.
 700
 701 .. genex:: $<HIP_COMPILER_VERSION>
 702
 703   .. versionadded:: 3.21
 704
 705   The version of the HIP compiler used.
 706
 707 .. genex:: $<HIP_COMPILER_VERSION:version>
 708
 709   .. versionadded:: 3.21
 710
 711   ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``.
 712
 713 .. genex:: $<ISPC_COMPILER_VERSION>
 714
 715   .. versionadded:: 3.19
 716
 717   The version of the ISPC compiler used.
 718
 719 .. genex:: $<ISPC_COMPILER_VERSION:version>
 720
 721   .. versionadded:: 3.19
 722
 723   ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``.
 724
 725 Compiler Language And ID
 726 ^^^^^^^^^^^^^^^^^^^^^^^^
 727
 728 See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable, which is closely
 729 related to most of the expressions in this sub-section.
 730
 731 .. genex:: $<C_COMPILER_ID>
 732
 733   CMake's compiler id of the C compiler used.
 734
 735 .. genex:: $<C_COMPILER_ID:compiler_ids>
 736
 737   where ``compiler_ids`` is a comma-separated list.
 738   ``1`` if CMake's compiler id of the C compiler matches any one
 739   of the entries in ``compiler_ids``, otherwise ``0``.
 740
 741 .. genex:: $<CXX_COMPILER_ID>
 742
 743   CMake's compiler id of the CXX compiler used.
 744
 745 .. genex:: $<CXX_COMPILER_ID:compiler_ids>
 746
 747   where ``compiler_ids`` is a comma-separated list.
 748   ``1`` if CMake's compiler id of the CXX compiler matches any one
 749   of the entries in ``compiler_ids``, otherwise ``0``.
 750
 751 .. genex:: $<CUDA_COMPILER_ID>
 752
 753   .. versionadded:: 3.15
 754
 755   CMake's compiler id of the CUDA compiler used.
 756
 757 .. genex:: $<CUDA_COMPILER_ID:compiler_ids>
 758
 759   .. versionadded:: 3.15
 760
 761   where ``compiler_ids`` is a comma-separated list.
 762   ``1`` if CMake's compiler id of the CUDA compiler matches any one
 763   of the entries in ``compiler_ids``, otherwise ``0``.
 764
 765 .. genex:: $<OBJC_COMPILER_ID>
 766
 767   .. versionadded:: 3.16
 768
 769   CMake's compiler id of the OBJC compiler used.
 770
 771 .. genex:: $<OBJC_COMPILER_ID:compiler_ids>
 772
 773   .. versionadded:: 3.16
 774
 775   where ``compiler_ids`` is a comma-separated list.
 776   ``1`` if CMake's compiler id of the Objective-C compiler matches any one
 777   of the entries in ``compiler_ids``, otherwise ``0``.
 778
 779 .. genex:: $<OBJCXX_COMPILER_ID>
 780
 781   .. versionadded:: 3.16
 782
 783   CMake's compiler id of the OBJCXX compiler used.
 784
 785 .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids>
 786
 787   .. versionadded:: 3.16
 788
 789   where ``compiler_ids`` is a comma-separated list.
 790   ``1`` if CMake's compiler id of the Objective-C++ compiler matches any one
 791   of the entries in ``compiler_ids``, otherwise ``0``.
 792
 793 .. genex:: $<Fortran_COMPILER_ID>
 794
 795   CMake's compiler id of the Fortran compiler used.
 796
 797 .. genex:: $<Fortran_COMPILER_ID:compiler_ids>
 798
 799   where ``compiler_ids`` is a comma-separated list.
 800   ``1`` if CMake's compiler id of the Fortran compiler matches any one
 801   of the entries in ``compiler_ids``, otherwise ``0``.
 802
 803 .. genex:: $<HIP_COMPILER_ID>
 804
 805   .. versionadded:: 3.21
 806
 807   CMake's compiler id of the HIP compiler used.
 808
 809 .. genex:: $<HIP_COMPILER_ID:compiler_ids>
 810
 811   .. versionadded:: 3.21
 812
 813   where ``compiler_ids`` is a comma-separated list.
 814   ``1`` if CMake's compiler id of the HIP compiler matches any one
 815   of the entries in ``compiler_ids``, otherwise ``0``.
 816
 817 .. genex:: $<ISPC_COMPILER_ID>
 818
 819   .. versionadded:: 3.19
 820
 821   CMake's compiler id of the ISPC compiler used.
 822
 823 .. genex:: $<ISPC_COMPILER_ID:compiler_ids>
 824
 825   .. versionadded:: 3.19
 826
 827   where ``compiler_ids`` is a comma-separated list.
 828   ``1`` if CMake's compiler id of the ISPC compiler matches any one
 829   of the entries in ``compiler_ids``, otherwise ``0``.
 830
 831 .. genex:: $<COMPILE_LANGUAGE>
 832
 833   .. versionadded:: 3.3
 834
 835   The compile language of source files when evaluating compile options.
 836   See :ref:`the related boolean expression
 837   <Boolean COMPILE_LANGUAGE Generator Expression>`
 838   ``$<COMPILE_LANGUAGE:language>``
 839   for notes about the portability of this generator expression.
 840
 841 .. _`Boolean COMPILE_LANGUAGE Generator Expression`:
 842
 843 .. genex:: $<COMPILE_LANGUAGE:languages>
 844
 845   .. versionadded:: 3.3
 846
 847   ``1`` when the language used for compilation unit matches any of the entries
 848   in ``languages``, otherwise ``0``.  This expression may be used to specify
 849   compile options, compile definitions, and include directories for source
 850   files of a particular language in a target. For example:
 851
 852   .. code-block:: cmake
 853
 854     add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
 855     target_compile_options(myapp
 856       PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
 857     )
 858     target_compile_definitions(myapp
 859       PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
 860               $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
 861     )
 862     target_include_directories(myapp
 863       PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
 864     )
 865
 866   This specifies the use of the ``-fno-exceptions`` compile option,
 867   ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include
 868   directory for C++ only (compiler id checks elided).  It also specifies
 869   a ``COMPILING_CUDA`` compile definition for CUDA.
 870
 871   Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there
 872   is no way to represent target-wide compile definitions or include directories
 873   separately for ``C`` and ``CXX`` languages.
 874   Also, with :ref:`Visual Studio Generators` there is no way to represent
 875   target-wide flags separately for ``C`` and ``CXX`` languages.  Under these
 876   generators, expressions for both C and C++ sources will be evaluated
 877   using ``CXX`` if there are any C++ sources and otherwise using ``C``.
 878   A workaround is to create separate libraries for each source file language
 879   instead:
 880
 881   .. code-block:: cmake
 882
 883     add_library(myapp_c foo.c)
 884     add_library(myapp_cxx bar.cpp)
 885     target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
 886     add_executable(myapp main.cpp)
 887     target_link_libraries(myapp myapp_c myapp_cxx)
 888
 889 .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids>
 890
 891   .. versionadded:: 3.15
 892
 893   ``1`` when the language used for compilation unit matches ``language`` and
 894   CMake's compiler id of the ``language`` compiler matches any one of the
 895   entries in ``compiler_ids``, otherwise ``0``. This expression is a short form
 896   for the combination of ``$<COMPILE_LANGUAGE:language>`` and
 897   ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
 898   compile options, compile definitions, and include directories for source
 899   files of a particular language and compiler combination in a target.
 900   For example:
 901
 902   .. code-block:: cmake
 903
 904     add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
 905     target_compile_definitions(myapp
 906       PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
 907               $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
 908               $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
 909     )
 910
 911   This specifies the use of different compile definitions based on both
 912   the compiler id and compilation language. This example will have a
 913   ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX
 914   compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler.
 915   Likewise, when the C compiler is Clang, it will only see the
 916   ``COMPILING_C_WITH_CLANG`` definition.
 917
 918   Without the ``COMPILE_LANG_AND_ID`` generator expression, the same logic
 919   would be expressed as:
 920
 921   .. code-block:: cmake
 922
 923     target_compile_definitions(myapp
 924       PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
 925               $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
 926               $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
 927     )
 928
 929 Compile Features
 930 ^^^^^^^^^^^^^^^^
 931
 932 .. genex:: $<COMPILE_FEATURES:features>
 933
 934   .. versionadded:: 3.1
 935
 936   where ``features`` is a comma-separated list.
 937   Evaluates to ``1`` if all of the ``features`` are available for the 'head'
 938   target, and ``0`` otherwise. If this expression is used while evaluating
 939   the link implementation of a target and if any dependency transitively
 940   increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
 941   for the 'head' target, an error is reported.  See the
 942   :manual:`cmake-compile-features(7)` manual for information on
 943   compile features and a list of supported compilers.
 944
 945 Linker Language And ID
 946 ^^^^^^^^^^^^^^^^^^^^^^
 947
 948 .. genex:: $<LINK_LANGUAGE>
 949
 950   .. versionadded:: 3.18
 951
 952   The link language of the target when evaluating link options.
 953   See :ref:`the related boolean expression
 954   <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:languages>``
 955   for notes about the portability of this generator expression.
 956
 957   .. note::
 958
 959     This generator expression is not supported by the link libraries
 960     properties to avoid side-effects due to the double evaluation of
 961     these properties.
 962
 963
 964 .. _`Boolean LINK_LANGUAGE Generator Expression`:
 965
 966 .. genex:: $<LINK_LANGUAGE:languages>
 967
 968   .. versionadded:: 3.18
 969
 970   ``1`` when the language used for link step matches any of the entries
 971   in ``languages``, otherwise ``0``.  This expression may be used to specify
 972   link libraries, link options, link directories and link dependencies of a
 973   particular language in a target. For example:
 974
 975   .. code-block:: cmake
 976
 977     add_library(api_C ...)
 978     add_library(api_CXX ...)
 979     add_library(api INTERFACE)
 980     target_link_options(api   INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
 981                                         $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
 982     target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
 983                                         $<$<LINK_LANGUAGE:CXX>:api_CXX>)
 984
 985     add_executable(myapp1 main.c)
 986     target_link_options(myapp1 PRIVATE api)
 987
 988     add_executable(myapp2 main.cpp)
 989     target_link_options(myapp2 PRIVATE api)
 990
 991   This specifies to use the ``api`` target for linking targets ``myapp1`` and
 992   ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and
 993   option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2``
 994   will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be
 995   the link language.
 996
 997   .. _`Constraints LINK_LANGUAGE Generator Expression`:
 998
 999   .. note::
1000
1001     To determine the link language of a target, it is required to collect,
1002     transitively, all the targets which will be linked to it. So, for link
1003     libraries properties, a double evaluation will be done. During the first
1004     evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``.
1005     The link language computed after this first pass will be used to do the
1006     second pass. To avoid inconsistency, it is required that the second pass
1007     do not change the link language. Moreover, to avoid unexpected
1008     side-effects, it is required to specify complete entities as part of the
1009     ``$<LINK_LANGUAGE:..>`` expression. For example:
1010
1011     .. code-block:: cmake
1012
1013       add_library(lib STATIC file.cxx)
1014       add_library(libother STATIC file.c)
1015
1016       # bad usage
1017       add_executable(myapp1 main.c)
1018       target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
1019
1020       # correct usage
1021       add_executable(myapp2 main.c)
1022       target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
1023
1024     In this example, for ``myapp1``, the first pass will, unexpectedly,
1025     determine that the link language is ``CXX`` because the evaluation of the
1026     generator expression will be an empty string so ``myapp1`` will depends on
1027     target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first
1028     evaluation will give ``C`` as link language, so the second pass will
1029     correctly add target ``libother`` as link dependency.
1030
1031 .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids>
1032
1033   .. versionadded:: 3.18
1034
1035   ``1`` when the language used for link step matches ``language`` and the
1036   CMake's compiler id of the language linker matches any one of the entries
1037   in ``compiler_ids``, otherwise ``0``. This expression is a short form for the
1038   combination of ``$<LINK_LANGUAGE:language>`` and
1039   ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
1040   link libraries, link options, link directories and link dependencies of a
1041   particular language and linker combination in a target. For example:
1042
1043   .. code-block:: cmake
1044
1045     add_library(libC_Clang ...)
1046     add_library(libCXX_Clang ...)
1047     add_library(libC_Intel ...)
1048     add_library(libCXX_Intel ...)
1049
1050     add_executable(myapp main.c)
1051     if (CXX_CONFIG)
1052       target_sources(myapp PRIVATE file.cxx)
1053     endif()
1054     target_link_libraries(myapp
1055       PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
1056               $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
1057               $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
1058               $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
1059
1060   This specifies the use of different link libraries based on both the
1061   compiler id and link language. This example will have target ``libCXX_Clang``
1062   as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX``
1063   linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker.
1064   Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target
1065   ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when
1066   ``Intel`` is the ``C`` linker.
1067
1068   See :ref:`the note related to
1069   <Constraints LINK_LANGUAGE Generator Expression>`
1070   ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
1071   generator expression.
1072
1073 Link Features
1074 ^^^^^^^^^^^^^
1075
1076 .. genex:: $<LINK_LIBRARY:feature,library-list>
1077
1078   .. versionadded:: 3.24
1079
1080   Specify a set of libraries to link to a target, along with a ``feature``
1081   which provides details about *how* they should be linked.  For example:
1082
1083   .. code-block:: cmake
1084
1085     add_library(lib1 STATIC ...)
1086     add_library(lib2 ...)
1087     target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")
1088
1089   This specifies that ``lib2`` should link to ``lib1`` and use the
1090   ``WHOLE_ARCHIVE`` feature when doing so.
1091
1092   Feature names are case-sensitive and may only contain letters, numbers and
1093   underscores.  Feature names defined in all uppercase are reserved for CMake's
1094   own built-in features.  The pre-defined built-in library features are:
1095
1096   .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
1097
1098   Built-in and custom library features are defined in terms of the following
1099   variables:
1100
1101   * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
1102   * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
1103   * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
1104   * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`
1105
1106   The value used for each of these variables is the value as set at the end of
1107   the directory scope in which the target was created.  The usage is as follows:
1108
1109   1. If the language-specific
1110      :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable
1111      is true, the ``feature`` must be defined by the corresponding
1112      :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable.
1113   2. If no language-specific ``feature`` is supported, then the
1114      :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable must be
1115      true and the ``feature`` must be defined by the corresponding
1116      :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable.
1117
1118   The following limitations should be noted:
1119
1120   * The ``library-list`` can specify CMake targets or libraries.
1121     Any CMake target of type :ref:`OBJECT <Object Libraries>`
1122     or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
1123     of the expression and instead be linked in the standard way.
1124
1125   * The ``$<LINK_LIBRARY:...>`` generator expression can only be used to
1126     specify link libraries.  In practice, this means it can appear in the
1127     :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
1128     :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`  target properties, and be
1129     specified in :command:`target_link_libraries` and :command:`link_libraries`
1130     commands.
1131
1132   * If a ``$<LINK_LIBRARY:...>`` generator expression appears in the
1133     :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
1134     included in the imported target generated by a :command:`install(EXPORT)`
1135     command.  It is the responsibility of the environment consuming this
1136     import to define the link feature used by this expression.
1137
1138   * Each target or library involved in the link step must have at most only
1139     one kind of library feature.  The absence of a feature is also incompatible
1140     with all other features.  For example:
1141
1142     .. code-block:: cmake
1143
1144       add_library(lib1 ...)
1145       add_library(lib2 ...)
1146       add_library(lib3 ...)
1147
1148       # lib1 will be associated with feature1
1149       target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
1150
1151       # lib1 is being linked with no feature here. This conflicts with the
1152       # use of feature1 in the line above and would result in an error.
1153       target_link_libraries(lib3 PRIVATE lib1 lib2)
1154
1155     Where it isn't possible to use the same feature throughout a build for a
1156     given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
1157     :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be
1158     used to resolve such incompatibilities.
1159
1160   * The ``$<LINK_LIBRARY:...>`` generator expression does not guarantee
1161     that the list of specified targets and libraries will be kept grouped
1162     together.  To manage constructs like ``--start-group`` and ``--end-group``,
1163     as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP`
1164     generator expression instead.
1165
1166 .. genex:: $<LINK_GROUP:feature,library-list>
1167
1168   .. versionadded:: 3.24
1169
1170   Specify a group of libraries to link to a target, along with a ``feature``
1171   which defines how that group should be linked.  For example:
1172
1173   .. code-block:: cmake
1174
1175     add_library(lib1 STATIC ...)
1176     add_library(lib2 ...)
1177     target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
1178
1179   This specifies that ``lib2`` should link to ``lib1`` and ``external``, and
1180   that both of those two libraries should be included on the linker command
1181   line according to the definition of the ``RESCAN`` feature.
1182
1183   Feature names are case-sensitive and may only contain letters, numbers and
1184   underscores.  Feature names defined in all uppercase are reserved for CMake's
1185   own built-in features.  Currently, there is only one pre-defined built-in
1186   group feature:
1187
1188   .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt
1189
1190   Built-in and custom group features are defined in terms of the following
1191   variables:
1192
1193   * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
1194   * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`
1195   * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
1196   * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`
1197
1198   The value used for each of these variables is the value as set at the end of
1199   the directory scope in which the target was created.  The usage is as follows:
1200
1201   1. If the language-specific
1202      :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable
1203      is true, the ``feature`` must be defined by the corresponding
1204      :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable.
1205   2. If no language-specific ``feature`` is supported, then the
1206      :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable must be
1207      true and the ``feature`` must be defined by the corresponding
1208      :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable.
1209
1210   The ``LINK_GROUP`` generator expression is compatible with the
1211   :genex:`LINK_LIBRARY` generator expression. The libraries involved in a
1212   group can be specified using the :genex:`LINK_LIBRARY` generator expression.
1213
1214   Each target or external library involved in the link step is allowed to be
1215   part of multiple groups, but only if all the groups involved specify the
1216   same ``feature``.  Such groups will not be merged on the linker command line,
1217   the individual groups will still be preserved.  Mixing different group
1218   features for the same target or library is forbidden.
1219
1220   .. code-block:: cmake
1221
1222     add_library(lib1 ...)
1223     add_library(lib2 ...)
1224     add_library(lib3 ...)
1225     add_library(lib4 ...)
1226     add_library(lib5 ...)
1227
1228     target_link_libraries(lib3 PUBLIC  "$<LINK_GROUP:feature1,lib1,lib2>")
1229     target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
1230     # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
1231     # Both groups specify the same feature, so this is fine.
1232
1233     target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
1234     # An error will be raised here because both lib1 and lib3 are part of two
1235     # groups with different features.
1236
1237   When a target or an external library is involved in the link step as part of
1238   a group and also as not part of any group, any occurrence of the non-group
1239   link item will be replaced by the groups it belongs to.
1240
1241   .. code-block:: cmake
1242
1243     add_library(lib1 ...)
1244     add_library(lib2 ...)
1245     add_library(lib3 ...)
1246     add_library(lib4 ...)
1247
1248     target_link_libraries(lib3 PUBLIC lib1)
1249
1250     target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
1251     # lib4 will only be linked with lib3 and the group {lib1,lib2}
1252
1253   Because ``lib1`` is part of the group defined for ``lib4``, that group then
1254   gets applied back to the use of ``lib1`` for ``lib3``.  The end result will
1255   be as though the linking relationship for ``lib3`` had been specified as:
1256
1257   .. code-block:: cmake
1258
1259     target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
1260
1261   Be aware that the precedence of the group over the non-group link item can
1262   result in circular dependencies between groups.  If this occurs, a fatal
1263   error is raised because circular dependencies are not allowed for groups.
1264
1265   .. code-block:: cmake
1266
1267     add_library(lib1A ...)
1268     add_library(lib1B ...)
1269     add_library(lib2A ...)
1270     add_library(lib2B ...)
1271     add_library(lib3 ...)
1272
1273     # Non-group linking relationships, these are non-circular so far
1274     target_link_libraries(lib1A PUBLIC lib2A)
1275     target_link_libraries(lib2B PUBLIC lib1B)
1276
1277     # The addition of these groups creates circular dependencies
1278     target_link_libraries(lib3 PRIVATE
1279       "$<LINK_GROUP:feat,lib1A,lib1B>"
1280       "$<LINK_GROUP:feat,lib2A,lib2B>"
1281     )
1282
1283   Because of the groups defined for ``lib3``, the linking relationships for
1284   ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of:
1285
1286   .. code-block:: cmake
1287
1288     target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
1289     target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
1290
1291   This creates a circular dependency between groups:
1292   ``lib1A --> lib2B --> lib1A``.
1293
1294   The following limitations should also be noted:
1295
1296   * The ``library-list`` can specify CMake targets or libraries.
1297     Any CMake target of type :ref:`OBJECT <Object Libraries>`
1298     or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
1299     of the expression and instead be linked in the standard way.
1300
1301   * The ``$<LINK_GROUP:...>`` generator expression can only be used to
1302     specify link libraries.  In practice, this means it can appear in the
1303     :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and
1304     :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be
1305     specified in :command:`target_link_libraries` and :command:`link_libraries`
1306     commands.
1307
1308   * If a ``$<LINK_GROUP:...>`` generator expression appears in the
1309     :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
1310     included in the imported target generated by a :command:`install(EXPORT)`
1311     command.  It is the responsibility of the environment consuming this
1312     import to define the link feature used by this expression.
1313
1314 Link Context
1315 ^^^^^^^^^^^^
1316
1317 .. genex:: $<LINK_ONLY:...>
1318
1319   .. versionadded:: 3.1
1320
1321   Content of ``...``, except while collecting :ref:`Target Usage Requirements`,
1322   in which case it is the empty string.  This is intended for use in an
1323   :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated
1324   via the :command:`target_link_libraries` command, to specify private link
1325   dependencies without other usage requirements.
1326
1327   .. versionadded:: 3.24
1328     ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target
1329     property.  See policy :policy:`CMP0131`.
1330
1331 .. genex:: $<DEVICE_LINK:list>
1332
1333   .. versionadded:: 3.18
1334
1335   Returns the list if it is the device link step, an empty list otherwise.
1336   The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
1337   and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and
1338   policy :policy:`CMP0105`. This expression can only be used to specify link
1339   options.
1340
1341 .. genex:: $<HOST_LINK:list>
1342
1343   .. versionadded:: 3.18
1344
1345   Returns the list if it is the normal link step, an empty list otherwise.
1346   This expression is mainly useful when a device link step is also involved
1347   (see :genex:`$<DEVICE_LINK:list>` generator expression). This expression can
1348   only be used to specify link options.
1349
1350
1351 .. _`Target-Dependent Queries`:
1352
1353 Target-Dependent Expressions
1354 ----------------------------
1355
1356 These queries refer to a target ``tgt``. Unless otherwise stated, this can
1357 be any runtime artifact, namely:
1358
1359 * An executable target created by :command:`add_executable`.
1360 * A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
1361   library) created by :command:`add_library`.
1362 * A static library target created by :command:`add_library`.
1363
1364 In the following, the phrase "the ``tgt`` filename" means the name of the
1365 ``tgt`` binary file. This has to be distinguished from the phrase
1366 "the target name", which is just the string ``tgt``.
1367
1368 .. genex:: $<TARGET_EXISTS:tgt>
1369
1370   .. versionadded:: 3.12
1371
1372   ``1`` if ``tgt`` exists as a CMake target, else ``0``.
1373
1374 .. genex:: $<TARGET_NAME_IF_EXISTS:tgt>
1375
1376   .. versionadded:: 3.12
1377
1378   The target name ``tgt`` if the target exists, an empty string otherwise.
1379
1380   Note that ``tgt`` is not added as a dependency of the target this
1381   expression is evaluated on.
1382
1383 .. genex:: $<TARGET_NAME:...>
1384
1385   Marks ``...`` as being the name of a target.  This is required if exporting
1386   targets to multiple dependent export sets.  The ``...`` must be a literal
1387   name of a target, it may not contain generator expressions.
1388
1389 .. genex:: $<TARGET_PROPERTY:tgt,prop>
1390
1391   Value of the property ``prop`` on the target ``tgt``.
1392
1393   Note that ``tgt`` is not added as a dependency of the target this
1394   expression is evaluated on.
1395
1396 .. genex:: $<TARGET_PROPERTY:prop>
1397
1398   Value of the property ``prop`` on the target for which the expression
1399   is being evaluated. Note that for generator expressions in
1400   :ref:`Target Usage Requirements` this is the consuming target rather
1401   than the target specifying the requirement.
1402
1403 .. genex:: $<TARGET_OBJECTS:tgt>
1404
1405   .. versionadded:: 3.1
1406
1407   List of objects resulting from building ``tgt``.  This would typically be
1408   used on :ref:`object library <Object Libraries>` targets.
1409
1410 .. genex:: $<TARGET_POLICY:policy>
1411
1412   ``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
1413   else ``0``.  If the ``policy`` was not set, the warning message for the policy
1414   will be emitted. This generator expression only works for a subset of
1415   policies.
1416
1417 .. genex:: $<TARGET_FILE:tgt>
1418
1419   Full path to the ``tgt`` binary file.
1420
1421   Note that ``tgt`` is not added as a dependency of the target this
1422   expression is evaluated on, unless the expression is being used in
1423   :command:`add_custom_command` or :command:`add_custom_target`.
1424
1425 .. genex:: $<TARGET_FILE_BASE_NAME:tgt>
1426
1427   .. versionadded:: 3.15
1428
1429   Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and
1430   suffix.
1431   For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``.
1432
1433   See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
1434   :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
1435   target properties and their configuration specific variants
1436   :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`,
1437   :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and
1438   :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`.
1439
1440   The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
1441   properties can also be considered.
1442
1443   Note that ``tgt`` is not added as a dependency of the target this
1444   expression is evaluated on.
1445
1446 .. genex:: $<TARGET_FILE_PREFIX:tgt>
1447
1448   .. versionadded:: 3.15
1449
1450   Prefix of the ``tgt`` filename (such as ``lib``).
1451
1452   See also the :prop_tgt:`PREFIX` target property.
1453
1454   Note that ``tgt`` is not added as a dependency of the target this
1455   expression is evaluated on.
1456
1457 .. genex:: $<TARGET_FILE_SUFFIX:tgt>
1458
1459   .. versionadded:: 3.15
1460
1461   Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``).
1462
1463   See also the :prop_tgt:`SUFFIX` target property.
1464
1465   Note that ``tgt`` is not added as a dependency of the target this
1466   expression is evaluated on.
1467
1468 .. genex:: $<TARGET_FILE_NAME:tgt>
1469
1470   The ``tgt`` filename.
1471
1472   Note that ``tgt`` is not added as a dependency of the target this
1473   expression is evaluated on (see policy :policy:`CMP0112`).
1474
1475 .. genex:: $<TARGET_FILE_DIR:tgt>
1476
1477   Directory of the ``tgt`` binary file.
1478
1479   Note that ``tgt`` is not added as a dependency of the target this
1480   expression is evaluated on (see policy :policy:`CMP0112`).
1481
1482 .. genex:: $<TARGET_LINKER_FILE:tgt>
1483
1484   File used when linking to the ``tgt`` target.  This will usually
1485   be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``),
1486   but for a shared library on DLL platforms, it would be the ``.lib``
1487   import library associated with the DLL.
1488
1489 .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt>
1490
1491   .. versionadded:: 3.15
1492
1493   Base name of file used to link the target ``tgt``, i.e.
1494   ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example,
1495   if target file name is ``libbase.a``, the base name is ``base``.
1496
1497   See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
1498   and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration
1499   specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`,
1500   :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and
1501   :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`.
1502
1503   The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
1504   properties can also be considered.
1505
1506   Note that ``tgt`` is not added as a dependency of the target this
1507   expression is evaluated on.
1508
1509 .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt>
1510
1511   .. versionadded:: 3.15
1512
1513   Prefix of file used to link target ``tgt``.
1514
1515   See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target
1516   properties.
1517
1518   Note that ``tgt`` is not added as a dependency of the target this
1519   expression is evaluated on.
1520
1521 .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt>
1522
1523   .. versionadded:: 3.15
1524
1525   Suffix of file used to link where ``tgt`` is the name of a target.
1526
1527   The suffix corresponds to the file extension (such as ".so" or ".lib").
1528
1529   See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target
1530   properties.
1531
1532   Note that ``tgt`` is not added as a dependency of the target this
1533   expression is evaluated on.
1534
1535 .. genex:: $<TARGET_LINKER_FILE_NAME:tgt>
1536
1537   Name of file used to link target ``tgt``.
1538
1539   Note that ``tgt`` is not added as a dependency of the target this
1540   expression is evaluated on (see policy :policy:`CMP0112`).
1541
1542 .. genex:: $<TARGET_LINKER_FILE_DIR:tgt>
1543
1544   Directory of file used to link target ``tgt``.
1545
1546   Note that ``tgt`` is not added as a dependency of the target this
1547   expression is evaluated on (see policy :policy:`CMP0112`).
1548
1549 .. genex:: $<TARGET_SONAME_FILE:tgt>
1550
1551   File with soname (``.so.3``) where ``tgt`` is the name of a target.
1552 .. genex:: $<TARGET_SONAME_FILE_NAME:tgt>
1553
1554   Name of file with soname (``.so.3``).
1555
1556   Note that ``tgt`` is not added as a dependency of the target this
1557   expression is evaluated on (see policy :policy:`CMP0112`).
1558
1559 .. genex:: $<TARGET_SONAME_FILE_DIR:tgt>
1560
1561   Directory of with soname (``.so.3``).
1562
1563   Note that ``tgt`` is not added as a dependency of the target this
1564   expression is evaluated on (see policy :policy:`CMP0112`).
1565
1566 .. genex:: $<TARGET_PDB_FILE:tgt>
1567
1568   .. versionadded:: 3.1
1569
1570   Full path to the linker generated program database file (.pdb)
1571   where ``tgt`` is the name of a target.
1572
1573   See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
1574   target properties and their configuration specific variants
1575   :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`.
1576
1577 .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt>
1578
1579   .. versionadded:: 3.15
1580
1581   Base name of the linker generated program database file (.pdb)
1582   where ``tgt`` is the name of a target.
1583
1584   The base name corresponds to the target PDB file name (see
1585   ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example,
1586   if target file name is ``base.pdb``, the base name is ``base``.
1587
1588   See also the :prop_tgt:`PDB_NAME` target property and its configuration
1589   specific variant :prop_tgt:`PDB_NAME_<CONFIG>`.
1590
1591   The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
1592   properties can also be considered.
1593
1594   Note that ``tgt`` is not added as a dependency of the target this
1595   expression is evaluated on.
1596
1597 .. genex:: $<TARGET_PDB_FILE_NAME:tgt>
1598
1599   .. versionadded:: 3.1
1600
1601   Name of the linker generated program database file (.pdb).
1602
1603   Note that ``tgt`` is not added as a dependency of the target this
1604   expression is evaluated on (see policy :policy:`CMP0112`).
1605
1606 .. genex:: $<TARGET_PDB_FILE_DIR:tgt>
1607
1608   .. versionadded:: 3.1
1609
1610   Directory of the linker generated program database file (.pdb).
1611
1612   Note that ``tgt`` is not added as a dependency of the target this
1613   expression is evaluated on (see policy :policy:`CMP0112`).
1614
1615 .. genex:: $<TARGET_BUNDLE_DIR:tgt>
1616
1617   .. versionadded:: 3.9
1618
1619   Full path to the bundle directory (``/path/to/my.app``,
1620   ``/path/to/my.framework``, or ``/path/to/my.bundle``),
1621   where ``tgt`` is the name of a target.
1622
1623   Note that ``tgt`` is not added as a dependency of the target this
1624   expression is evaluated on (see policy :policy:`CMP0112`).
1625
1626 .. genex:: $<TARGET_BUNDLE_DIR_NAME:tgt>
1627
1628   .. versionadded:: 3.24
1629
1630   Name of the bundle directory (``my.app``, ``my.framework``, or
1631   ``my.bundle``), where ``tgt`` is the name of a target.
1632
1633   Note that ``tgt`` is not added as a dependency of the target this
1634   expression is evaluated on (see policy :policy:`CMP0112`).
1635
1636 .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt>
1637
1638   .. versionadded:: 3.9
1639
1640   Full path to the bundle content directory where ``tgt`` is the name of a
1641   target.  For the macOS SDK it leads to ``/path/to/my.app/Contents``,
1642   ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``.
1643   For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``,
1644   ``/path/to/my.framework``, or ``/path/to/my.bundle`` due to the flat
1645   bundle structure.
1646
1647   Note that ``tgt`` is not added as a dependency of the target this
1648   expression is evaluated on (see policy :policy:`CMP0112`).
1649
1650 .. genex:: $<TARGET_RUNTIME_DLLS:tgt>
1651
1652   .. versionadded:: 3.21
1653
1654   List of DLLs that the target depends on at runtime. This is determined by
1655   the locations of all the ``SHARED`` targets in the target's transitive
1656   dependencies. Using this generator expression on targets other than
1657   executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error.
1658   **On non-DLL platforms, this expression always evaluates to an empty string**.
1659
1660   This generator expression can be used to copy all of the DLLs that a target
1661   depends on into its output directory in a ``POST_BUILD`` custom command. For
1662   example:
1663
1664   .. code-block:: cmake
1665
1666     find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
1667
1668     add_executable(exe main.c)
1669     target_link_libraries(exe PRIVATE foo::foo foo::bar)
1670     add_custom_command(TARGET exe POST_BUILD
1671       COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
1672       COMMAND_EXPAND_LISTS
1673     )
1674
1675   .. note::
1676
1677     :ref:`Imported Targets` are supported only if they know the location
1678     of their ``.dll`` files.  An imported ``SHARED`` library must have
1679     :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file.  See the
1680     :ref:`add_library imported libraries <add_library imported libraries>`
1681     section for details.  Many :ref:`Find Modules` produce imported targets
1682     with the ``UNKNOWN`` type and therefore will be ignored.
1683
1684
1685 Export And Install Expressions
1686 ------------------------------
1687
1688 .. genex:: $<INSTALL_INTERFACE:...>
1689
1690   Content of ``...`` when the property is exported using
1691   :command:`install(EXPORT)`, and empty otherwise.
1692
1693 .. genex:: $<BUILD_INTERFACE:...>
1694
1695   Content of ``...`` when the property is exported using :command:`export`, or
1696   when the target is used by another target in the same buildsystem. Expands to
1697   the empty string otherwise.
1698
1699 .. genex:: $<INSTALL_PREFIX>
1700
1701   Content of the install prefix when the target is exported via
1702   :command:`install(EXPORT)`, or when evaluated in the
1703   :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of
1704   :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise.
1705
1706 Multi-level Expression Evaluation
1707 ---------------------------------
1708
1709 .. genex:: $<GENEX_EVAL:expr>
1710
1711   .. versionadded:: 3.12
1712
1713   Content of ``expr`` evaluated as a generator expression in the current
1714   context. This enables consumption of generator expressions whose
1715   evaluation results itself in generator expressions.
1716
1717 .. genex:: $<TARGET_GENEX_EVAL:tgt,expr>
1718
1719   .. versionadded:: 3.12
1720
1721   Content of ``expr`` evaluated as a generator expression in the context of
1722   ``tgt`` target. This enables consumption of custom target properties that
1723   themselves contain generator expressions.
1724
1725   Having the capability to evaluate generator expressions is very useful when
1726   you want to manage custom properties supporting generator expressions.
1727   For example:
1728
1729   .. code-block:: cmake
1730
1731     add_library(foo ...)
1732
1733     set_property(TARGET foo PROPERTY
1734       CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
1735     )
1736
1737     add_custom_target(printFooKeys
1738       COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
1739     )
1740
1741   This naive implementation of the ``printFooKeys`` custom command is wrong
1742   because ``CUSTOM_KEYS`` target property is not evaluated and the content
1743   is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``).
1744
1745   To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is
1746   ``Debug``), it is required to evaluate the output of
1747   ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``:
1748
1749   .. code-block:: cmake
1750
1751     add_custom_target(printFooKeys
1752       COMMAND ${CMAKE_COMMAND} -E
1753         echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
1754     )
1755
1756 Escaped Characters
1757 ------------------
1758
1759 These expressions evaluate to specific string literals. Use them in place of
1760 the actual string literal where you need to prevent them from having their
1761 special meaning.
1762
1763 .. genex:: $<ANGLE-R>
1764
1765   A literal ``>``. Used for example to compare strings that contain a ``>``.
1766
1767 .. genex:: $<COMMA>
1768
1769   A literal ``,``. Used for example to compare strings which contain a ``,``.
1770
1771 .. genex:: $<SEMICOLON>
1772
1773   A literal ``;``. Used to prevent list expansion on an argument with ``;``.
1774
1775 Deprecated Expressions
1776 ----------------------
1777
1778 .. genex:: $<CONFIGURATION>
1779
1780   Configuration name. Deprecated since CMake 3.0. Use :genex:`CONFIG` instead.