|
|
@@ -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.
|
Craig Scott