CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_PROPERTIES

New in version 3.30.

This variable defines the semantics of the specified <FEATURE> for the language <LANG> (as described by the CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> or CMAKE_LINK_LIBRARY_USING_<FEATURE> variables) used for the link command generation.

Feature Properties Definition

A feature properties definition is a semicolon-separated list 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 LINK_LIBRARY_OVERRIDE or 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:

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:

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.