指定要連結到目標的函式庫群組,以及定義應如何連結該群組的 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
定義的群組的一部分,因此該群組隨後會應用回 lib1
用於 lib3
的情況。最終結果將如同 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
。
還應注意以下限制