$<LINK_LIBRARY>: Add LINK_LIBRARY_OVERRIDE target property

To enable the management of incompatible $<LINK_LIBRARY> declarations,
add LINK_LIBRARY_OVERRIDE and LINK_LIBRARY_OVERRIDE_<LIBRARY> target
properties.

8 files changed, 132 insertions, 1 deletions

diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index b67d479..7c34671 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1176,12 +1176,20 @@ Output-Related Expressions
     target_link_libraries(lib3 PRIVATE lib1 lib2)
     # an error will be raised here because lib1 has two different features
 
+  To resolve such incompatibilities, the :prop_tgt:`LINK_LIBRARY_OVERRIDE`
+  and  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be
+  used.
+
   .. note::
 
     This expression does not guarantee that the list of specified libraries
     will be kept grouped. So, constructs like ``start-group`` and
     ``end-group``, as supported by ``GNU ld``, cannot be used.
 
+  ``CMake`` pre-defines some features of general interest:
+
+  .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
+
 .. genex:: $<INSTALL_INTERFACE:...>
 
   Content of ``...`` when the property is exported using :command:`install(EXPORT)`,
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index f4efd3c..e8048b3 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -308,6 +308,8 @@ Properties on Targets
    /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
    /prop_tgt/LINK_LIBRARIES
    /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
+   /prop_tgt/LINK_LIBRARY_OVERRIDE
+   /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY
    /prop_tgt/LINK_OPTIONS
    /prop_tgt/LINK_SEARCH_END_STATIC
    /prop_tgt/LINK_SEARCH_START_STATIC
diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
new file mode 100644
index 0000000..e9c76b0
--- /dev/null
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
@@ -0,0 +1,54 @@
+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.
+
+This property takes a :ref:`;-list <CMake Language Lists>` of override
+declarations which have the following format:
+
+::
+
+  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:
+
+.. 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(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
+  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):
+
+.. 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
+
+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_USING_<FEATURE>`
+and :variable:`CMAKE_LINK_USING_<FEATURE>` variables.
diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
new file mode 100644
index 0000000..58141c9
--- /dev/null
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
@@ -0,0 +1,45 @@
+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.
+
+This property takes a ``feature`` name which will be applied to the
+``link-item`` specified by ``<LIBRARY>`` suffix property. For example:
+
+.. 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(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
+  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):
+
+.. code-block:: cmake
+
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
+  # The lib1 will be used without any feature to link lib3
+
+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_USING_<FEATURE>`
+and :variable:`CMAKE_LINK_USING_<FEATURE>` variables.
diff --git a/Help/release/dev/Genex-LINK_LIBRARY.rst b/Help/release/dev/Genex-LINK_LIBRARY.rst
index 6b87a4f..3234acb 100644
--- a/Help/release/dev/Genex-LINK_LIBRARY.rst
+++ b/Help/release/dev/Genex-LINK_LIBRARY.rst
@@ -5,4 +5,7 @@ Genex-LINK_LIBRARY
   libraries are specified during the link step. The variables
   :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>` and
   :variable:`CMAKE_LINK_USING_<FEATURE>` are used to define features usable by
-  the :genex:`LINK_LIBRARY` generator expression.
+  the :genex:`LINK_LIBRARY` generator expression. Moreover, the
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are available
+  to resolve incompatible features.
diff --git a/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst
index ff8b3d9..9d7f87a 100644
--- a/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst
+++ b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst
@@ -17,3 +17,10 @@ See also the associated variable
 independent from the link language.
 
 .. include:: CMAKE_LINK_USING_FEATURE.txt
+
+Predefined Features
+^^^^^^^^^^^^^^^^^^^
+
+``CMake`` pre-defines some features of general interest:
+
+.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt
diff --git a/Help/variable/CMAKE_LINK_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_USING_FEATURE.rst
index 3d94461..0c9cadc 100644
--- a/Help/variable/CMAKE_LINK_USING_FEATURE.rst
+++ b/Help/variable/CMAKE_LINK_USING_FEATURE.rst
@@ -21,3 +21,10 @@ for the linker language, the variable
 :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` is false or not set.
 
 .. include:: CMAKE_LINK_USING_FEATURE.txt
+
+Predefined Features
+^^^^^^^^^^^^^^^^^^^
+
+``CMake`` pre-defines some features of general interest:
+
+.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt
diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
new file mode 100644
index 0000000..dd22e14
--- /dev/null
+++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
@@ -0,0 +1,5 @@
+**Features available in all environments**
+
+* ``DEFAULT``: This feature enables default link expression. This is mainly
+  useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties.