Help: Restructure reference sections of genex manual

As part of the general restructuring, also move the notes of a more
introductory nature out of what was the "String-Valued Generator
Expressions" section and up to the dedicated Introduction. This gives
the reader a bit more of a foundation before they get to the heavier
detail of the reference section.

1 files changed, 866 insertions, 872 deletions

diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 18147b3..357a20c 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -12,7 +12,14 @@ Introduction
 
 Generator expressions are evaluated during build system generation to produce
 information specific to each build configuration.  They have the form
-``$<...>``.
+``$<...>``.  For example:
+
+.. code-block:: cmake
+
+  target_include_directories(tgt PRIVATE /opt/include/$<CXX_COMPILER_ID>)
+
+This would expand to ``/opt/include/GNU``, ``/opt/include/Clang``, etc.
+depending on the C++ compiler used.
 
 Generator expressions are allowed in the context of many target properties,
 such as :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`,
@@ -24,7 +31,17 @@ compiling, conditional include directories, and more.  The conditions may be
 based on the build configuration, target properties, platform information,
 or any other queryable information.
 
-Generator expressions can be nested, as shown in most of the examples below.
+Generator expressions can be nested:
+
+.. code-block:: cmake
+
+  target_compile_definitions(tgt PRIVATE
+    $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
+  )
+
+The above would expand to ``OLD_COMPILER`` if the
+:variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less
+than 4.2.0.
 
 Debugging
 =========
@@ -58,19 +75,38 @@ Generator Expression Reference
   ``string``, ``target``, etc.  This is to prevent an opportunity for those
   placeholders to be misinterpreted as generator expressions.
 
-.. _`Boolean Generator Expressions`:
+.. _`Conditional Generator Expressions`:
 
-Boolean Generator Expressions
------------------------------
+Conditional Expressions
+-----------------------
 
-Boolean expressions evaluate to either ``0`` or ``1``.
-They are typically used to construct the condition in a :ref:`conditional
-generator expression<Conditional Generator Expressions>`.
+A fundamental category of generator expressions relates to conditional logic.
+Two forms of conditional generator expressions are supported:
 
-Available boolean expressions are:
+.. genex:: $<condition:true_string>
 
-Logical Operators
-^^^^^^^^^^^^^^^^^
+  Evaluates to ``true_string`` if ``condition`` is ``1``, or an empty string
+  if ``condition`` evaluates to ``0``.  Any other value for ``condition``
+  results in an error.
+
+.. genex:: $<IF:condition,true_string,false_string>
+
+  .. versionadded:: 3.8
+
+  Evaluates to ``true_string`` if ``condition`` is ``1``, or ``false_string``
+  if ``condition`` is ``0``.  Any other value for ``condition`` results in an
+  error.
+
+Typically, the ``condition`` is itself a generator expression.  For instance,
+the following expression expands to ``DEBUG_MODE`` when the ``Debug``
+configuration is used, and the empty string for all other configurations:
+
+.. code-block:: cmake
+
+  $<$<CONFIG:Debug>:DEBUG_MODE>
+
+Boolean-like ``condition`` values other than ``1`` or ``0`` can be handled
+by wrapping them with the ``$<BOOL:...>`` generator expression:
 
 .. genex:: $<BOOL:string>
 
@@ -84,6 +120,21 @@ Logical Operators
 
   Otherwise evaluates to ``1``.
 
+The ``$<BOOL:...>`` generator expression is often used when a ``condition``
+is provided by a CMake variable:
+
+.. code-block:: cmake
+
+  $<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE>
+
+
+.. _`Boolean Generator Expressions`:
+
+Logical Operators
+-----------------
+
+The common boolean logic operators are supported:
+
 .. genex:: $<AND:conditions>
 
   where ``conditions`` is a comma-separated list of boolean expressions,
@@ -103,6 +154,16 @@ Logical Operators
   ``condition`` must be ``0`` or ``1``.  The result of the expression is
   ``0`` if ``condition`` is ``1``, else ``1``.
 
+.. _`Comparison Expressions`:
+
+Primary Comparison Expressions
+------------------------------
+
+CMake supports a variety of generator expressions that compare things.
+This section covers the primary and most widely used comparison types.
+Other more specific comparison types are documented in their own separate
+sections further below.
+
 String Comparisons
 ^^^^^^^^^^^^^^^^^^
 
@@ -111,23 +172,17 @@ String Comparisons
   ``1`` if ``string1`` and ``string2`` are equal, else ``0``.
   The comparison is case-sensitive.  For a case-insensitive comparison,
   combine with a :ref:`string transforming generator expression
-  <String Transforming Generator Expressions>`,
+  <String Transforming Generator Expressions>`.  For example, the following
+  evaluates to ``1`` if ``${foo}`` is any of ``BAR``, ``Bar``, ``bar``, etc.
 
   .. code-block:: cmake
 
-    $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...
+    $<STREQUAL:$<UPPER_CASE:${foo}>,BAR>
 
 .. genex:: $<EQUAL:value1,value2>
 
   ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``.
 
-.. genex:: $<IN_LIST:string,list>
-
-  .. versionadded:: 3.12
-
-  ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``.
-  It uses case-sensitive comparisons.
-
 Version Comparisons
 ^^^^^^^^^^^^^^^^^^^
 
@@ -155,6 +210,67 @@ Version Comparisons
 
   ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``.
 
+.. _`String Transforming Generator Expressions`:
+
+String Transformations
+----------------------
+
+.. genex:: $<LOWER_CASE:string>
+
+  Content of ``string`` converted to lower case.
+
+.. genex:: $<UPPER_CASE:string>
+
+  Content of ``string`` converted to upper case.
+
+.. genex:: $<MAKE_C_IDENTIFIER:...>
+
+  Content of ``...`` converted to a C identifier.  The conversion follows the
+  same behavior as :command:`string(MAKE_C_IDENTIFIER)`.
+
+List Expressions
+----------------
+
+.. genex:: $<IN_LIST:string,list>
+
+  .. versionadded:: 3.12
+
+  ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``.
+  It uses case-sensitive comparisons.
+
+.. genex:: $<JOIN:list,string>
+
+  Joins the list with the content of ``string`` inserted between each item.
+
+.. genex:: $<REMOVE_DUPLICATES:list>
+
+  .. versionadded:: 3.15
+
+  Removes duplicated items in the given ``list``. The relative order of items
+  is preserved, but if duplicates are encountered, only the first instance is
+  preserved.
+
+.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex>
+
+  .. versionadded:: 3.15
+
+  Includes or removes items from ``list`` that match the regular expression
+  ``regex``.
+
+Path Expressions
+----------------
+
+Most of the expressions in this section are closely associated with the
+:command:`cmake_path` command, providing the same capabilities, but in
+the form of a generator expression.
+
+For all generator expressions in this section, paths are expected to be in
+cmake-style format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>`
+generator expression can be used to convert a native path to a cmake-style
+one.
+
+.. _GenEx Path Comparisons:
+
 Path Comparisons
 ^^^^^^^^^^^^^^^^
 
@@ -173,16 +289,9 @@ Path Comparisons
 Path Queries
 ^^^^^^^^^^^^
 
-The ``$<PATH>`` generator expression offers the same capabilities as the
-:command:`cmake_path` command, for the :ref:`Query <Path Query>` options.
-
-For all ``$<PATH>`` generator expressions, paths are expected in cmake-style
-format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator
-expression can be used to convert a native path to a cmake-style one.
-
-The ``$<PATH>`` generator expression can also be used for path
-:ref:`Decomposition <GenEx Path Decomposition>` and
-:ref:`Transformations <GenEx Path Transformations>`.
+These expressions provide the generation-time capabilities equivalent to the
+:ref:`Query <Path Query>` options of the :command:`cmake_path` command.
+All paths are expected to be in cmake-style format.
 
 .. genex:: $<PATH:HAS_*,path>
 
@@ -228,209 +337,419 @@ The ``$<PATH>`` generator expression can also be used for path
 
   .. versionadded:: 3.24
 
-  Returns ``1`` if ``path`` is the prefix of ``input``,``0`` otherwise.
+  Returns ``1`` if ``path`` is the prefix of ``input``, ``0`` otherwise.
 
   When the ``NORMALIZE`` option is specified, ``path`` and ``input`` are
   :ref:`normalized <Normalization>` before the check.
 
-Variable Queries
-^^^^^^^^^^^^^^^^
+.. _GenEx Path Decomposition:
 
-.. genex:: $<TARGET_EXISTS:target>
+Path Decomposition
+^^^^^^^^^^^^^^^^^^
 
-  .. versionadded:: 3.12
+These expressions provide the generation-time capabilities equivalent to the
+:ref:`Decomposition <Path Decomposition>` options of the :command:`cmake_path`
+command.  All paths are expected to be in cmake-style format.
 
-  ``1`` if ``target`` exists, else ``0``.
+.. genex:: $<PATH:GET_*,...>
 
-.. genex:: $<CONFIG:cfgs>
+  .. versionadded:: 3.24
 
-  ``1`` if config is any one of the entries in comma-separated list
-  ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in
-  :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this
-  expression when it is evaluated on a property on an :prop_tgt:`IMPORTED`
-  target.
+  The following operations retrieve a different component or group of
+  components from a path. See :ref:`Path Structure And Terminology` for the
+  meaning of each path component.
 
-.. genex:: $<PLATFORM_ID:platform_ids>
+  ::
 
-  where ``platform_ids`` is a comma-separated list.
-  ``1`` if CMake's platform id matches any one of the entries in
-  ``platform_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_SYSTEM_NAME` variable.
+    $<PATH:GET_ROOT_NAME,path>
+    $<PATH:GET_ROOT_DIRECTORY,path>
+    $<PATH:GET_ROOT_PATH,path>
+    $<PATH:GET_FILENAME,path>
+    $<PATH:GET_EXTENSION[,LAST_ONLY],path>
+    $<PATH:GET_STEM[,LAST_ONLY],path>
+    $<PATH:GET_RELATIVE_PART,path>
+    $<PATH:GET_PARENT_PATH,path>
 
-.. genex:: $<C_COMPILER_ID:compiler_ids>
+  If a requested component is not present in the path, an empty string is
+  returned.
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the C compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+.. _GenEx Path Transformations:
 
-.. genex:: $<CXX_COMPILER_ID:compiler_ids>
+Path Transformations
+^^^^^^^^^^^^^^^^^^^^
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the CXX compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+These expressions provide the generation-time capabilities equivalent to the
+:ref:`Modification <Path Modification>` and :ref:`Generation <Path Generation>`
+options of the :command:`cmake_path` command.  All paths are expected to be
+in cmake-style format.
 
-.. genex:: $<CUDA_COMPILER_ID:compiler_ids>
+.. _GenEx PATH-CMAKE_PATH:
 
-  .. versionadded:: 3.15
+.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path>
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the CUDA compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+  .. versionadded:: 3.24
 
-.. genex:: $<OBJC_COMPILER_ID:compiler_ids>
+  Returns ``path``. If ``path`` is a native path, it is converted into a
+  cmake-style path with forward-slashes (``/``). On Windows, the long filename
+  marker is taken into account.
 
-  .. versionadded:: 3.16
+  When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
+  <Normalization>` after the conversion.
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the Objective-C compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+.. genex:: $<PATH:APPEND,path,input,...>
 
-.. genex:: $<OBJCXX_COMPILER_ID:compiler_ids>
+  .. versionadded:: 3.24
 
-  .. versionadded:: 3.16
+  Returns all the ``input`` arguments appended to ``path`` using ``/`` as the
+  ``directory-separator``. Depending on the ``input``, the value of ``path``
+  may be discarded.
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the Objective-C++ compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+  See :ref:`cmake_path(APPEND) <APPEND>` for more details.
 
-.. genex:: $<Fortran_COMPILER_ID:compiler_ids>
+.. genex:: $<PATH:REMOVE_FILENAME,path>
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the Fortran compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+  .. versionadded:: 3.24
 
-.. genex:: $<HIP_COMPILER_ID:compiler_ids>
+  Returns ``path`` with filename component (as returned by
+  ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing
+  ``directory-separator`` is left alone, if present.
 
-  .. versionadded:: 3.21
+  See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details.
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the HIP compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+.. genex:: $<PATH:REPLACE_FILENAME,path,input>
 
-.. genex:: $<ISPC_COMPILER_ID:compiler_ids>
+  .. versionadded:: 3.24
 
-  .. versionadded:: 3.19
+  Returns ``path`` with the filename component replaced by ``input``. If
+  ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns
+  ``0``), ``path`` is unchanged.
 
-  where ``compiler_ids`` is a comma-separated list.
-  ``1`` if CMake's compiler id of the ISPC compiler matches any one
-  of the entries in ``compiler_ids``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+  See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details.
+
+.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path>
+
+  .. versionadded:: 3.24
+
+  Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any.
+
+  See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details.
+
+.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path>
+
+  .. versionadded:: 3.24
+
+  Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by
+  ``input``, if any.
+
+  See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details.
+
+.. genex:: $<PATH:NORMAL_PATH,path>
+
+  .. versionadded:: 3.24
+
+  Returns ``path`` normalized according to the steps described in
+  :ref:`Normalization`.
+
+.. genex:: $<PATH:RELATIVE_PATH,path,base_directory>
+
+  .. versionadded:: 3.24
+
+  Returns ``path``, modified to make it relative to the ``base_directory``
+  argument.
+
+  See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more
+  details.
+
+.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory>
+
+  .. versionadded:: 3.24
+
+  Returns ``path`` as absolute. If ``path`` is a relative path
+  (``$<PATH:IS_RELATIVE>`` returns ``1``), it is evaluated relative to the
+  given base directory specified by ``base_directory`` argument.
+
+  When the ``NORMALIZE`` option is specified, the path is
+  :ref:`normalized <Normalization>` after the path computation.
+
+  See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details.
+
+Shell Paths
+^^^^^^^^^^^
+
+.. genex:: $<SHELL_PATH:...>
+
+  .. versionadded:: 3.4
+
+  Content of ``...`` converted to shell path style. For example, slashes are
+  converted to backslashes in Windows shells and drive letters are converted
+  to posix paths in MSYS shells. The ``...`` must be an absolute path.
+
+  .. versionadded:: 3.14
+    The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>`
+    of paths, in which case each path is converted individually and a result
+    list is generated using the shell path separator (``:`` on POSIX and
+    ``;`` on Windows).  Be sure to enclose the argument containing this genex
+    in double quotes in CMake source code so that ``;`` does not split arguments.
+
+Configuration Expressions
+-------------------------
+
+.. genex:: $<CONFIG>
+
+  Configuration name. Use this instead of the deprecated :genex:`CONFIGURATION`
+  generator expression.
+
+.. genex:: $<CONFIG:cfgs>
+
+  ``1`` if config is any one of the entries in comma-separated list
+  ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in
+  :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this
+  expression when it is evaluated on a property of an :prop_tgt:`IMPORTED`
+  target.
+
+.. genex:: $<OUTPUT_CONFIG:...>
+
+  .. versionadded:: 3.20
+
+  Only valid in :command:`add_custom_command` and :command:`add_custom_target`
+  as the outer-most generator expression in an argument.
+  With the :generator:`Ninja Multi-Config` generator, generator expressions
+  in ``...`` are evaluated using the custom command's "output config".
+  With other generators, the content of ``...`` is evaluated normally.
+
+.. genex:: $<COMMAND_CONFIG:...>
+
+  .. versionadded:: 3.20
+
+  Only valid in :command:`add_custom_command` and :command:`add_custom_target`
+  as the outer-most generator expression in an argument.
+  With the :generator:`Ninja Multi-Config` generator, generator expressions
+  in ``...`` are evaluated using the custom command's "command config".
+  With other generators, the content of ``...`` is evaluated normally.
+
+Toolchain And Language Expressions
+----------------------------------
+
+Platform
+^^^^^^^^
+
+.. genex:: $<PLATFORM_ID>
+
+  The current system's CMake platform id.
+  See also the :variable:`CMAKE_SYSTEM_NAME` variable.
+
+.. genex:: $<PLATFORM_ID:platform_ids>
+
+  where ``platform_ids`` is a comma-separated list.
+  ``1`` if CMake's platform id matches any one of the entries in
+  ``platform_ids``, otherwise ``0``.
+  See also the :variable:`CMAKE_SYSTEM_NAME` variable.
+
+Compiler Version
+^^^^^^^^^^^^^^^^
+
+See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable, which is
+closely related to the expressions in this sub-section.
+
+.. genex:: $<C_COMPILER_VERSION>
+
+  The version of the C compiler used.
 
 .. genex:: $<C_COMPILER_VERSION:version>
 
   ``1`` if the version of the C compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<CXX_COMPILER_VERSION>
+
+  The version of the CXX compiler used.
 
 .. genex:: $<CXX_COMPILER_VERSION:version>
 
   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<CUDA_COMPILER_VERSION>
+
+  .. versionadded:: 3.15
+
+  The version of the CUDA compiler used.
 
 .. genex:: $<CUDA_COMPILER_VERSION:version>
 
   .. versionadded:: 3.15
 
   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<OBJC_COMPILER_VERSION>
+
+  .. versionadded:: 3.16
+
+  The version of the OBJC compiler used.
 
 .. genex:: $<OBJC_COMPILER_VERSION:version>
 
   .. versionadded:: 3.16
 
   ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<OBJCXX_COMPILER_VERSION>
+
+  .. versionadded:: 3.16
+
+  The version of the OBJCXX compiler used.
 
 .. genex:: $<OBJCXX_COMPILER_VERSION:version>
 
   .. versionadded:: 3.16
 
   ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<Fortran_COMPILER_VERSION>
+
+  The version of the Fortran compiler used.
 
 .. genex:: $<Fortran_COMPILER_VERSION:version>
 
   ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<HIP_COMPILER_VERSION>
+
+  .. versionadded:: 3.21
+
+  The version of the HIP compiler used.
 
 .. genex:: $<HIP_COMPILER_VERSION:version>
 
   .. versionadded:: 3.21
 
   ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+
+.. genex:: $<ISPC_COMPILER_VERSION>
+
+  .. versionadded:: 3.19
+
+  The version of the ISPC compiler used.
 
 .. genex:: $<ISPC_COMPILER_VERSION:version>
 
   .. versionadded:: 3.19
 
   ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
 
-.. genex:: $<TARGET_POLICY:policy>
+Compiler Language And ID
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-  ``1`` if the ``policy`` was NEW when the 'head' target was created,
-  else ``0``.  If the ``policy`` was not set, the warning message for the policy
-  will be emitted. This generator expression only works for a subset of
-  policies.
+See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable, which is closely
+related to most of the expressions in this sub-section.
 
-.. genex:: $<COMPILE_FEATURES:features>
+.. genex:: $<C_COMPILER_ID>
 
-  .. versionadded:: 3.1
+  CMake's compiler id of the C compiler used.
 
-  where ``features`` is a comma-separated list.
-  Evaluates to ``1`` if all of the ``features`` are available for the 'head'
-  target, and ``0`` otherwise. If this expression is used while evaluating
-  the link implementation of a target and if any dependency transitively
-  increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
-  for the 'head' target, an error is reported.  See the
-  :manual:`cmake-compile-features(7)` manual for information on
-  compile features and a list of supported compilers.
+.. genex:: $<C_COMPILER_ID:compiler_ids>
 
-.. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids>
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the C compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<CXX_COMPILER_ID>
+
+  CMake's compiler id of the CXX compiler used.
+
+.. genex:: $<CXX_COMPILER_ID:compiler_ids>
+
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the CXX compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<CUDA_COMPILER_ID>
 
   .. versionadded:: 3.15
 
-  ``1`` when the language used for compilation unit matches ``language`` and
-  CMake's compiler id of the ``language`` compiler matches any one of the
-  entries in ``compiler_ids``, otherwise ``0``. This expression is a short form
-  for the combination of ``$<COMPILE_LANGUAGE:language>`` and
-  ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
-  compile options, compile definitions, and include directories for source files of a
-  particular language and compiler combination in a target. For example:
+  CMake's compiler id of the CUDA compiler used.
 
-  .. code-block:: cmake
+.. genex:: $<CUDA_COMPILER_ID:compiler_ids>
 
-    add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
-    target_compile_definitions(myapp
-      PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
-              $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
-              $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
-    )
+  .. versionadded:: 3.15
 
-  This specifies the use of different compile definitions based on both
-  the compiler id and compilation language. This example will have a
-  ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX
-  compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler.
-  Likewise when the C compiler is Clang it will only see the  ``COMPILING_C_WITH_CLANG``
-  definition.
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the CUDA compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
 
-  Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic
-  would be expressed as:
+.. genex:: $<OBJC_COMPILER_ID>
 
-  .. code-block:: cmake
+  .. versionadded:: 3.16
 
-    target_compile_definitions(myapp
-      PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
-              $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
-              $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
-    )
+  CMake's compiler id of the OBJC compiler used.
+
+.. genex:: $<OBJC_COMPILER_ID:compiler_ids>
+
+  .. versionadded:: 3.16
+
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the Objective-C compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<OBJCXX_COMPILER_ID>
+
+  .. versionadded:: 3.16
+
+  CMake's compiler id of the OBJCXX compiler used.
+
+.. genex:: $<OBJCXX_COMPILER_ID:compiler_ids>
+
+  .. versionadded:: 3.16
+
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the Objective-C++ compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<Fortran_COMPILER_ID>
+
+  CMake's compiler id of the Fortran compiler used.
+
+.. genex:: $<Fortran_COMPILER_ID:compiler_ids>
+
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the Fortran compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<HIP_COMPILER_ID>
+
+  .. versionadded:: 3.21
+
+  CMake's compiler id of the HIP compiler used.
+
+.. genex:: $<HIP_COMPILER_ID:compiler_ids>
+
+  .. versionadded:: 3.21
+
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the HIP compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<ISPC_COMPILER_ID>
+
+  .. versionadded:: 3.19
+
+  CMake's compiler id of the ISPC compiler used.
+
+.. genex:: $<ISPC_COMPILER_ID:compiler_ids>
+
+  .. versionadded:: 3.19
+
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if CMake's compiler id of the ISPC compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+
+.. genex:: $<COMPILE_LANGUAGE>
+
+  .. versionadded:: 3.3
+
+  The compile language of source files when evaluating compile options.
+  See :ref:`the related boolean expression
+  <Boolean COMPILE_LANGUAGE Generator Expression>`
+  ``$<COMPILE_LANGUAGE:language>``
+  for notes about the portability of this generator expression.
 
 .. _`Boolean COMPILE_LANGUAGE Generator Expression`:
 
@@ -440,7 +759,7 @@ Variable Queries
 
   ``1`` when the language used for compilation unit matches any of the entries
   in ``languages``, otherwise ``0``.  This expression may be used to specify
-  compile options, compile definitions, and include directories for source files of a
+  compile options, compile definitions, and include directories for source
   files of a particular language in a target. For example:
 
   .. code-block:: cmake
@@ -480,47 +799,80 @@ Variable Queries
     add_executable(myapp main.cpp)
     target_link_libraries(myapp myapp_c myapp_cxx)
 
-.. genex:: $<LINK_LANG_AND_ID:language,compiler_ids>
+.. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids>
 
-  .. versionadded:: 3.18
+  .. versionadded:: 3.15
 
-  ``1`` when the language used for link step matches ``language`` and the
-  CMake's compiler id of the language linker matches any one of the entries
-  in ``compiler_ids``, otherwise ``0``. This expression is a short form for the
-  combination of ``$<LINK_LANGUAGE:language>`` and
+  ``1`` when the language used for compilation unit matches ``language`` and
+  CMake's compiler id of the ``language`` compiler matches any one of the
+  entries in ``compiler_ids``, otherwise ``0``. This expression is a short form
+  for the combination of ``$<COMPILE_LANGUAGE:language>`` and
   ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
-  link libraries, link options, link directories and link dependencies of a
-  particular language and linker combination in a target. For example:
+  compile options, compile definitions, and include directories for source
+  files of a particular language and compiler combination in a target.
+  For example:
 
   .. code-block:: cmake
 
-    add_library(libC_Clang ...)
-    add_library(libCXX_Clang ...)
-    add_library(libC_Intel ...)
-    add_library(libCXX_Intel ...)
+    add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
+    target_compile_definitions(myapp
+      PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
+              $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
+              $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
+    )
 
-    add_executable(myapp main.c)
-    if (CXX_CONFIG)
-      target_sources(myapp PRIVATE file.cxx)
-    endif()
-    target_link_libraries(myapp
-      PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
-              $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
-              $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
-              $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
+  This specifies the use of different compile definitions based on both
+  the compiler id and compilation language. This example will have a
+  ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX
+  compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler.
+  Likewise, when the C compiler is Clang, it will only see the
+  ``COMPILING_C_WITH_CLANG`` definition.
 
-  This specifies the use of different link libraries based on both the
-  compiler id and link language. This example will have target ``libCXX_Clang``
-  as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX``
-  linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker.
-  Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target
-  ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when
-  ``Intel`` is the ``C`` linker.
+  Without the ``COMPILE_LANG_AND_ID`` generator expression, the same logic
+  would be expressed as:
+
+  .. code-block:: cmake
+
+    target_compile_definitions(myapp
+      PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
+              $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
+              $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
+    )
+
+Compile Features
+^^^^^^^^^^^^^^^^
+
+.. genex:: $<COMPILE_FEATURES:features>
+
+  .. versionadded:: 3.1
+
+  where ``features`` is a comma-separated list.
+  Evaluates to ``1`` if all of the ``features`` are available for the 'head'
+  target, and ``0`` otherwise. If this expression is used while evaluating
+  the link implementation of a target and if any dependency transitively
+  increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
+  for the 'head' target, an error is reported.  See the
+  :manual:`cmake-compile-features(7)` manual for information on
+  compile features and a list of supported compilers.
+
+Linker Language And ID
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. genex:: $<LINK_LANGUAGE>
+
+  .. versionadded:: 3.18
+
+  The link language of the target when evaluating link options.
+  See :ref:`the related boolean expression
+  <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:languages>``
+  for notes about the portability of this generator expression.
+
+  .. note::
+
+    This generator expression is not supported by the link libraries
+    properties to avoid side-effects due to the double evaluation of
+    these properties.
 
-  See :ref:`the note related to
-  <Constraints LINK_LANGUAGE Generator Expression>`
-  ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
-  generator expression.
 
 .. _`Boolean LINK_LANGUAGE Generator Expression`:
 
@@ -589,489 +941,391 @@ Variable Queries
     evaluation will give ``C`` as link language, so the second pass will
     correctly add target ``libother`` as link dependency.
 
-String-Valued Generator Expressions
------------------------------------
-
-These expressions expand to some string.
-For example,
-
-.. code-block:: cmake
-
-  include_directories(/usr/include/$<CXX_COMPILER_ID>/)
-
-expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on
-the compiler identifier.
-
-String-valued expressions may also be combined with other expressions.
-Here an example for a string-valued expression within a boolean expressions
-within a conditional expression:
-
-.. code-block:: cmake
-
-  $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
-
-expands to ``OLD_COMPILER`` if the
-:variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less
-than 4.2.0.
-
-And here two nested string-valued expressions:
-
-.. code-block:: cmake
-
-  -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>
-
-generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target
-property with each entry preceded by ``-I``.
-
-Expanding on the previous example, if one first wants to check if the
-``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to
-introduce a helper variable to keep the code readable:
-
-.. code-block:: cmake
-
-  set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
-  $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>
-
-The following string-valued generator expressions are available:
-
-Escaped Characters
-^^^^^^^^^^^^^^^^^^
-
-String literals to escape the special meaning a character would otherwise have:
-
-.. genex:: $<ANGLE-R>
-
-  A literal ``>``. Used for example to compare strings that contain a ``>``.
-
-.. genex:: $<COMMA>
-
-  A literal ``,``. Used for example to compare strings which contain a ``,``.
-
-.. genex:: $<SEMICOLON>
-
-  A literal ``;``. Used to prevent list expansion on an argument with ``;``.
-
-.. _`Conditional Generator Expressions`:
-
-Conditional Expressions
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Conditional generator expressions depend on a boolean condition
-that must be ``0`` or ``1``.
-
-.. genex:: $<condition:true_string>
-
-  Evaluates to ``true_string`` if ``condition`` is ``1``.
-  Otherwise evaluates to the empty string.
-
-.. genex:: $<IF:condition,true_string,false_string>
-
-  .. versionadded:: 3.8
-
-  Evaluates to ``true_string`` if ``condition`` is ``1``.
-  Otherwise evaluates to ``false_string``.
-
-Typically, the ``condition`` is a :ref:`boolean generator expression
-<Boolean Generator Expressions>`.  For instance,
-
-.. code-block:: cmake
-
-  $<$<CONFIG:Debug>:DEBUG_MODE>
-
-expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and
-otherwise expands to the empty string.
-
-.. _`String Transforming Generator Expressions`:
-
-String Transformations
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. genex:: $<JOIN:list,string>
-
-  Joins the list with the content of ``string``.
-
-.. genex:: $<REMOVE_DUPLICATES:list>
-
-  .. versionadded:: 3.15
-
-  Removes duplicated items in the given ``list``. The relative order of items
-  is preserved, but if duplicates are encountered, only the first instance is
-  preserved.
-
-.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex>
-
-  .. versionadded:: 3.15
-
-  Includes or removes items from ``list`` that match the regular expression ``regex``.
-
-.. genex:: $<LOWER_CASE:string>
-
-  Content of ``string`` converted to lower case.
-
-.. genex:: $<UPPER_CASE:string>
-
-  Content of ``string`` converted to upper case.
-
-.. genex:: $<GENEX_EVAL:expr>
-
-  .. versionadded:: 3.12
-
-  Content of ``expr`` evaluated as a generator expression in the current
-  context. This enables consumption of generator expressions whose
-  evaluation results itself in generator expressions.
-
-.. genex:: $<TARGET_GENEX_EVAL:tgt,expr>
-
-  .. versionadded:: 3.12
-
-  Content of ``expr`` evaluated as a generator expression in the context of
-  ``tgt`` target. This enables consumption of custom target properties that
-  themselves contain generator expressions.
-
-  Having the capability to evaluate generator expressions is very useful when
-  you want to manage custom properties supporting generator expressions.
-  For example:
-
-  .. code-block:: cmake
-
-    add_library(foo ...)
-
-    set_property(TARGET foo PROPERTY
-      CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
-    )
-
-    add_custom_target(printFooKeys
-      COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
-    )
+.. genex:: $<LINK_LANG_AND_ID:language,compiler_ids>
 
-  This naive implementation of the ``printFooKeys`` custom command is wrong
-  because ``CUSTOM_KEYS`` target property is not evaluated and the content
-  is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``).
+  .. versionadded:: 3.18
 
-  To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is
-  ``Debug``), it is required to evaluate the output of
-  ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``:
+  ``1`` when the language used for link step matches ``language`` and the
+  CMake's compiler id of the language linker matches any one of the entries
+  in ``compiler_ids``, otherwise ``0``. This expression is a short form for the
+  combination of ``$<LINK_LANGUAGE:language>`` and
+  ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
+  link libraries, link options, link directories and link dependencies of a
+  particular language and linker combination in a target. For example:
 
   .. code-block:: cmake
 
-    add_custom_target(printFooKeys
-      COMMAND ${CMAKE_COMMAND} -E
-        echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
-    )
-
-.. _GenEx Path Decomposition:
-
-Path Decomposition
-^^^^^^^^^^^^^^^^^^
-
-The ``$<PATH>`` generator expression offers the same capabilities as the
-:command:`cmake_path` command, for the
-:ref:`Decomposition <Path Decomposition>` options.
-
-For all ``$<PATH>`` generator expressions, paths are expected in cmake-style
-format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator
-expression can be used to convert a native path to a cmake-style one.
-
-The ``$<PATH>`` generator expression can also be used for path
-:ref:`Queries <GenEx Path Queries>` and
-:ref:`Transformations <GenEx Path Transformations>`.
-
-.. genex:: $<PATH:GET_*,...>
-
-  .. versionadded:: 3.24
-
-  The following operations retrieve a different component or group of
-  components from a path. See :ref:`Path Structure And Terminology` for the
-  meaning of each path component.
-
-  ::
-
-    $<PATH:GET_ROOT_NAME,path>
-    $<PATH:GET_ROOT_DIRECTORY,path>
-    $<PATH:GET_ROOT_PATH,path>
-    $<PATH:GET_FILENAME,path>
-    $<PATH:GET_EXTENSION[,LAST_ONLY],path>
-    $<PATH:GET_STEM[,LAST_ONLY],path>
-    $<PATH:GET_RELATIVE_PART,path>
-    $<PATH:GET_PARENT_PATH,path>
-
-  If a requested component is not present in the path, an empty string is
-  returned.
-
-.. _GenEx Path Transformations:
-
-Path Transformations
-^^^^^^^^^^^^^^^^^^^^
-
-The ``$<PATH>`` generator expression offers the same capabilities as the
-:command:`cmake_path` command, for the
-:ref:`Modification <Path Modification>` and
-:ref:`Generation <Path Generation>` options.
-
-For all ``$<PATH>`` generator expressions, paths are expected in cmake-style
-format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator
-expression can be used to convert a native path to a cmake-style one.
-
-The ``$<PATH>`` generator expression can also be used for path
-:ref:`Queries <GenEx Path Queries>` and
-:ref:`Decomposition <GenEx Path Decomposition>`.
-
-.. _GenEx PATH-CMAKE_PATH:
+    add_library(libC_Clang ...)
+    add_library(libCXX_Clang ...)
+    add_library(libC_Intel ...)
+    add_library(libCXX_Intel ...)
 
-.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path>
+    add_executable(myapp main.c)
+    if (CXX_CONFIG)
+      target_sources(myapp PRIVATE file.cxx)
+    endif()
+    target_link_libraries(myapp
+      PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
+              $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
+              $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
+              $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
 
-  .. versionadded:: 3.24
+  This specifies the use of different link libraries based on both the
+  compiler id and link language. This example will have target ``libCXX_Clang``
+  as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX``
+  linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker.
+  Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target
+  ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when
+  ``Intel`` is the ``C`` linker.
 
-  Returns ``path``. If ``path`` is a native path, it is converted into a
-  cmake-style path with forward-slashes (``/``). On Windows, the long filename
-  marker is taken into account.
+  See :ref:`the note related to
+  <Constraints LINK_LANGUAGE Generator Expression>`
+  ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
+  generator expression.
 
-  When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
-  <Normalization>` after the conversion.
+Link Features
+^^^^^^^^^^^^^
 
-.. genex:: $<PATH:APPEND,path,input,...>
+.. genex:: $<LINK_LIBRARY:feature,library-list>
 
   .. versionadded:: 3.24
 
-  Returns all the ``input`` arguments appended to ``path`` using ``/`` as the
-  ``directory-separator``. Depending on the ``input``, the value of ``path``
-  may be discarded.
+  Specify a set of libraries to link to a target, along with a ``feature``
+  which provides details about *how* they should be linked.  For example:
 
-  See :ref:`cmake_path(APPEND) <APPEND>` for more details.
+  .. code-block:: cmake
 
-.. genex:: $<PATH:REMOVE_FILENAME,path>
+    add_library(lib1 STATIC ...)
+    add_library(lib2 ...)
+    target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")
 
-  .. versionadded:: 3.24
+  This specifies that ``lib2`` should link to ``lib1`` and use the
+  ``WHOLE_ARCHIVE`` feature when doing so.
 
-  Returns ``path`` with filename component (as returned by
-  ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing
-  ``directory-separator`` is left alone, if present.
+  Feature names are case-sensitive and may only contain letters, numbers and
+  underscores.  Feature names defined in all uppercase are reserved for CMake's
+  own built-in features.  The pre-defined built-in library features are:
 
-  See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details.
+  .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
 
-.. genex:: $<PATH:REPLACE_FILENAME,path,input>
+  Built-in and custom library features are defined in terms of the following
+  variables:
 
-  .. versionadded:: 3.24
+  * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
+  * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
+  * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
+  * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`
 
-  Returns ``path`` with the filename component replaced by ``input``. If
-  ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns
-  ``0``), ``path`` is unchanged.
+  The value used for each of these variables is the value as set at the end of
+  the directory scope in which the target was created.  The usage is as follows:
 
-  See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details.
+  1. If the language-specific
+     :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable
+     is true, the ``feature`` must be defined by the corresponding
+     :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable.
+  2. If no language-specific ``feature`` is supported, then the
+     :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable must be
+     true and the ``feature`` must be defined by the corresponding
+     :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable.
 
-.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path>
+  The following limitations should be noted:
 
-  .. versionadded:: 3.24
+  * The ``library-list`` can specify CMake targets or libraries.
+    Any CMake target of type :ref:`OBJECT <Object Libraries>`
+    or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
+    of the expression and instead be linked in the standard way.
 
-  Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any.
+  * The ``$<LINK_LIBRARY:...>`` generator expression can only be used to
+    specify link libraries.  In practice, this means it can appear in the
+    :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
+    :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`  target properties, and be
+    specified in :command:`target_link_libraries` and :command:`link_libraries`
+    commands.
 
-  See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details.
+  * If a ``$<LINK_LIBRARY:...>`` generator expression appears in the
+    :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
+    included in the imported target generated by a :command:`install(EXPORT)`
+    command.  It is the responsibility of the environment consuming this
+    import to define the link feature used by this expression.
 
-.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path>
+  * Each target or library involved in the link step must have at most only
+    one kind of library feature.  The absence of a feature is also incompatible
+    with all other features.  For example:
 
-  .. versionadded:: 3.24
+    .. code-block:: cmake
 
-  Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by
-  ``input``, if any.
+      add_library(lib1 ...)
+      add_library(lib2 ...)
+      add_library(lib3 ...)
 
-  See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details.
+      # lib1 will be associated with feature1
+      target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
 
-.. genex:: $<PATH:NORMAL_PATH,path>
+      # lib1 is being linked with no feature here. This conflicts with the
+      # use of feature1 in the line above and would result in an error.
+      target_link_libraries(lib3 PRIVATE lib1 lib2)
 
-  .. versionadded:: 3.24
+    Where it isn't possible to use the same feature throughout a build for a
+    given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+    :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be
+    used to resolve such incompatibilities.
 
-  Returns ``path`` normalized according to the steps described in
-  :ref:`Normalization`.
+  * The ``$<LINK_LIBRARY:...>`` generator expression does not guarantee
+    that the list of specified targets and libraries will be kept grouped
+    together.  To manage constructs like ``--start-group`` and ``--end-group``,
+    as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP`
+    generator expression instead.
 
-.. genex:: $<PATH:RELATIVE_PATH,path,base_directory>
+.. genex:: $<LINK_GROUP:feature,library-list>
 
   .. versionadded:: 3.24
 
-  Returns ``path``, modified to make it relative to the ``base_directory``
-  argument.
+  Specify a group of libraries to link to a target, along with a ``feature``
+  which defines how that group should be linked.  For example:
 
-  See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more
-  details.
+  .. code-block:: cmake
 
-.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory>
+    add_library(lib1 STATIC ...)
+    add_library(lib2 ...)
+    target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
 
-  .. versionadded:: 3.24
+  This specifies that ``lib2`` should link to ``lib1`` and ``external``, and
+  that both of those two libraries should be included on the linker command
+  line according to the definition of the ``RESCAN`` feature.
 
-  Returns ``path`` as absolute. If ``path`` is a relative path
-  (``$<PATH:IS_RELATIVE>`` returns ``1``), it is evaluated relative to the
-  given base directory specified by ``base_directory`` argument.
+  Feature names are case-sensitive and may only contain letters, numbers and
+  underscores.  Feature names defined in all uppercase are reserved for CMake's
+  own built-in features.  Currently, there is only one pre-defined built-in
+  group feature:
 
-  When the ``NORMALIZE`` option is specified, the path is
-  :ref:`normalized <Normalization>` after the path computation.
+  .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt
 
-  See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details.
+  Built-in and custom group features are defined in terms of the following
+  variables:
 
-Variable Queries
-^^^^^^^^^^^^^^^^
+  * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
+  * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`
+  * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
+  * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`
 
-.. genex:: $<CONFIG>
+  The value used for each of these variables is the value as set at the end of
+  the directory scope in which the target was created.  The usage is as follows:
 
-  Configuration name.
+  1. If the language-specific
+     :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable
+     is true, the ``feature`` must be defined by the corresponding
+     :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable.
+  2. If no language-specific ``feature`` is supported, then the
+     :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable must be
+     true and the ``feature`` must be defined by the corresponding
+     :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable.
 
-.. genex:: $<CONFIGURATION>
+  The ``LINK_GROUP`` generator expression is compatible with the
+  :genex:`LINK_LIBRARY` generator expression. The libraries involved in a
+  group can be specified using the :genex:`LINK_LIBRARY` generator expression.
 
-  Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead.
+  Each target or external library involved in the link step is allowed to be
+  part of multiple groups, but only if all the groups involved specify the
+  same ``feature``.  Such groups will not be merged on the linker command line,
+  the individual groups will still be preserved.  Mixing different group
+  features for the same target or library is forbidden.
 
-.. genex:: $<PLATFORM_ID>
+  .. code-block:: cmake
 
-  The current system's CMake platform id.
-  See also the :variable:`CMAKE_SYSTEM_NAME` variable.
+    add_library(lib1 ...)
+    add_library(lib2 ...)
+    add_library(lib3 ...)
+    add_library(lib4 ...)
+    add_library(lib5 ...)
 
-.. genex:: $<C_COMPILER_ID>
+    target_link_libraries(lib3 PUBLIC  "$<LINK_GROUP:feature1,lib1,lib2>")
+    target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
+    # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
+    # Both groups specify the same feature, so this is fine.
 
-  CMake's compiler id of the C compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+    target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
+    # An error will be raised here because both lib1 and lib3 are part of two
+    # groups with different features.
 
-.. genex:: $<CXX_COMPILER_ID>
+  When a target or an external library is involved in the link step as part of
+  a group and also as not part of any group, any occurrence of the non-group
+  link item will be replaced by the groups it belongs to.
 
-  CMake's compiler id of the CXX compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+  .. code-block:: cmake
 
-.. genex:: $<CUDA_COMPILER_ID>
+    add_library(lib1 ...)
+    add_library(lib2 ...)
+    add_library(lib3 ...)
+    add_library(lib4 ...)
 
-  .. versionadded:: 3.15
+    target_link_libraries(lib3 PUBLIC lib1)
 
-  CMake's compiler id of the CUDA compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+    target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
+    # lib4 will only be linked with lib3 and the group {lib1,lib2}
 
-.. genex:: $<OBJC_COMPILER_ID>
+  Because ``lib1`` is part of the group defined for ``lib4``, that group then
+  gets applied back to the use of ``lib1`` for ``lib3``.  The end result will
+  be as though the linking relationship for ``lib3`` had been specified as:
 
-  .. versionadded:: 3.16
+  .. code-block:: cmake
 
-  CMake's compiler id of the OBJC compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+    target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
 
-.. genex:: $<OBJCXX_COMPILER_ID>
+  Be aware that the precedence of the group over the non-group link item can
+  result in circular dependencies between groups.  If this occurs, a fatal
+  error is raised because circular dependencies are not allowed for groups.
 
-  .. versionadded:: 3.16
+  .. code-block:: cmake
 
-  CMake's compiler id of the OBJCXX compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+    add_library(lib1A ...)
+    add_library(lib1B ...)
+    add_library(lib2A ...)
+    add_library(lib2B ...)
+    add_library(lib3 ...)
 
-.. genex:: $<Fortran_COMPILER_ID>
+    # Non-group linking relationships, these are non-circular so far
+    target_link_libraries(lib1A PUBLIC lib2A)
+    target_link_libraries(lib2B PUBLIC lib1B)
 
-  CMake's compiler id of the Fortran compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+    # The addition of these groups creates circular dependencies
+    target_link_libraries(lib3 PRIVATE
+      "$<LINK_GROUP:feat,lib1A,lib1B>"
+      "$<LINK_GROUP:feat,lib2A,lib2B>"
+    )
 
-.. genex:: $<HIP_COMPILER_ID>
+  Because of the groups defined for ``lib3``, the linking relationships for
+  ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of:
 
-  .. versionadded:: 3.21
+  .. code-block:: cmake
 
-  CMake's compiler id of the HIP compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+    target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
+    target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
 
-.. genex:: $<ISPC_COMPILER_ID>
+  This creates a circular dependency between groups:
+  ``lib1A --> lib2B --> lib1A``.
 
-  .. versionadded:: 3.19
+  The following limitations should also be noted:
 
-  CMake's compiler id of the ISPC compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+  * The ``library-list`` can specify CMake targets or libraries.
+    Any CMake target of type :ref:`OBJECT <Object Libraries>`
+    or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
+    of the expression and instead be linked in the standard way.
 
-.. genex:: $<C_COMPILER_VERSION>
+  * The ``$<LINK_GROUP:...>`` generator expression can only be used to
+    specify link libraries.  In practice, this means it can appear in the
+    :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and
+    :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be
+    specified in :command:`target_link_libraries` and :command:`link_libraries`
+    commands.
 
-  The version of the C compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+  * If a ``$<LINK_GROUP:...>`` generator expression appears in the
+    :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
+    included in the imported target generated by a :command:`install(EXPORT)`
+    command.  It is the responsibility of the environment consuming this
+    import to define the link feature used by this expression.
 
-.. genex:: $<CXX_COMPILER_VERSION>
+Link Context
+^^^^^^^^^^^^
 
-  The version of the CXX compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+.. genex:: $<LINK_ONLY:...>
 
-.. genex:: $<CUDA_COMPILER_VERSION>
+  .. versionadded:: 3.1
 
-  .. versionadded:: 3.15
+  Content of ``...``, except while collecting :ref:`Target Usage Requirements`,
+  in which case it is the empty string.  This is intended for use in an
+  :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated
+  via the :command:`target_link_libraries` command, to specify private link
+  dependencies without other usage requirements.
 
-  The version of the CUDA compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+  .. versionadded:: 3.24
+    ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target
+    property.  See policy :policy:`CMP0131`.
 
-.. genex:: $<OBJC_COMPILER_VERSION>
+.. genex:: $<DEVICE_LINK:list>
 
-  .. versionadded:: 3.16
+  .. versionadded:: 3.18
 
-  The version of the OBJC compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+  Returns the list if it is the device link step, an empty list otherwise.
+  The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
+  and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and
+  policy :policy:`CMP0105`. This expression can only be used to specify link
+  options.
 
-.. genex:: $<OBJCXX_COMPILER_VERSION>
+.. genex:: $<HOST_LINK:list>
 
-  .. versionadded:: 3.16
+  .. versionadded:: 3.18
 
-  The version of the OBJCXX compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+  Returns the list if it is the normal link step, an empty list otherwise.
+  This expression is mainly useful when a device link step is also involved
+  (see :genex:`$<DEVICE_LINK:list>` generator expression). This expression can
+  only be used to specify link options.
 
-.. genex:: $<Fortran_COMPILER_VERSION>
 
-  The version of the Fortran compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+.. _`Target-Dependent Queries`:
 
-.. genex:: $<HIP_COMPILER_VERSION>
+Target-Dependent Expressions
+----------------------------
 
-  .. versionadded:: 3.21
+These queries refer to a target ``tgt``. Unless otherwise stated, this can
+be any runtime artifact, namely:
 
-  The version of the HIP compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+* An executable target created by :command:`add_executable`.
+* A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
+  library) created by :command:`add_library`.
+* A static library target created by :command:`add_library`.
 
-.. genex:: $<ISPC_COMPILER_VERSION>
+In the following, the phrase "the ``tgt`` filename" means the name of the
+``tgt`` binary file. This has to be distinguished from the phrase
+"the target name", which is just the string ``tgt``.
 
-  .. versionadded:: 3.19
+.. genex:: $<TARGET_EXISTS:tgt>
 
-  The version of the ISPC compiler used.
-  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+  .. versionadded:: 3.12
 
-.. genex:: $<COMPILE_LANGUAGE>
+  ``1`` if ``tgt`` exists as a CMake target, else ``0``.
 
-  .. versionadded:: 3.3
+.. genex:: $<TARGET_NAME_IF_EXISTS:tgt>
 
-  The compile language of source files when evaluating compile options.
-  See :ref:`the related boolean expression
-  <Boolean COMPILE_LANGUAGE Generator Expression>`
-  ``$<COMPILE_LANGUAGE:language>``
-  for notes about the portability of this generator expression.
+  .. versionadded:: 3.12
 
-.. genex:: $<LINK_LANGUAGE>
+  The target name ``tgt`` if the target exists, an empty string otherwise.
 
-  .. versionadded:: 3.18
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on.
 
-  The link language of the target when evaluating link options.
-  See :ref:`the related boolean expression
-  <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>``
-  for notes about the portability of this generator expression.
+.. genex:: $<TARGET_NAME:...>
 
-  .. note::
+  Marks ``...`` as being the name of a target.  This is required if exporting
+  targets to multiple dependent export sets.  The ``...`` must be a literal
+  name of a target, it may not contain generator expressions.
 
-    This generator expression is not supported by the link libraries
-    properties to avoid side-effects due to the double evaluation of
-    these properties.
+.. genex:: $<TARGET_PROPERTY:tgt,prop>
 
-.. _`Target-Dependent Queries`:
+  Value of the property ``prop`` on the target ``tgt``.
 
-Target-Dependent Queries
-^^^^^^^^^^^^^^^^^^^^^^^^
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on.
 
-These queries refer to a target ``tgt``. This can be any runtime artifact,
-namely:
+.. genex:: $<TARGET_PROPERTY:prop>
 
-* an executable target created by :command:`add_executable`
-* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library)
-  created by :command:`add_library`
-* a static library target created by :command:`add_library`
+  Value of the property ``prop`` on the target for which the expression
+  is being evaluated. Note that for generator expressions in
+  :ref:`Target Usage Requirements` this is the consuming target rather
+  than the target specifying the requirement.
 
-In the following, "the ``tgt`` filename" means the name of the ``tgt``
-binary file. This has to be distinguished from "the target name",
-which is just the string ``tgt``.
+.. genex:: $<TARGET_OBJECTS:tgt>
 
-.. genex:: $<TARGET_NAME_IF_EXISTS:tgt>
+  .. versionadded:: 3.1
 
-  .. versionadded:: 3.12
+  List of objects resulting from building ``tgt``.  This would typically be
+  used on :ref:`object library <Object Libraries>` targets.
 
-  The target name ``tgt`` if the target exists, an empty string otherwise.
+.. genex:: $<TARGET_POLICY:policy>
 
-  Note that ``tgt`` is not added as a dependency of the target this
-  expression is evaluated on.
+  ``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
+  else ``0``.  If the ``policy`` was not set, the warning message for the policy
+  will be emitted. This generator expression only works for a subset of
+  policies.
 
 .. genex:: $<TARGET_FILE:tgt>
 
@@ -1306,20 +1560,6 @@ which is just the string ``tgt``.
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
 
-.. genex:: $<TARGET_PROPERTY:tgt,prop>
-
-  Value of the property ``prop`` on the target ``tgt``.
-
-  Note that ``tgt`` is not added as a dependency of the target this
-  expression is evaluated on.
-
-.. genex:: $<TARGET_PROPERTY:prop>
-
-  Value of the property ``prop`` on the target for which the expression
-  is being evaluated. Note that for generator expressions in
-  :ref:`Target Usage Requirements` this is the consuming target rather
-  than the target specifying the requirement.
-
 .. genex:: $<TARGET_RUNTIME_DLLS:tgt>
 
   .. versionadded:: 3.21
@@ -1343,7 +1583,7 @@ which is just the string ``tgt``.
     add_custom_command(TARGET exe POST_BUILD
       COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
       COMMAND_EXPAND_LISTS
-      )
+    )
 
   .. note::
 
@@ -1354,346 +1594,100 @@ which is just the string ``tgt``.
     section for details.  Many :ref:`Find Modules` produce imported targets
     with the ``UNKNOWN`` type and therefore will be ignored.
 
-.. genex:: $<INSTALL_PREFIX>
 
-  Content of the install prefix when the target is exported via
-  :command:`install(EXPORT)`, or when evaluated in the
-  :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of
-  :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise.
-
-Output-Related Expressions
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. genex:: $<TARGET_NAME:...>
-
-  Marks ``...`` as being the name of a target.  This is required if exporting
-  targets to multiple dependent export sets.  The ``...`` must be a literal
-  name of a target, it may not contain generator expressions.
-
-.. genex:: $<LINK_ONLY:...>
-
-  .. versionadded:: 3.1
-
-  Content of ``...``, except while collecting :ref:`Target Usage Requirements`,
-  in which case it is the empty string.  This is intended for use in an
-  :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated
-  via the :command:`target_link_libraries` command, to specify private link
-  dependencies without other usage requirements.
-
-  .. versionadded:: 3.24
-    ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target
-    property.  See policy :policy:`CMP0131`.
-
-.. genex:: $<DEVICE_LINK:list>
+Export And Install Expressions
+------------------------------
 
-  .. versionadded:: 3.18
-
-  Returns the list if it is the device link step, an empty list otherwise.
-  The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
-  and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and
-  policy :policy:`CMP0105`. This expression can only be used to specify link
-  options.
-
-.. genex:: $<HOST_LINK:list>
-
-  .. versionadded:: 3.18
-
-  Returns the list if it is the normal link step, an empty list otherwise.
-  This expression is mainly useful when a device link step is also involved
-  (see :genex:`$<DEVICE_LINK:list>` generator expression). This expression can
-  only be used to specify link options.
-
-.. genex:: $<LINK_LIBRARY:feature,library-list>
-
-  .. versionadded:: 3.24
-
-  Specify a set of libraries to link to a target, along with a ``feature``
-  which provides details about *how* they should be linked.  For example:
-
-  .. code-block:: cmake
-
-    add_library(lib1 STATIC ...)
-    add_library(lib2 ...)
-    target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")
-
-  This specifies that ``lib2`` should link to ``lib1`` and use the
-  ``WHOLE_ARCHIVE`` feature when doing so.
-
-  Feature names are case-sensitive and may only contain letters, numbers and
-  underscores.  Feature names defined in all uppercase are reserved for CMake's
-  own built-in features.  The pre-defined built-in library features are:
-
-  .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
-
-  Built-in and custom library features are defined in terms of the following
-  variables:
-
-  * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
-  * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
-  * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`
-  * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`
-
-  The value used for each of these variables is the value as set at the end of
-  the directory scope in which the target was created.  The usage is as follows:
-
-  1. If the language-specific
-     :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable
-     is true, the ``feature`` must be defined by the corresponding
-     :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable.
-  2. If no language-specific ``feature`` is supported, then the
-     :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable must be
-     true and the ``feature`` must be defined by the corresponding
-     :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable.
-
-  The following limitations should be noted:
-
-  * The ``library-list`` can specify CMake targets or libraries.
-    Any CMake target of type :ref:`OBJECT <Object Libraries>`
-    or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
-    of the expression and instead be linked in the standard way.
-
-  * The ``$<LINK_LIBRARY:...>`` generator expression can only be used to
-    specify link libraries.  In practice, this means it can appear in the
-    :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
-    :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`  target properties, and be
-    specified in :command:`target_link_libraries` and :command:`link_libraries`
-    commands.
-
-  * If a ``$<LINK_LIBRARY:...>`` generator expression appears in the
-    :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
-    included in the imported target generated by a :command:`install(EXPORT)`
-    command.  It is the responsibility of the environment consuming this
-    import to define the link feature used by this expression.
-
-  * Each target or library involved in the link step must have at most only
-    one kind of library feature.  The absence of a feature is also incompatible
-    with all other features.  For example:
-
-    .. code-block:: cmake
-
-      add_library(lib1 ...)
-      add_library(lib2 ...)
-      add_library(lib3 ...)
-
-      # lib1 will be associated with feature1
-      target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
-
-      # lib1 is being linked with no feature here. This conflicts with the
-      # use of feature1 in the line above and would result in an error.
-      target_link_libraries(lib3 PRIVATE lib1 lib2)
-
-    Where it isn't possible to use the same feature throughout a build for a
-    given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
-    :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be
-    used to resolve such incompatibilities.
-
-  * The ``$<LINK_LIBRARY:...>`` generator expression does not guarantee
-    that the list of specified targets and libraries will be kept grouped
-    together.  To manage constructs like ``--start-group`` and ``--end-group``,
-    as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP`
-    generator expression instead.
-
-.. genex:: $<LINK_GROUP:feature,library-list>
-
-  .. versionadded:: 3.24
-
-  Specify a group of libraries to link to a target, along with a ``feature``
-  which defines how that group should be linked.  For example:
-
-  .. code-block:: cmake
-
-    add_library(lib1 STATIC ...)
-    add_library(lib2 ...)
-    target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
-
-  This specifies that ``lib2`` should link to ``lib1`` and ``external``, and
-  that both of those two libraries should be included on the linker command
-  line according to the definition of the ``RESCAN`` feature.
+.. genex:: $<INSTALL_INTERFACE:...>
 
-  Feature names are case-sensitive and may only contain letters, numbers and
-  underscores.  Feature names defined in all uppercase are reserved for CMake's
-  own built-in features.  Currently, there is only one pre-defined built-in
-  group feature:
+  Content of ``...`` when the property is exported using
+  :command:`install(EXPORT)`, and empty otherwise.
 
-  .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt
+.. genex:: $<BUILD_INTERFACE:...>
 
-  Built-in and custom group features are defined in terms of the following
-  variables:
+  Content of ``...`` when the property is exported using :command:`export`, or
+  when the target is used by another target in the same buildsystem. Expands to
+  the empty string otherwise.
 
-  * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
-  * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`
-  * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
-  * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`
+.. genex:: $<INSTALL_PREFIX>
 
-  The value used for each of these variables is the value as set at the end of
-  the directory scope in which the target was created.  The usage is as follows:
+  Content of the install prefix when the target is exported via
+  :command:`install(EXPORT)`, or when evaluated in the
+  :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of
+  :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise.
 
-  1. If the language-specific
-     :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable
-     is true, the ``feature`` must be defined by the corresponding
-     :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable.
-  2. If no language-specific ``feature`` is supported, then the
-     :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable must be
-     true and the ``feature`` must be defined by the corresponding
-     :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable.
+Multi-level Expression Evaluation
+---------------------------------
 
-  The ``LINK_GROUP`` generator expression is compatible with the
-  :genex:`LINK_LIBRARY` generator expression. The libraries involved in a
-  group can be specified using the :genex:`LINK_LIBRARY` generator expression.
+.. genex:: $<GENEX_EVAL:expr>
 
-  Each target or external library involved in the link step is allowed to be
-  part of multiple groups, but only if all the groups involved specify the
-  same ``feature``.  Such groups will not be merged on the linker command line,
-  the individual groups will still be preserved.  Mixing different group
-  features for the same target or library is forbidden.
+  .. versionadded:: 3.12
 
-  .. code-block:: cmake
+  Content of ``expr`` evaluated as a generator expression in the current
+  context. This enables consumption of generator expressions whose
+  evaluation results itself in generator expressions.
 
-    add_library(lib1 ...)
-    add_library(lib2 ...)
-    add_library(lib3 ...)
-    add_library(lib4 ...)
-    add_library(lib5 ...)
+.. genex:: $<TARGET_GENEX_EVAL:tgt,expr>
 
-    target_link_libraries(lib3 PUBLIC  "$<LINK_GROUP:feature1,lib1,lib2>")
-    target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
-    # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
-    # Both groups specify the same feature, so this is fine.
+  .. versionadded:: 3.12
 
-    target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
-    # An error will be raised here because both lib1 and lib3 are part of two
-    # groups with different features.
+  Content of ``expr`` evaluated as a generator expression in the context of
+  ``tgt`` target. This enables consumption of custom target properties that
+  themselves contain generator expressions.
 
-  When a target or an external library is involved in the link step as part of
-  a group and also as not part of any group, any occurrence of the non-group
-  link item will be replaced by the groups it belongs to.
+  Having the capability to evaluate generator expressions is very useful when
+  you want to manage custom properties supporting generator expressions.
+  For example:
 
   .. code-block:: cmake
 
-    add_library(lib1 ...)
-    add_library(lib2 ...)
-    add_library(lib3 ...)
-    add_library(lib4 ...)
-
-    target_link_libraries(lib3 PUBLIC lib1)
-
-    target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
-    # lib4 will only be linked with lib3 and the group {lib1,lib2}
+    add_library(foo ...)
 
-  Because ``lib1`` is part of the group defined for ``lib4``, that group then
-  gets applied back to the use of ``lib1`` for ``lib3``.  The end result will
-  be as though the linking relationship for ``lib3`` had been specified as:
+    set_property(TARGET foo PROPERTY
+      CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
+    )
 
-  .. code-block:: cmake
+    add_custom_target(printFooKeys
+      COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
+    )
 
-    target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
+  This naive implementation of the ``printFooKeys`` custom command is wrong
+  because ``CUSTOM_KEYS`` target property is not evaluated and the content
+  is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``).
 
-  Be aware that the precedence of the group over the non-group link item can
-  result in circular dependencies between groups.  If this occurs, a fatal
-  error is raised because circular dependencies are not allowed for groups.
+  To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is
+  ``Debug``), it is required to evaluate the output of
+  ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``:
 
   .. code-block:: cmake
 
-    add_library(lib1A ...)
-    add_library(lib1B ...)
-    add_library(lib2A ...)
-    add_library(lib2B ...)
-    add_library(lib3 ...)
-
-    # Non-group linking relationships, these are non-circular so far
-    target_link_libraries(lib1A PUBLIC lib2A)
-    target_link_libraries(lib2B PUBLIC lib1B)
-
-    # The addition of these groups creates circular dependencies
-    target_link_libraries(lib3 PRIVATE
-      "$<LINK_GROUP:feat,lib1A,lib1B>"
-      "$<LINK_GROUP:feat,lib2A,lib2B>"
+    add_custom_target(printFooKeys
+      COMMAND ${CMAKE_COMMAND} -E
+        echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
     )
 
-  Because of the groups defined for ``lib3``, the linking relationships for
-  ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of:
-
-  .. code-block:: cmake
-
-    target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
-    target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
-
-  This creates a circular dependency between groups:
-  ``lib1A --> lib2B --> lib1A``.
-
-  The following limitations should also be noted:
-
-  * The ``library-list`` can specify CMake targets or libraries.
-    Any CMake target of type :ref:`OBJECT <Object Libraries>`
-    or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect
-    of the expression and instead be linked in the standard way.
-
-  * The ``$<LINK_GROUP:...>`` generator expression can only be used to
-    specify link libraries.  In practice, this means it can appear in the
-    :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and
-    :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be
-    specified in :command:`target_link_libraries` and :command:`link_libraries`
-    commands.
-
-  * If a ``$<LINK_GROUP:...>`` generator expression appears in the
-    :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be
-    included in the imported target generated by a :command:`install(EXPORT)`
-    command.  It is the responsibility of the environment consuming this
-    import to define the link feature used by this expression.
-
-.. genex:: $<INSTALL_INTERFACE:...>
-
-  Content of ``...`` when the property is exported using
-  :command:`install(EXPORT)`, and empty otherwise.
-
-.. genex:: $<BUILD_INTERFACE:...>
-
-  Content of ``...`` when the property is exported using :command:`export`, or
-  when the target is used by another target in the same buildsystem. Expands to
-  the empty string otherwise.
-
-.. genex:: $<MAKE_C_IDENTIFIER:...>
-
-  Content of ``...`` converted to a C identifier.  The conversion follows the
-  same behavior as :command:`string(MAKE_C_IDENTIFIER)`.
-
-.. genex:: $<TARGET_OBJECTS:objLib>
-
-  .. versionadded:: 3.1
-
-  List of objects resulting from build of ``objLib``.
+Escaped Characters
+------------------
 
-.. genex:: $<SHELL_PATH:...>
+These expressions evaluate to specific string literals. Use them in place of
+the actual string literal where you need to prevent them from having their
+special meaning.
 
-  .. versionadded:: 3.4
+.. genex:: $<ANGLE-R>
 
-  Content of ``...`` converted to shell path style. For example, slashes are
-  converted to backslashes in Windows shells and drive letters are converted
-  to posix paths in MSYS shells. The ``...`` must be an absolute path.
+  A literal ``>``. Used for example to compare strings that contain a ``>``.
 
-  .. versionadded:: 3.14
-    The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>`
-    of paths, in which case each path is converted individually and a result
-    list is generated using the shell path separator (``:`` on POSIX and
-    ``;`` on Windows).  Be sure to enclose the argument containing this genex
-    in double quotes in CMake source code so that ``;`` does not split arguments.
+.. genex:: $<COMMA>
 
-.. genex:: $<OUTPUT_CONFIG:...>
+  A literal ``,``. Used for example to compare strings which contain a ``,``.
 
-  .. versionadded:: 3.20
+.. genex:: $<SEMICOLON>
 
-  Only valid in :command:`add_custom_command` and :command:`add_custom_target`
-  as the outer-most generator expression in an argument.
-  With the :generator:`Ninja Multi-Config` generator, generator expressions
-  in ``...`` are evaluated using the custom command's "output config".
-  With other generators, the content of ``...`` is evaluated normally.
+  A literal ``;``. Used to prevent list expansion on an argument with ``;``.
 
-.. genex:: $<COMMAND_CONFIG:...>
+Deprecated Expressions
+----------------------
 
-  .. versionadded:: 3.20
+.. genex:: $<CONFIGURATION>
 
-  Only valid in :command:`add_custom_command` and :command:`add_custom_target`
-  as the outer-most generator expression in an argument.
-  With the :generator:`Ninja Multi-Config` generator, generator expressions
-  in ``...`` are evaluated using the custom command's "command config".
-  With other generators, the content of ``...`` is evaluated normally.
+  Configuration name. Deprecated since CMake 3.0. Use :genex:`CONFIG` instead.