INTERFACE_LINK_LIBRARIES_DIRECT
-------------------------------
.. versionadded:: 3.24
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_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT`` or
``INTERFACE_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT``,
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the usage requirements
declared by the direct link dependencies they add, are propagated to
``X``'s dependents.
* If ``X`` is a static library or object library, and links ``Y`` privately:
.. code-block:: cmake
target_link_libraries(X PRIVATE Y)
then ``$<LINK_ONLY:Y>`` is placed in ``X``'s
:prop_tgt:`INTERFACE_LINK_LIBRARIES`. ``Y``'s linking requirements,
including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the transitive link
dependencies declared by the direct link dependencies they add, are
propagated to ``X``'s dependents. However, ``Y``'s non-linking
usage requirements are blocked by the :genex:`LINK_ONLY` generator
expression, and are not propagated to ``X``'s dependents.
* If ``X`` is a shared library or executable, and 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_LINK_LIBRARIES_DIRECT``
and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, are not propagated to
``X``'s dependents.
* In all cases, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`
is not affected by ``Y``'s ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``.
One may limit the effects of ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
``INTERFACE_LINK_LIBRARIES_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 requirements).
* ``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 PRIVATE 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 requirements).
* ``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``.
Generated by dwww version 1.15 on Fri Jun 28 23:01:38 CEST 2024.