Merge topic 'LINK_GROUP-rescan-static-libs'

b0fada9964 Genex-LINK_GROUP: Add feature RESCAN

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7044

Help/manual/cmake-generator-expressions.7.rst

@@ -1236,7 +1236,7 @@ Output-Related Expressions
     expression.
 
   The ``library-list`` argument can hold CMake targets or external libraries.
-  Any ``CMake`` target of type :ref:`OBJECT <Object Libraries>` or
+  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.
 
@@ -1284,7 +1284,7 @@ Output-Related Expressions
     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:
+  This example will be "re-written" by CMake in the following form:
 
   .. code-block:: cmake
 
@@ -1317,7 +1317,7 @@ Output-Related Expressions
     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:
+  This example will be "re-written" by CMake in the following form:
 
   .. code-block:: cmake
 
@@ -1337,6 +1337,10 @@ Output-Related Expressions
   So, we have a circular dependency between groups ``{lib1A,lib1B}`` and
   ``{lib2A,lib2B}``.
 
+  CMake pre-defines some features of general interest:
+
+  .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt
+
 .. genex:: $<INSTALL_INTERFACE:...>
 
   Content of ``...`` when the property is exported using :command:`install(EXPORT)`,

Help/release/dev/rescan-static-libraries.rst

@@ -0,0 +1,5 @@
+rescan-static-libraries
+-----------------------
+
+* The :genex:`LINK_GROUP` generator expression gained the ability to manage
+  circular references between static libraries by using ``RESCAN`` feature.

Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst

@@ -18,3 +18,10 @@ See also the associated variable
 features independent from the link language.
 
 .. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt
+
+Predefined Features
+^^^^^^^^^^^^^^^^^^^
+
+CMake pre-defines some features of general interest:
+
+.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt

Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst

@@ -23,3 +23,10 @@ for the linker language, the variable
 set.
 
 .. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt
+
+Predefined Features
+^^^^^^^^^^^^^^^^^^^
+
+CMake pre-defines some features of general interest:
+
+.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt

Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt

@@ -0,0 +1,22 @@
+**Circular references with static libraries**
+
+Some linkers are one-pass only so to handle circular references between
+static libraries, the following feature can be used:
+
+``RESCAN``
+  The specified static libraries are searched repeatedly until no
+  new undefined references are created. Normally, an static library is searched
+  only once in the order that it is specified on the command line. If a symbol
+  in that library is needed to resolve an undefined symbol referred to by an
+  object in an library that appears later on the command line, the linker would
+  not be able to resolve that reference. By grouping the static libraries, they
+  all be searched repeatedly until all possible references are resolved (use
+  linker options ``--start-group`` and ``--end-group`` or, on ``SunOS``,
+  ``-z rescan-start`` and ``-z rescan-end``).
+
+  Using this feature has a significant performance cost. It is best to use it
+  only when there are unavoidable circular references between two or more static
+  libraries.
+
+  This feature is available on ``Linux`` and ``SunOS`` platforms as well as
+  ``Windows`` when ``GNU`` toolchain is used.