Genex-LINK_GROUP: Add feature RESCAN

Feature RESCAN can be used to manage circular references between
static libraries.

3 files changed, 36 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst
index b68c94a..f2ef843 100644
--- a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst
+++ b/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
diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst
index 8aade01..fad1837 100644
--- a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst
+++ b/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
diff --git a/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt
new file mode 100644
index 0000000..7c5b458
--- /dev/null
+++ b/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.