Add usage requirements to update direct link dependencies

Link line construction starts with `LINK_LIBRARIES` and appends
dependencies from the transitive closure of `INTERFACE_LINK_LIBRARIES`.
Only the entries of `LINK_LIBRARIES` are considered direct link
dependencies.  In some advanced use cases, particularly involving static
libraries and static plugins, usage requirements need to update the list
of direct link dependencies.  This may mean adding new items, removing
existing items, or both.

Add target properties to encode these usage requirements:

* INTERFACE_LINK_LIBRARIES_DIRECT
* INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE

Fixes: #22496

5 files changed, 273 insertions, 0 deletions

diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
index af3d9c2..53f5838 100644
--- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
+++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
@@ -26,6 +26,12 @@ manual for more on defining buildsystem properties.
 
 .. include:: LINK_LIBRARIES_INDIRECTION.txt
 
+``INTERFACE_LINK_LIBRARIES`` adds transitive link dependencies for a
+target's dependents.  In advanced use cases, one may update the
+direct link dependencies of a target's dependents by using the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.
+
 Creating Relocatable Packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst
new file mode 100644
index 0000000..1a6ebd1
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst
@@ -0,0 +1,221 @@
+INTERFACE_LINK_LIBRARIES_DIRECT
+-------------------------------
+
+List of libraries that consumers of this library should treat
+as direct link dependencies.
+
+This target property may be set to *include* items in a dependent
+target's final set of direct link dependencies.  See the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target property
+to exclude items.
+
+The initial set of a dependent target's direct link dependencies is
+specified by its :prop_tgt:`LINK_LIBRARIES` target property.  Indirect
+link dependencies are specified by the transitive closure of the direct
+link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
+Any link dependency may specify additional direct link dependencies
+using the ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property.
+The set of direct link dependencies is then filtered to exclude items named
+by any dependency's :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
+target property.
+
+.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT``
+.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
+
+Direct Link Dependencies as Usage Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``INTERFACE_PROPERTY_LINK_DIRECT`` and
+``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties
+are :ref:`usage requirements <Target Usage Requirements>`.
+Their effects propagate to dependent targets transitively, and can
+therefore affect the direct link dependencies of every target in a
+chain of dependent libraries.  Whenever some library target ``X`` links
+to another library target ``Y`` whose direct or transitive usage
+requirements contain ``INTERFACE_PROPERTY_LINK_DIRECT`` or
+``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, the properties may affect
+``X``'s list of direct link dependencies:
+
+* If ``X`` is a shared library or executable, its dependencies are linked.
+  They also affect the usage requirements with which ``X``'s sources are
+  compiled.
+
+* If ``X`` is a static library or object library, it does not actually
+  link, so its dependencies at most affect the usage requirements with
+  which ``X``'s sources are compiled.
+
+The properties may also affect the list of direct link dependencies
+on ``X``'s dependents:
+
+* If ``X`` links ``Y`` publicly:
+
+  .. code-block:: cmake
+
+    target_link_libraries(X PUBLIC Y)
+
+  then ``Y`` is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
+  so ``Y``'s usage requirements, including ``INTERFACE_PROPERTY_LINK_DIRECT``
+  and ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, are propagated
+  to ``X``'s dependents.
+
+* If ``X`` links ``Y`` privately:
+
+  .. code-block:: cmake
+
+    target_link_libraries(X PRIVATE Y)
+
+  then ``Y`` is not placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
+  so ``Y``'s usage requirements, even ``INTERFACE_PROPERTY_LINK_DIRECT``
+  and ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, are not propagated
+  to ``X``'s dependents.
+  (If ``X`` is a static library or object library, then ``$<LINK_ONLY:Y>``
+  is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`, but the
+  :genex:`LINK_ONLY` generator expression block ``Y``'s usage requirements.)
+
+* In either case, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+  is not affected by ``Y``'s ``INTERFACE_PROPERTY_LINK_DIRECT`` or
+  ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``.
+
+One may limit the effects of ``INTERFACE_PROPERTY_LINK_DIRECT`` and
+``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE`` to a subset of dependent
+targets by using the :genex:`TARGET_PROPERTY` generator expression.
+For example, to limit the effects to executable targets, use an
+entry of the form::
+
+  "$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
+
+Similarly, to limit the effects to specific targets, use an entry
+of the form::
+
+  "$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
+
+This entry will only affect targets that set their ``USE_IT``
+target property to a true value.
+
+Direct Link Dependency Ordering
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The list of direct link dependencies for a target is computed from an
+initial ordered list in its :prop_tgt:`LINK_LIBRARIES` target property.
+For each item, additional direct link dependencies are discovered from
+its direct and transitive ``INTERFACE_LINK_LIBRARIES_DIRECT`` usage
+requirements.  Each discovered item is injected before the item that
+specified it.  However, a discovered item is added at most once,
+and only if it did not appear anywhere in the initial list.
+This gives :prop_tgt:`LINK_LIBRARIES` control over ordering of
+those direct link dependencies that it explicitly specifies.
+
+Once all direct link dependencies have been collected, items named by
+all of their :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
+usage requirements are removed from the final list.  This does not
+affect the order of the items that remain.
+
+Example: Static Plugins
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Consider a static library ``Foo`` that provides a static plugin
+``FooPlugin`` to consuming application executables, where the
+implementation of the plugin depends on ``Foo`` and other things.
+In this case, the application should link to ``FooPlugin`` directly,
+before ``Foo``.  However, the application author only knows about ``Foo``.
+We can express this as follows:
+
+.. code-block:: cmake
+
+  # Core library used by other components.
+  add_library(Core STATIC core.cpp)
+
+  # Foo is a static library for use by applications.
+  # Implementation of Foo depends on Core.
+  add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
+  target_link_libraries(Foo PRIVATE Core)
+
+  # Extra parts of Foo for use by its static plugins.
+  # Implementation of Foo's extra parts depends on both Core and Foo.
+  add_library(FooExtras STATIC foo_extras.cpp)
+  target_link_libraries(FooExtras PRIVATE Core Foo)
+
+  # The Foo library has an associated static plugin
+  # that should be linked into the final executable.
+  # Implementation of the plugin depends on Core, Foo, and FooExtras.
+  add_library(FooPlugin STATIC foo_plugin.cpp)
+  target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
+
+  # An app that links Foo should link Foo's plugin directly.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
+
+  # An app does not need to link Foo directly because the plugin links it.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
+
+An application ``app`` only needs to specify that it links to ``Foo``:
+
+.. code-block:: cmake
+
+  add_executable(app main.cpp)
+  target_link_libraries(app PRIVATE Foo)
+
+The ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property on ``Foo`` tells
+CMake to pretend that ``app`` also links directly to ``FooPlugin``.
+The ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target property on ``Foo``
+tells CMake to pretend that ``app`` did *not* link directly to ``Foo``.
+Instead, ``Foo`` will be linked as a dependency of ``FooPlugin``.  The
+final link line for ``app`` will link the libraries in the following
+order:
+
+* ``FooPlugin`` as a direct link dependency of ``app``
+  (via ``Foo``'s usage requiremens).
+* ``FooExtras`` as a dependency of ``FooPlugin``.
+* ``Foo`` as a dependency of ``FooPlugin`` and ``FooExtras``.
+* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
+
+Note that without the ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
+property, ``Foo`` would be linked twice: once as a direct dependency
+of ``app``, and once as a dependency of ``FooPlugin``.
+
+Example: Opt-In Static Plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the above `Example: Static Plugins`_, the ``app`` executable specifies
+that it links directly to ``Foo``.  In a real application, there might
+be an intermediate library:
+
+.. code-block:: cmake
+
+  add_library(app_impl STATIC app_impl.cpp)
+  target_link_libraries(app_impl PUBLIC Foo)
+
+  add_executable(app main.cpp)
+  target_link_libraries(app PRIVATE app_impl)
+
+In this case we do not want ``Foo``'s ``INTERFACE_LINK_LIBRARIES_DIRECT``
+and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties to affect
+the direct dependencies of ``app_impl``.  To avoid this, we can revise
+the property values to make their effects opt-in:
+
+.. code-block:: cmake
+
+  # An app that links Foo should link Foo's plugin directly.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
+    "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
+  )
+
+  # An app does not need to link Foo directly because the plugin links it.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
+    "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
+  )
+
+Now, the ``app`` executable can opt-in to get ``Foo``'s plugin(s):
+
+.. code-block:: cmake
+
+  set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
+
+The final link line for ``app`` will now link the libraries in the following
+order:
+
+* ``FooPlugin`` as a direct link dependency of ``app``
+  (via ``Foo``'s usage requiremens).
+* ``app_impl`` as a direct link dependency of ``app``.
+* ``FooExtras`` as a dependency of ``FooPlugin``.
+* ``Foo`` as a dependency of ``app_impl``, ``FooPlugin``, and ``FooExtras``.
+* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt
new file mode 100644
index 0000000..077af42
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt
@@ -0,0 +1,9 @@
+The value of |INTERFACE_PROPERTY_LINK_DIRECT| may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+.. note::
+
+  The |INTERFACE_PROPERTY_LINK_DIRECT| target property is intended for
+  advanced use cases such as injection of static plugins into a consuming
+  executable.  It should not be used as a substitute for organizing
+  normal calls to :command:`target_link_libraries`.
diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst
new file mode 100644
index 0000000..ecab8a0
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst
@@ -0,0 +1,32 @@
+INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
+---------------------------------------
+
+List of libraries that consumers of this library should *not* treat
+as direct link dependencies.
+
+This target property may be set to *exclude* items from a dependent
+target's final set of direct link dependencies.  This property is
+processed after the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`
+target property of all other dependencies of the dependent target, so
+exclusion from direct link dependence takes priority over inclusion.
+
+The initial set of a dependent target's direct link dependencies is
+specified by its :prop_tgt:`LINK_LIBRARIES` target property.  Indirect
+link dependencies are specified by the transitive closure of the direct
+link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
+Any link dependency may specify additional direct link dependencies
+using the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property.
+The set of direct link dependencies is then filtered to exclude items named
+by any dependency's ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
+property.
+
+Excluding an item from a dependent target's direct link dependencies
+does not mean the dependent target won't link the item.  The item
+may still be linked as an indirect link dependency via the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on other dependencies.
+
+.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``
+.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
+
+See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property
+documentation for more details and examples.
diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst
index 29baf8c..ae5334a 100644
--- a/Help/prop_tgt/LINK_LIBRARIES.rst
+++ b/Help/prop_tgt/LINK_LIBRARIES.rst
@@ -20,3 +20,8 @@ for available expressions.  See the :manual:`cmake-buildsystem(7)` manual
 for more on defining buildsystem properties.
 
 .. include:: LINK_LIBRARIES_INDIRECTION.txt
+
+In advanced use cases, the list of direct link dependencies specified
+by this property may be updated by usage requirements from dependencies.
+See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.