1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
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.
|
