CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES

在 3.30 版本中添加。

此变量定义了指定的链接库 <FEATURE> 的行为。它指定了 <FEATURE> 如何与其他特性进行交互，在什么时候 <FEATURE> 应该应用，以及当 CMake 组装最终链接器命令行（例如删除重复项）时 <FEATURE> 的处理方式的各个方面。

语法 <FEATURE> 的链接器的标志由 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> 和 CMAKE_LINK_LIBRARY_USING_<FEATURE> 变量进行控制。 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED 和 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED 变量控制能否全面使用 <FEATURE>。

在为特定语言 <LANG> 链接时，如果也针对同样的 <FEATURE> 定义了 CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_ATTRIBUTES 变量，那么 CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES 将被忽略。

在定义目标的目录范围内末尾的 CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES 和 CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_ATTRIBUTES 的值是重要的。

特性属性定义

特性属性定义为一个 用分号分隔的列表，由 attribute=value(s) 项目组成。如果一个属性具有多个值，这些值必须用逗号分隔。

支持以下属性

LIBRARY_TYPE=<库类型列表>

指定特性支持的库类型。支持的值为： STATIC、SHARED、MODULE 和 EXECUTABLE。

如果未指定此属性，则默认值为 LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE。

如果特正在与不支持的库类型联合使用，CMake 将产生一个开发者警告，并且该特性将被忽略。

OVERRIDE=<feature-list>

指定如果发生冲突，此特性将替换其中的哪些特性。此覆盖机制已经被 LINK_LIBRARY_OVERRIDE 或 LINK_LIBRARY_OVERRIDE_<LIBRARY> 目标属性定义（如果已定义）所取代。

如果未指定此属性，则默认值为一个空列表。

DEDUPLICATION=YES|NO|DEFAULT

使用此特性的库的去重策略。

YES

始终对库去重。将忽略 CMake 通常应用的默认策略。

NO

从不对库去重。将忽略 CMake 通常应用的默认策略。

DEFAULT

让 CMake 自动确定去重策略。

如果未指定此属性，将使用 DEFAULT。

范例

常见的需求是在共享库创建过程中加载一个完整归档。内置 WHOLE_ARCHIVE 特性可用于此目的。该内置特性的实现设置了以下链接库特性属性

set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_ATTRIBUTES
  LIBRARY_TYPE=STATIC
  OVERRIDE=DEFAULT
  DEDUPLICATION=YES
)

LIBRARY_TYPE=STATIC

此特性仅对静态库有意义。

OVERRIDE=DEFAULT

DEFAULT 特性将被 WHOLE_ARCHIVE 特性覆盖，因为它们兼容并且增强了用户体验：标准库规范和 $<LINK_LIBRARY:WHOLE_ARCHIVE> 可随意使用。

DEDUPLICATION=YES

当使用此特性时，链接器将从静态库中加载所有符号，因此无需在链接器命令行中重复使用库。

WHOLE_ARCHIVE 特性可如此般使用

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

生成的链接命令将仅有一个指定的 A 库实例，并且链接器标志将确保从 A 库加载所有符号。