Merge topic 'doc-LINK_LIBRARY_genex'

d185f7c0a8 Help: Rework $<LINK_LIBRARY>, $<LINK_GROUP> and related docs

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

2 files changed, 68 insertions, 51 deletions

diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
index 81a2a4a..916a7c6 100644
--- a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
@@ -3,52 +3,63 @@ LINK_LIBRARY_OVERRIDE
 
 .. versionadded:: 3.24
 
-To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator
-expression, this property offers the possibility to override, per ``link-item``
-(``CMake`` target or external library) involved in the link step, any defined
-features with a new one.
+Override the library features associated with libraries from
+:genex:`LINK_LIBRARY` generator expressions.  This can be used to resolve
+incompatible library features that result from specifying different features
+for the same library in different :genex:`LINK_LIBRARY` generator expressions.
 
-This property takes a :ref:`;-list <CMake Language Lists>` of override
-declarations which have the following format:
-
-::
+This property supports overriding multiple libraries and features. It expects
+a :ref:`semicolon-separated list <CMake Language Lists>`, where each list item
+has the following form::
 
   feature[,link-item]*
 
-For the list of ``link-item`` (``CMake`` target or external library) specified,
-the feature ``feature`` will be used in place of any declared feature. For
-example:
+For each comma-separated ``link-item``, any existing library feature associated
+with it will be ignored for the target this property is set on.  The item
+will instead be associated with the specified ``feature``.  Each ``link-item``
+can be anything that would be accepted as part of a ``library-list`` in a
+:genex:`LINK_LIBRARY` generator expression.
 
 .. code-block:: cmake
 
   add_library(lib1 ...)
-  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
-
   add_library(lib2 ...)
-  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
-
   add_library(lib3 ...)
+
+  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
+  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
   target_link_libraries(lib3 PRIVATE lib1 lib2)
-  # Here, lib1 has two different features which prevents to link lib3
-  # So, define LINK_LIBRARY_OVERRIDE property to ensure correct link
+
+  # lib1 is associated with both feature2 and no feature. Without any override,
+  # this would result in a fatal error at generation time for lib3.
+  # Define an override to resolve the incompatible feature associations.
   set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
-  # The lib1 and external will be used with FEATURE2 to link lib3
 
-It is also possible to override any feature with the pre-defined feature
-``DEFAULT`` to get the standard behavior (i.e. no feature):
+  # lib1 and external will now be associated with feature2 instead when linking lib3
+
+It is also possible to override any feature with the pre-defined ``DEFAULT``
+library feature.  This effectively discards any feature for that link item,
+for that target only (``lib3`` in this example):
 
 .. code-block:: cmake
 
-  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "DEFAULT,lib1"
-                                                          "feature2,external")
-  # The lib1 will be used without any feature and external will use feature2 to link lib3
+  # When linking lib3, discard any library feature for lib1, and use feature2 for external
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
+    "DEFAULT,lib1"
+    "feature2,external"
+  )
+
+The above example also demonstrates how to specify different feature overrides
+for different link items.  See the :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>`
+target property for an alternative way of overriding library features for
+individual libraries, which may be simpler in some cases.  If both properties
+are defined and specify an override for the same link item,
+:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` takes precedence over
+``LINK_LIBRARY_OVERRIDE``.
 
 Contents of ``LINK_LIBRARY_OVERRIDE`` may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
-See also :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target property for
-a per linked target oriented approach to override features.
-
-For more information about features, see
-:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
-and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
+For more information about library features, see the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
index 112f614..4d3dd4f 100644
--- a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
@@ -3,43 +3,49 @@ LINK_LIBRARY_OVERRIDE_<LIBRARY>
 
 .. versionadded:: 3.24
 
-To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator
-expression, this property offers the possibility to override, for a
-``link-item`` (``CMake`` target or external library) involved in the link step,
-any defined features with a new one.
+Override the library feature associated with ``<LIBRARY>`` from
+:genex:`LINK_LIBRARY` generator expressions.  This can be used to resolve
+incompatible library features that result from specifying different features
+for ``<LIBRARY>`` in different :genex:`LINK_LIBRARY` generator expressions.
 
-This property takes a ``feature`` name which will be applied to the
-``link-item`` specified by ``<LIBRARY>`` suffix property. For example:
+When set on a target, this property holds a single library feature name, which
+will be applied to ``<LIBRARY>`` when linking that target.
 
 .. code-block:: cmake
 
   add_library(lib1 ...)
-  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
-
   add_library(lib2 ...)
-  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
-
   add_library(lib3 ...)
+
+  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
+  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
   target_link_libraries(lib3 PRIVATE lib1 lib2)
-  # Here, lib1 has two different features which prevents to link lib3
-  # So, define LINK_LIBRARY_OVERRIDE_lib1 property to ensure correct link
+
+  # lib1 is associated with both feature2 and no feature. Without any override,
+  # this would result in a fatal error at generation time for lib3.
+  # Define an override to resolve the incompatible feature associations.
   set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
-  # The lib1 will be used with feature2 to link lib3
 
-It is also possible to override any feature with the pre-defined feature
-``DEFAULT`` to get the standard behavior (i.e. no feature):
+  # lib1 will now be associated with feature2 instead when linking lib3
+
+It is also possible to override any feature with the pre-defined ``DEFAULT``
+library feature.  This effectively discards any feature for that link item,
+for that target only (``lib3`` in this example):
 
 .. code-block:: cmake
 
+  # When linking lib3, discard any library feature for lib1
   set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
-  # The lib1 will be used without any feature to link lib3
+
+See the :prop_tgt:`LINK_LIBRARY_OVERRIDE` target property for an alternative
+way of overriding library features for multiple libraries at once.  If both
+properties are defined and specify an override for the same link item,
+``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` takes precedence over
+:prop_tgt:`LINK_LIBRARY_OVERRIDE`.
 
 Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
-This property takes precedence over :prop_tgt:`LINK_LIBRARY_OVERRIDE`
-target property.
-
-For more information about features, see
-:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
-and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
+For more information about library features, see the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.