echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge topic 'doc-link-libraries-strategy'

Browse Source 
1e2b2b7fd2 Help: Clarify LINK_LIBRARIES_STRATEGY follow-up de-duplication

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9933
This commit is contained in:
Brad King 2024-10-24 12:58:27 +00:00 committed by Kitware Robot
commit 23a24935f1
1 changed files with 26 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst
View File

@ -4,7 +4,9 @@ LINK_LIBRARIES_STRATEGY
.. versionadded:: 3.31 .. versionadded:: 3.31
Specify a strategy for ordering a target's direct link dependencies Specify a strategy for ordering a target's direct link dependencies
on linker command lines. on linker command lines. This property is initialized by the value of the
:variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable if it is set when a
target is created.
CMake generates a target's link line using its :ref:`Target Link Properties`. CMake generates a target's link line using its :ref:`Target Link Properties`.
In particular, the :prop_tgt:`LINK_LIBRARIES` target property records the In particular, the :prop_tgt:`LINK_LIBRARIES` target property records the
@ -44,7 +46,11 @@ The supported strategies are:
In the above example, this strategy computes a link line for ``main`` In the above example, this strategy computes a link line for ``main``
by starting with its original entries ``A B C``, and then appends by starting with its original entries ``A B C``, and then appends
another ``A`` to satisfy the dependencies of ``B`` and ``C`` on ``A``. another ``A`` to satisfy the dependencies of ``B`` and ``C`` on ``A``.
The final order is ``A B C A``. The final order produced by this strategy is ``A B C A``.
Note that additional filtering for `Toolchain-Specific Behavior`_
may de-duplicate ``A`` on the actual linker invocation in the
generated build system, resulting in either ``A B C`` or ``B C A``.
``REORDER`` ``REORDER``
Entries of :prop_tgt:`LINK_LIBRARIES` may be reordered, de-duplicated, Entries of :prop_tgt:`LINK_LIBRARIES` may be reordered, de-duplicated,
@ -55,14 +61,24 @@ The supported strategies are:
In the above example, this strategy computes a link line for ``main`` In the above example, this strategy computes a link line for ``main``
by re-ordering its original entries ``A B C`` to satisfy the by re-ordering its original entries ``A B C`` to satisfy the
dependencies of ``B`` and ``C`` on ``A``. dependencies of ``B`` and ``C`` on ``A``.
The final order is ``B C A``. The final order produced by this strategy is ``B C A``.
.. note:: Toolchain-Specific Behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Regardless of the strategy used, the actual linker invocation for Regardless of the strategy used, the actual linker invocation for
some platforms may de-duplicate entries based on linker capabilities. some platforms may de-duplicate entries based on linker capabilities.
See policies :policy:`CMP0156` and :policy:`CMP0179`. See policy :policy:`CMP0156`.
This property is initialized by the value of the For example, if the ``PRESERVE_ORDER`` strategy produces ``A B C A``,
:variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable if it is set when a the actual link line may de-duplicate ``A`` as follows:
target is created.
* If ``A`` is a static library and the linker re-scans automatically,
the first occurrence is kept, resulting in ``A B C``.
See policy :policy:`CMP0179`
* If ``A`` is a shared library on Windows, the first
occurrence is kept, resulting in ``A B C``.
* If ``A`` is a shared library on macOS or UNIX platforms, the last
occurrence is kept, resulting in ``B C A``.