mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 21:59:54 -06:00
Help: Improve link library feature properties docs
This commit is contained in:
Craig Scott
@@ -3,10 +3,8 @@ CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES
|
||||
|
||||
.. versionadded:: 3.30
|
||||
|
||||
This variable defines the semantics of the specified ``<FEATURE>`` for the
|
||||
language ``<LANG>`` (as described by the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` or
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables) used for the link
|
||||
command generation.
|
||||
|
||||
.. include:: CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt
|
||||
This variable defines the semantics of the specified link library ``<FEATURE>``
|
||||
when linking with the link language ``<LANG>``. It takes precedence over
|
||||
:variable:`CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES` if that variable is also
|
||||
defined for the same ``<FEATURE>``, but otherwise has similar effects.
|
||||
See :variable:`CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES` for further details.
|
||||
|
||||
@@ -3,12 +3,113 @@ CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES
|
||||
|
||||
.. versionadded:: 3.30
|
||||
|
||||
This variable defines the semantics of the specified ``<FEATURE>`` (as
|
||||
described by the :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` or
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables) used for the link
|
||||
command generation.
|
||||
This variable defines the behavior of the specified link library
|
||||
``<FEATURE>``. It specifies how the ``<FEATURE>`` interacts with other
|
||||
features, when the ``<FEATURE>`` should be applied, and aspects of how the
|
||||
``<FEATURE>`` should be handled when CMake assembles the final linker
|
||||
command line (e.g. de-duplication).
|
||||
|
||||
This variable will be considered only if the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` is not defined.
|
||||
The syntax of the linker flags for the ``<FEATURE>`` are controlled by the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
|
||||
The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variables
|
||||
control whether the ``<FEATURE>`` is available at all.
|
||||
|
||||
.. include:: CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt
|
||||
When linking for a particular language ``<LANG>``,
|
||||
``CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES`` is ignored if the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` variable is also
|
||||
defined for the same ``<FEATURE>``.
|
||||
|
||||
The value of ``CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES`` and
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` at the end of the
|
||||
directory scope in which a target is defined is what matters.
|
||||
|
||||
Feature Properties Definition
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A feature properties definition is a
|
||||
:ref:`semicolon-separated list <CMake Language Lists>` of ``property=value(s)``
|
||||
items. If a property has multiple values, those values must be comma-separated.
|
||||
|
||||
The following properties are supported:
|
||||
|
||||
``LIBRARY_TYPE=<library-type-list>``
|
||||
Specify the library types supported by the feature. Supported values are:
|
||||
``STATIC``, ``SHARED``, ``MODULE``, and ``EXECUTABLE``.
|
||||
|
||||
If this property is not specified, the default is
|
||||
``LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE``.
|
||||
|
||||
If the feature is used with an unsupported library type, CMake will emit a
|
||||
developer warning and the feature will be ignored.
|
||||
|
||||
``OVERRIDE=<feature-list>``
|
||||
Specify which features this one replaces in the event of a conflict.
|
||||
This override mechanism is superseded by
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE` or
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target property definitions,
|
||||
if defined.
|
||||
|
||||
If this property is not specified, the default is an empty list.
|
||||
|
||||
``UNICITY=YES|NO|DEFAULT``
|
||||
Specify the de-duplication strategy for a library using this feature.
|
||||
|
||||
``YES``
|
||||
The library is always de-duplicated. The default strategy CMake would
|
||||
normally apply is ignored.
|
||||
|
||||
``NO``
|
||||
The library is never de-duplicated. The default strategy CMake would
|
||||
normally apply is ignored.
|
||||
|
||||
``DEFAULT``
|
||||
Let CMake determine a de-duplication strategy automatically.
|
||||
|
||||
If this property is not specified, ``DEFAULT`` will be used.
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
|
||||
A common need is the loading of a full archive as part of the creation of a
|
||||
shared library. The built-in ``WHOLE_ARCHIVE`` feature can be used for that
|
||||
purpose. The implementation of that built-in feature sets the following
|
||||
link library feature properties:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_PROPERTIES
|
||||
LIBRARY_TYPE=STATIC
|
||||
OVERRIDE=DEFAULT
|
||||
UNICITY=YES
|
||||
)
|
||||
|
||||
``LIBRARY_TYPE=STATIC``
|
||||
This feature is only meaningful for static libraries.
|
||||
``OVERRIDE=DEFAULT``
|
||||
The ``DEFAULT`` feature will be overridden by the ``WHOLE_ARCHIVE`` feature
|
||||
because they are compatible and enhance the user's experience: standard
|
||||
library specification and ``$<LINK_LIBRARY:WHOLE_ARCHIVE>`` can be used
|
||||
freely.
|
||||
``UNICITY=YES``
|
||||
When this feature is used, the linker loads all symbols from the static
|
||||
library, so there is no need to repeat the library on the linker
|
||||
command line.
|
||||
|
||||
The ``WHOLE_ARCHIVE`` feature can be used like so:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(A STATIC ...)
|
||||
add_library(B STATIC ...)
|
||||
|
||||
target_link_libraries(B PUBLIC A)
|
||||
target_link_libraries(A PUBLIC B)
|
||||
|
||||
add_library(global SHARED ...)
|
||||
target_link_libraries(global PRIVATE $<LINK_LIBRARY:WHOLE_ARCHIVE,A>)
|
||||
|
||||
The resulting link command will only have one instance of the ``A`` library
|
||||
specified, and the linker flags will ensure that all symbols are loaded from
|
||||
the ``A`` library.
|
||||
|
||||
@@ -1,87 +0,0 @@
|
||||
Feature Properties Definition
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A feature properties definition is a
|
||||
:ref:`semicolon-separated list <CMake Language Lists>` of ``property=value(s)``
|
||||
items. In the case of multiple values can be specified, they are separated by
|
||||
a comma.
|
||||
|
||||
The following properties are supported:
|
||||
|
||||
``LIBRARY_TYPE=<library_type-list>``
|
||||
Specify which library types are supported by this feature. The possible
|
||||
values are: ``STATIC``, ``SHARED``, ``MODULE`` or ``EXECUTABLE``.
|
||||
|
||||
If this property is not specified, the default is
|
||||
``LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE``.
|
||||
|
||||
If the feature is used with an unsupported library type, CMake will emit a
|
||||
developer warning and the feature will be ignored.
|
||||
|
||||
``OVERRIDE=<feature-list>``
|
||||
Specify which features will be replaced by this one in the event of a
|
||||
conflict. This override mechanism is superseded by any
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE` or
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties definitions.
|
||||
|
||||
If this property is not specified, the default is an empty list.
|
||||
|
||||
``UNICITY=YES|NO|DEFAULT``
|
||||
Manage the strategy of de-duplication for the libraries using this feature.
|
||||
|
||||
``YES``
|
||||
Libraries are de-duplicated regardless the default strategy applied by
|
||||
CMake.
|
||||
|
||||
``NO``
|
||||
Libraries are not de-duplicated regardless the default strategy applied
|
||||
by CMake.
|
||||
|
||||
``DEFAULT``
|
||||
Apply the default CMake strategy.
|
||||
|
||||
If this property is not specified, ``DEFAULT`` will be used.
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
|
||||
A common need is the loading of a full archive as part of the creation of a
|
||||
shared library or an executable. For that purpose, the ``WHOLE_ARCHIVE``
|
||||
feature can be used.
|
||||
|
||||
Currently, the associated properties with this feature are defined as follows:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_PROPERTIES LIBRARY_TYPE=STATIC
|
||||
OVERRIDE=DEFAULT
|
||||
UNICITY=YES)
|
||||
|
||||
``LIBRARY_TYPE=STATIC``
|
||||
Obviously, this feature is only meaningful for static libraries.
|
||||
``OVERRIDE=DEFAULT``
|
||||
The ``DEFAULT`` feature will be overridden by the ``WHOLE_ARCHIVE`` feature
|
||||
because they are compatible and enhance the user's experience: standard
|
||||
library specification and ``$<LINK_LIBRARY:WHOLE_ARCHIVE>`` can be used
|
||||
freely.
|
||||
``UNICITY=YES``
|
||||
When this feature is used, all symbols from the static library are loaded
|
||||
by the linker, so there is no need to duplicate the library on the link
|
||||
command.
|
||||
|
||||
A typical usage of the ``WHOLE_ARCHIVE`` can be:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(A STATIC ...)
|
||||
add_library(B STATIC ...)
|
||||
|
||||
target_link_libraries(B PUBLIC A)
|
||||
target_link_libraries(A PUBLIC B)
|
||||
|
||||
add_library(global SHARED ...)
|
||||
target_link_libraries(global PRIVATE $<LINK_LIBRARY:WHOLE_ARCHIVE,A>)
|
||||
|
||||
The resulting link command will only have one iteration of the ``A`` library
|
||||
specified with the needed linker flags to ensure the load of all the symbols
|
||||
of the library.
|
||||
@@ -2,8 +2,8 @@ Feature names are case-sensitive and may only contain letters, numbers
|
||||
and underscores. Feature names defined in all uppercase are reserved for
|
||||
CMake's own built-in features (see `Predefined Features`_ further below).
|
||||
|
||||
The feature behavior can be described using the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` or
|
||||
Some aspects of feature behavior can be defined by the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES` and
|
||||
:variable:`CMAKE_LINK_LIBRARY_<FEATURE>_PROPERTIES` variables.
|
||||
|
||||
Feature Definitions
|
||||
|
||||
Reference in New Issue
Block a user