mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 13:51:33 -06:00
88 lines
2.9 KiB
Plaintext
88 lines
2.9 KiB
Plaintext
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.
|