mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-04-24 07:08:38 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'revert-link-interface-direct-for-3.23' into release-3.23

Browse Source 
687a91967f Revert INTERFACE_LINK_LIBRARIES_DIRECT feature for 3.23 branch

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7098
This commit is contained in:
Brad King
2022-03-22 15:56:32 +00:00
committed by Kitware Robot
parent 25c31f1955 687a91967f
commit 2aad4cef97
78 changed files with 27 additions and 1320 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/manual/cmake-properties.7.rst
-2
View File
@@ -266,8 +266,6 @@ Properties on Targets
/prop_tgt/INTERFACE_LINK_DEPENDS
/prop_tgt/INTERFACE_LINK_DIRECTORIES
/prop_tgt/INTERFACE_LINK_LIBRARIES
/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT
/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
/prop_tgt/INTERFACE_LINK_OPTIONS
/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE
/prop_tgt/INTERFACE_PRECOMPILE_HEADERS
Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
-6
View File
@@ -26,12 +26,6 @@ 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst
-223
View File
@@ -1,223 +0,0 @@
INTERFACE_LINK_LIBRARIES_DIRECT
-------------------------------
.. versionadded:: 3.23
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``.
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt
-9
View File
@@ -1,9 +0,0 @@
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`.
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst
-34
View File
@@ -1,34 +0,0 @@
INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
---------------------------------------
.. versionadded:: 3.23
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.
Help/prop_tgt/LINK_LIBRARIES.rst
-5
View File
@@ -20,8 +20,3 @@ 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.
Help/release/3.23.rst
-5
View File
@@ -130,11 +130,6 @@ Properties
not be treated as a system library (i.e. its include directories
are not automatically ``SYSTEM``).
* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
were added to express usage requirements affecting a consumer's
direct link dependencies.
* The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property
was added to tell the :generator:`Xcode` generator what targets to put in
the ``Embed PlugIns`` build phase.