CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES

Added in version 3.30.

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).

The syntax of the linker flags for the <FEATURE> are controlled by the CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and CMAKE_LINK_LIBRARY_USING_<FEATURE> variables. The CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED and CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variables control whether the <FEATURE> is available at all.

When linking for a particular language <LANG>, CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES is ignored if the CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_ATTRIBUTES variable is also defined for the same <FEATURE>.

The value of CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES and CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_ATTRIBUTES at the end of the directory scope in which a target is defined is what matters.

Feature Attributes Definition

A feature attributes definition is a semicolon-separated list of attribute=value(s) items. If an attribute has multiple values, those values must be comma-separated.

The following attributes 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 attribute 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 LINK_LIBRARY_OVERRIDE or LINK_LIBRARY_OVERRIDE_<LIBRARY> target property definitions, if defined.

If this attribute is not specified, the default is an empty list.

DEDUPLICATION=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 attribute 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 attributes:

set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_ATTRIBUTES
  LIBRARY_TYPE=STATIC
  OVERRIDE=DEFAULT
  DEDUPLICATION=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.

DEDUPLICATION=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:

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.