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=<library-type-list>

指定特性支援的程式庫類型。支援的值為：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 程式庫載入。