Genex-LINK_GROUP: Add possibility to group libraries at link step

Fixes: #23121

7 files changed, 130 insertions, 2 deletions

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