Help: Improve link library feature properties docs

4 files changed, 115 insertions, 103 deletions

diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst
index d8efd0f..10f4fda 100644
--- a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst
+++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst
@@ -3,10 +3,8 @@ CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES
 
 .. versionadded:: 3.30
 
-This variable defines the semantics of the specified ``<FEATURE>`` for the
-language ``<LANG>`` (as described by the
-:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` or
-:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables) used for the link
-command generation.
-
-.. include:: CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt
+This variable defines the semantics of the specified link library ``<FEATURE>``
+when linking with the link language ``<LANG>``. It takes precedence over
+:variable:`CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES` if that variable is also
+defined for the same ``<FEATURE>``, but otherwise has similar effects.
+See :variable:`CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES` for further details.
diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst b/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst
index 86b4e77..e30c30a 100644
--- a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst
+++ b/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst
@@ -3,12 +3,113 @@ CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES
 
 .. versionadded:: 3.30
 
-This variable defines the semantics of the specified ``<FEATURE>`` (as
-described by the :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` or
-:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables) used for the link
-command generation.
+This variable defines the behavior of the specified link library
+``<FEATURE>``. It specifies how the ``<FEATURE>`` interacts with other
+features, when the ``<FEATURE>`` should be applied, and aspects of how the
+``<FEATURE>`` should be handled when CMake assembles the final linker
+command line (e.g. de-duplication).
 
-This variable will be considered only if the
- :variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` is not defined.
+The syntax of the linker flags for the ``<FEATURE>`` are controlled by the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
+The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variables
+control whether the ``<FEATURE>`` is available at all.
 
-.. include:: CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt
+When linking for a particular language ``<LANG>``,
+``CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES`` is ignored if the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` variable is also
+defined for the same ``<FEATURE>``.
+
+The value of ``CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES`` and
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` at the end of the
+directory scope in which a target is defined is what matters.
+
+Feature Properties Definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A feature properties definition is a
+:ref:`semicolon-separated list <CMake Language Lists>` of ``property=value(s)``
+items. If a property has multiple values, those values must be comma-separated.
+
+The following properties are supported:
+
+``LIBRARY_TYPE=<library-type-list>``
+  Specify the library types supported by the feature. Supported values are:
+  ``STATIC``, ``SHARED``, ``MODULE``, and ``EXECUTABLE``.
+
+  If this property is not specified, the default is
+  ``LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE``.
+
+  If the feature is used with an unsupported library type, CMake will emit a
+  developer warning and the feature will be ignored.
+
+``OVERRIDE=<feature-list>``
+  Specify which features this one replaces in the event of a conflict.
+  This override mechanism is superseded by
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE` or
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target property definitions,
+  if defined.
+
+  If this property is not specified, the default is an empty list.
+
+``UNICITY=YES|NO|DEFAULT``
+  Specify the de-duplication strategy for a library using this feature.
+
+  ``YES``
+    The library is always de-duplicated. The default strategy CMake would
+    normally apply is ignored.
+
+  ``NO``
+    The library is never de-duplicated. The default strategy CMake would
+    normally apply is ignored.
+
+  ``DEFAULT``
+    Let CMake determine a de-duplication strategy automatically.
+
+  If this property is not specified, ``DEFAULT`` will be used.
+
+Example
+^^^^^^^
+
+A common need is the loading of a full archive as part of the creation of a
+shared library. The built-in ``WHOLE_ARCHIVE`` feature can be used for that
+purpose. The implementation of that built-in feature sets the following
+link library feature properties:
+
+.. code-block:: cmake
+
+  set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_PROPERTIES
+    LIBRARY_TYPE=STATIC
+    OVERRIDE=DEFAULT
+    UNICITY=YES
+  )
+
+``LIBRARY_TYPE=STATIC``
+  This feature is only meaningful for static libraries.
+``OVERRIDE=DEFAULT``
+  The ``DEFAULT`` feature will be overridden by the ``WHOLE_ARCHIVE`` feature
+  because they are compatible and enhance the user's experience: standard
+  library specification and ``$<LINK_LIBRARY:WHOLE_ARCHIVE>`` can be used
+  freely.
+``UNICITY=YES``
+  When this feature is used, the linker loads all symbols from the static
+  library, so there is no need to repeat the library on the linker
+  command line.
+
+The ``WHOLE_ARCHIVE`` feature can be used like so:
+
+.. code-block:: cmake
+
+  add_library(A STATIC ...)
+  add_library(B STATIC ...)
+
+  target_link_libraries(B PUBLIC A)
+  target_link_libraries(A PUBLIC B)
+
+  add_library(global SHARED ...)
+  target_link_libraries(global PRIVATE $<LINK_LIBRARY:WHOLE_ARCHIVE,A>)
+
+The resulting link command will only have one instance of the ``A`` library
+specified, and the linker flags will ensure that all symbols are loaded from
+the ``A`` library.
diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt b/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt
deleted file mode 100644
index 202a7ec..0000000
--- a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt
+++ /dev/null
@@ -1,87 +0,0 @@
-Feature Properties Definition
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A feature properties definition is a
-:ref:`semicolon-separated list <CMake Language Lists>` of ``property=value(s)``
-items. In the case of multiple values can be specified, they are separated by
-a comma.
-
-The following properties are supported:
-
-``LIBRARY_TYPE=<library_type-list>``
-  Specify which library types are supported by this feature. The possible
-  values are: ``STATIC``, ``SHARED``, ``MODULE`` or ``EXECUTABLE``.
-
-  If this property is not specified, the default is
-  ``LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE``.
-
-  If the feature is used with an unsupported library type, CMake will emit a
-  developer warning and the feature will be ignored.
-
-``OVERRIDE=<feature-list>``
-  Specify which features will be replaced by this one in the event of a
-  conflict. This override mechanism is superseded by any
-  :prop_tgt:`LINK_LIBRARY_OVERRIDE` or
-  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties definitions.
-
-  If this property is not specified, the default is an empty list.
-
-``UNICITY=YES|NO|DEFAULT``
-  Manage the strategy of de-duplication for the libraries using this feature.
-
-  ``YES``
-    Libraries are de-duplicated regardless the default strategy applied by
-    CMake.
-
-  ``NO``
-    Libraries are not de-duplicated regardless the default strategy applied
-    by CMake.
-
-  ``DEFAULT``
-    Apply the default CMake strategy.
-
-  If this property is not specified, ``DEFAULT`` will be used.
-
-Example
-^^^^^^^
-
-A common need is the loading of a full archive as part of the creation of a
-shared library or an executable. For that purpose, the ``WHOLE_ARCHIVE``
-feature can be used.
-
-Currently, the associated properties with this feature are defined as follows:
-
-.. code-block:: cmake
-
-  set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_PROPERTIES LIBRARY_TYPE=STATIC
-                                                  OVERRIDE=DEFAULT
-                                                  UNICITY=YES)
-
-``LIBRARY_TYPE=STATIC``
-  Obviously, this feature is only meaningful for static libraries.
-``OVERRIDE=DEFAULT``
-  The ``DEFAULT`` feature will be overridden by the ``WHOLE_ARCHIVE`` feature
-  because they are compatible and enhance the user's experience: standard
-  library specification and ``$<LINK_LIBRARY:WHOLE_ARCHIVE>`` can be used
-  freely.
-``UNICITY=YES``
-  When this feature is used, all symbols from the static library are loaded
-  by the linker, so there is no need to duplicate the library on the link
-  command.
-
-A typical usage of the ``WHOLE_ARCHIVE`` can be:
-
-.. code-block:: cmake
-
-  add_library(A STATIC ...)
-  add_library(B STATIC ...)
-
-  target_link_libraries(B PUBLIC A)
-  target_link_libraries(A PUBLIC B)
-
-  add_library(global SHARED ...)
-  target_link_libraries(global PRIVATE $<LINK_LIBRARY:WHOLE_ARCHIVE,A>)
-
-The resulting link command will only have one iteration of the ``A`` library
-specified with the needed linker flags to ensure the load of all the symbols
-of the library.
diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt
index 0359f58..59a0d02 100644
--- a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt
+++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt
@@ -2,8 +2,8 @@ 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 (see `Predefined Features`_ further below).
 
-The feature behavior can be described using the
-:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` or
+Some aspects of feature behavior can be defined by the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` and
 :variable:`CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES` variables.
 
 Feature Definitions