10 files changed, 291 insertions, 4 deletions
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 0e9060d..403c06e 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1183,13 +1183,160 @@ Output-Related Expressions
   .. note::
 
     This expression does not guarantee that the list of specified libraries
-    will be kept grouped. So, constructs like ``start-group`` and
-    ``end-group``, as supported by ``GNU ld``, cannot be used.
+    will be kept grouped. So, to manage constructs like ``start-group`` and
+    ``end-group``, as supported by ``GNU ld``, the :genex:`LINK_GROUP`
+    generator expression can be used.
 
   ``CMake`` pre-defines some features of general interest:
 
   .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
 
+.. genex:: $<LINK_GROUP:feature,library-list>
+
+  .. versionadded:: 3.24
+
+  Manage the grouping of libraries during the link step.
+  This expression may be used to specify how to kept groups of libraries during
+  the link of a target.
+  For example:
+
+  .. code-block:: cmake
+
+    add_library(lib1 STATIC ...)
+    add_library(lib2 ...)
+    target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
+
+  This specify to use the ``lib1`` target and ``external`` library  with the
+  group feature ``cross_refs`` for linking target ``lib2``. The feature must
+  have be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`
+  variable or, if :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`
+  is false, by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable.
+
+  .. note::
+
+    The evaluation of this generator expression will use, for the following
+    variables, the values defined at the level of the creation of the target:
+
+    * :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>`
+
+  This expression can only be used to specify link libraries (i.e. part of
+  :command:`link_libraries` or :command:`target_link_libraries` commands and
+  :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
+  properties).
+
+  .. note::
+
+    If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+    property of a target, it will be included in the imported target generated
+    by :command:`install(EXPORT)` command. It is the responsibility of the
+    environment consuming this import to define the link feature used by this
+    expression.
+
+  The ``library-list`` argument can hold CMake targets or external libraries.
+  Any ``CMake`` target of type :ref:`OBJECT <Object Libraries>` or
+  :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and
+  will be handled in the standard way.
+
+  .. note::
+
+    This 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.
+
+  Each target or external library involved in the link step can be part of
+  different groups as far as these groups use the same feature, so mixing
+  different group features for the same target or library is forbidden. The
+  different groups will be part of the link step.
+
+  .. code-block:: cmake
+
+    add_library(lib1 ...)
+    add_library(lib2 ...)
+
+    add_library(lib3 ...)
+    target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
+
+    add_library(lib4 ...)
+    target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
+    # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}
+
+    add_library(lib5 ...)
+    target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
+    # an error will be raised here because lib1 is part of two groups with
+    # different features
+
+  When a target or an external library is involved in the link step as part of
+  a group and also as standalone, any occurrence of the standalone link item
+  will be replaced by the group or groups it belong to.
+
+  .. code-block:: cmake
+
+    add_library(lib1 ...)
+    add_library(lib2 ...)
+
+    add_library(lib3 ...)
+    target_link_libraries(lib3 PUBLIC lib1)
+
+    add_library(lib4 ...)
+    target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
+    # lib4 will only be linked with lib3 and the group {lib1,lib2}
+
+  This example will be "re-written" by ``CMake`` in the following form:
+
+  .. code-block:: cmake
+
+    add_library(lib1 ...)
+    add_library(lib2 ...)
+
+    add_library(lib3 ...)
+    target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
+
+    add_library(lib4 ...)
+    target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
+    # lib4 will only be linked with lib3 and the group {lib1,lib2}
+
+  Be aware that the precedence of the group over the standalone link item can
+  result in some circular dependency between groups, which will raise an
+  error because circular dependencies are not allowed for groups.
+
+  .. code-block:: cmake
+
+    add_library(lib1A ...)
+    add_library(lib1B ...)
+
+    add_library(lib2A ...)
+    add_library(lib2B ...)
+
+    target_link_libraries(lib1A PUBLIC lib2A)
+    target_link_libraries(lib2B PUBLIC lib1B)
+
+    add_library(lib ...)
+    target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>"
+                                       "$<LINK_GROUP:feat,lib2A,lib2B>")
+
+  This example will be "re-written" by ``CMake`` in the following form:
+
+  .. code-block:: cmake
+
+    add_library(lib1A ...)
+    add_library(lib1B ...)
+
+    add_library(lib2A ...)
+    add_library(lib2B ...)
+
+    target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
+    target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
+
+    add_library(lib ...)
+    target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>"
+                                       "$<LINK_GROUP:feat,lib2A,lib2B>")
+
+  So, we have a circular dependency between groups ``{lib1A,lib1B}`` and
+  ``{lib2A,lib2B}``.
+
 .. genex:: $<INSTALL_INTERFACE:...>
 
   Content of ``...`` when the property is exported using :command:`install(EXPORT)`,
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index b38f56c..ffebfff 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -440,6 +440,8 @@ Variables that Control the Build
    /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE
    /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LANG_LINKER_LAUNCHER
+   /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE
+   /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LANG_LINK_LIBRARY_FLAG
    /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG
@@ -449,6 +451,8 @@ Variables that Control the Build
    /variable/CMAKE_LIBRARY_PATH_FLAG
    /variable/CMAKE_LINK_DEF_FILE_FLAG
    /variable/CMAKE_LINK_DEPENDS_NO_SHARED
+   /variable/CMAKE_LINK_GROUP_USING_FEATURE
+   /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LINK_INTERFACE_LIBRARIES
    /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LINK_LIBRARY_FLAG
diff --git a/Help/release/dev/Genex-LINK_GROUP.rst b/Help/release/dev/Genex-LINK_GROUP.rst
new file mode 100644
index 0000000..aa9e318
--- /dev/null
+++ b/Help/release/dev/Genex-LINK_GROUP.rst
@@ -0,0 +1,8 @@
+Genex-LINK_GROUP
+----------------
+
+* The :genex:`LINK_GROUP` generator expression was added to manage the grouping
+  of libraries during the link step. The variables
+  :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
+  :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` are used to define features
+  usable by the :genex:`LINK_GROUP` generator expression.
diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst
new file mode 100644
index 0000000..b68c94a
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst
@@ -0,0 +1,20 @@
+CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
+---------------------------------------
+
+.. versionadded:: 3.24
+
+This variable defines, for the specified ``<FEATURE>`` and the linker language
+``<LANG>``, the expression expected by the linker when libraries are specified
+using :genex:`LINK_GROUP` generator expression.
+
+.. note::
+
+  * Feature names can contain Latin letters, digits and undercores.
+  * Feature names defined in all uppercase are reserved to CMake.
+
+See also the associated variable
+:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and
+:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable for the definition of
+features independent from the link language.
+
+.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt
diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst
new file mode 100644
index 0000000..533eee7
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst
@@ -0,0 +1,13 @@
+CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
+-------------------------------------------------
+
+.. versionadded:: 3.24
+
+Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable
+:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, is supported for the
+linker language ``<LANG>``.
+
+.. note::
+
+  This variable is evaluated before the more generic variable
+  :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`.
diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst
index 45b8aa8..a9fa9a7 100644
--- a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst
+++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst
@@ -9,7 +9,8 @@ using :genex:`LINK_LIBRARY` generator expression.
 
 .. note::
 
-  Feature names defined in all uppercase are reserved to CMake.
+  * Feature names can contain Latin letters, digits and undercores.
+  * Feature names defined in all uppercase are reserved to CMake.
 
 See also the associated variable
 :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and
diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst
new file mode 100644
index 0000000..8aade01
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst
@@ -0,0 +1,25 @@
+CMAKE_LINK_GROUP_USING_<FEATURE>
+--------------------------------
+
+.. versionadded:: 3.24
+
+This variable defines, for the specified ``<FEATURE>``, the expression expected
+by the linker when libraries are specified using :genex:`LINK_GROUP` generator
+expression.
+
+.. note::
+
+  * Feature names can contain Latin letters, digits and undercores.
+  * Feature names defined in all uppercase are reserved to CMake.
+
+See also the associated variable
+:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and
+:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable for the definition
+of features dependent from the link language.
+
+This variable will be used by :genex:`LINK_GROUP` generator expression if,
+for the linker language, the variable
+:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is false or not
+set.
+
+.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt
diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt
new file mode 100644
index 0000000..ecd9cb5
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt
@@ -0,0 +1,54 @@
+
+It must contain two elements.
+
+::
+
+  <PREFIX> <SUFFIX>
+
+``<PREFIX>`` and ``<SUFFIX>`` will be used to encapsulate the list of
+libraries.
+
+For the elements of this variable, the ``LINKER:`` prefix can be used:
+
+  .. include:: ../command/LINK_OPTIONS_LINKER.txt
+    :start-line: 3
+
+Examples
+^^^^^^^^
+
+Solving cross-references between two static libraries
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+A common need is the capability to search repeatedly in a group of static
+libraries until no new undefined references are created. This capability is
+offered by different environments but with a specific syntax:
+
+.. code-block:: cmake
+
+  set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
+  if(CMAKE_C_COMPILER_ID STREQUAL "GNU"
+     AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    set(CMAKE_C_LINK_GROUP_USING_cross_refs "LINKER:--start-group"
+                                            "LINKER:--end-group")
+  elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro"
+         AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
+    set(CMAKE_C_LINK_GROUP_USING_cross_refs "LINKER:-z,rescan-start"
+                                            "LINKER:-z,rescan-end")
+  else()
+    # feature not yet supported for the other environments
+    set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
+  endif()
+
+  add_library(lib1 STATIC ...)
+
+  add_library(lib3 SHARED ...)
+  if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
+    target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
+  else()
+    target_link_libraries(lib3 PRIVATE lib1 external)
+  endif()
+
+CMake will generate the following link expressions:
+
+* ``GNU``: ``-Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group``
+* ``SunPro``: ``-Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end``
diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst
new file mode 100644
index 0000000..249ccbc
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst
@@ -0,0 +1,14 @@
+CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
+------------------------------------------
+
+.. versionadded:: 3.24
+
+Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable
+:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`, is supported regardless the
+linker language.
+
+.. note::
+
+  This variable is evaluated if, and only if, the variable
+  :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` evaluates to
+  ``FALSE``.
diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst
index eae60c5..7aace32 100644
--- a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst
+++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst
@@ -9,7 +9,8 @@ using :genex:`LINK_LIBRARY` generator expression.
 
 .. note::
 
-  Feature names defined in all uppercase are reserved to CMake.
+  * Feature names can contain Latin letters, digits and undercores.
+  * Feature names defined in all uppercase are reserved to CMake.
 
 See also the associated variable
 :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and