指定要連結到目標的函式庫群組,以及定義該群組應如何連結的 feature
。例如:
add_library(lib1 STATIC ...)
add_library(lib2 ...)
target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
這指定了 lib2
應連結到 lib1
和 external
,並且這兩個函式庫都應根據 RESCAN
特性的定義包含在連結器命令列中。
特性名稱區分大小寫,且只能包含字母、數字和底線。以全部大寫定義的特性名稱保留給 CMake 自己的內建特性。目前,只有一個預定義的內建群組特性:
RESCAN
某些連結器是單次掃描的。對於這種連結器,函式庫之間的循環引用通常會導致未解析的符號。此特性指示連結器重複搜尋指定的靜態函式庫,直到沒有建立新的未定義引用為止。
通常,靜態函式庫只會按照它在命令列上指定的順序搜尋一次。如果稍後出現在命令列上的函式庫中的物件需要該函式庫中的符號來解析未定義的符號,則連結器將無法解析該引用。透過使用 RESCAN
特性將靜態函式庫分組,將會重複搜尋它們,直到解析所有可能的引用。這將會使用諸如 --start-group
和 --end-group
之類的連結器選項,或者在 SunOS 上使用 -z rescan-start
和 -z rescan-end
。
使用此特性會產生顯著的效能成本。最好只在兩個或多個靜態函式庫之間存在不可避免的循環引用時才使用它。
當使用以 Linux、BSD 和 SunOS 為目標的工具鏈時,此特性可用。如果使用 GNU 工具鏈,也可以在以 Windows 平台為目標時使用。
內建和自訂群組特性是根據以下變數定義的:
每個變數所使用的值是在建立目標的目錄範圍結束時設定的值。用法如下:
如果特定於語言的 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
變數為 true,則 feature
必須由對應的 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
變數定義。
如果沒有支援特定於語言的 feature
,則 CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
變數必須為 true,且 feature
必須由對應的 CMAKE_LINK_GROUP_USING_<FEATURE>
變數定義。
LINK_GROUP
產生器表達式與 LINK_LIBRARY
產生器表達式相容。可以使用 LINK_LIBRARY
產生器表達式來指定群組中涉及的函式庫。
在連結步驟中涉及的每個目標或外部函式庫都允許成為多個群組的一部分,但前提是所有涉及的群組都指定相同的 feature
。此類群組不會在連結器命令列上合併,各個群組仍會保留。禁止對同一個目標或函式庫混合使用不同的群組特性。
add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
add_library(lib4 ...)
add_library(lib5 ...)
target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
# lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
# Both groups specify the same feature, so this is fine.
target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
# An error will be raised here because both lib1 and lib3 are part of two
# groups with different features.
當目標或外部函式庫作為群組的一部分參與連結步驟,同時又不是任何群組的一部分時,任何非群組連結項目的出現都會被其所屬的群組取代。
add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
add_library(lib4 ...)
target_link_libraries(lib3 PUBLIC lib1)
target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
# lib4 will only be linked with lib3 and the group {lib1,lib2}
由於 lib1
是為 lib4
定義的群組的一部分,因此該群組隨後會被應用回 lib3
對 lib1
的使用。最終結果將如同為 lib3
指定的連結關係如下:
target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
請注意,群組優先於非群組連結項目的順序可能會導致群組之間出現循環相依性。如果發生這種情況,則會引發嚴重錯誤,因為群組不允許循環相依性。
add_library(lib1A ...)
add_library(lib1B ...)
add_library(lib2A ...)
add_library(lib2B ...)
add_library(lib3 ...)
# Non-group linking relationships, these are non-circular so far
target_link_libraries(lib1A PUBLIC lib2A)
target_link_libraries(lib2B PUBLIC lib1B)
# The addition of these groups creates circular dependencies
target_link_libraries(lib3 PRIVATE
"$<LINK_GROUP:feat,lib1A,lib1B>"
"$<LINK_GROUP:feat,lib2A,lib2B>"
)
由於為 lib3
定義的群組,lib1A
和 lib2B
的連結關係實際上會擴展到等效於:
target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
這會在群組之間建立循環相依性:lib1A --> lib2B --> lib1A
。
還應注意以下限制: