CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>¶
在 3.24 版本中添加。
此变量定义了在使用 LINK_LIBRARY
生成器表达式时,如何为指定的 <LANG>
链接语言的 <FEATURE>
链接库或框架。要使此变量生效,必须将关联的 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
变量设置为 true。
对于独立于链接语言的特性,应改用 CMAKE_LINK_LIBRARY_USING_<FEATURE>
变量。
特性名称区分大小写,并且只能包含字母、数字和下划线。全大写定义的特性名称保留给 CMake 自身的内置特性(请参阅下面的 预定义特性)。
特性的某些方面可以通过 CMAKE_<LANG>_LINK_LIBRARY_<FEATURE>_ATTRIBUTES
和 CMAKE_LINK_LIBRARY_<FEATURE>_ATTRIBUTES
变量来定义。
功能定义¶
库特性定义是一个包含一个或三个元素的列表
[<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
当指定了 <PREFIX>
和 <SUFFIX>
时,它们分别位于 LINK_LIBRARY
表达式中指定的整个库列表之前和之后,而不是单独针对每个库项。但是,无法保证指定的库列表会保持在一起,因此如果 CMake 为了满足其他约束而重新组织库列表,<PREFIX>
和 <SUFFIX>
可能会出现多次。这意味着像 GNU ld
链接器支持的 --start-group
和 --end-group
这样的结构不能以这种方式使用。应改用 LINK_GROUP
生成器表达式来实现此类结构。
<LIBRARY_EXPRESSION>
用于指定在链接器命令行上为每个库构造相应片段的模式。表达式中可以使用以下占位符
<LIBRARY>
扩展为 CMake 目标的库的完整路径,或者根据其他平台的项目特定值进行扩展(在 Windows 上与<LINK_ITEM>
相同,在其他平台上是库的基本名称)。<LINK_ITEM>
扩展为库在链接器命令行上通常的链接方式。<LIB_ITEM>
扩展为 CMake 目标的库的完整路径,或者在其他情况下,扩展为<LIBRARY_EXPRESSION>
中指定的项本身。
除了上述内容,还可以为路径(CMake 目标和使用文件路径指定的外部库)和一个模式,以及为仅按名称指定的其他项提供另一个模式。可以使用 PATH{}
和 NAME{}
包装器来提供这两种情况的扩展。使用包装器时,两者都必须存在。例如
set(CMAKE_LINK_LIBRARY_USING_weak_library
"PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
)
对于此变量的所有三个元素(<PREFIX>
、<LIBRARY_EXPRESSION>
和 <SUFFIX>
),可以使用 LINKER:
前缀。
为了将选项传递给链接器工具,每个编译器驱动程序都有自己的语法。可以使用 LINKER:
前缀和 ,
分隔符来以可移植的方式指定要传递给链接器工具的选项。LINKER:
被替换为适当的驱动程序选项,,
被替换为适当的驱动程序分隔符。驱动程序前缀和驱动程序分隔符由 CMAKE_<LANG>_LINKER_WRAPPER_FLAG
和 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
变量的值给出。
例如,"LINKER:-z,defs"
对于 Clang
会变成 -Xlinker -z -Xlinker defs
,对于 GNU GCC
会变成 -Wl,-z,defs
。
LINKER:
前缀可以作为 SHELL:
前缀表达式的一部分指定。
LINKER:
前缀支持使用 SHELL:
前缀和空格作为分隔符来指定参数,作为一种替代语法。之前的示例会变成 "LINKER:SHELL:-z defs"
。
注意
不支持在 LINKER:
前缀的开头以外的任何位置指定 SHELL:
前缀。
示例¶
加载整个静态库¶
一个常见的需求是防止链接器丢弃静态库中的任何符号。不同的链接器使用不同的语法来实现这一点。下面的示例展示了如何为某些链接器实现此功能。请注意,这仅用于说明目的。项目应使用内置的 WHOLE_ARCHIVE
特性(请参阅 预定义特性),它提供了此功能的更完整、更健壮的实现。
set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
set(CMAKE_C_LINK_LIBRARY_USING_load_archive
"LINKER:--push-state,--whole-archive"
"<LINK_ITEM>"
"LINKER:--pop-state"
)
elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
else()
# feature not yet supported for the other environments
set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
endif()
add_library(lib1 STATIC ...)
add_library(lib2 SHARED ...)
if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
# The -force_load Apple linker option requires a file name
set(external_lib
"$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
)
target_link_libraries(lib2 PRIVATE
"$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
)
else()
target_link_libraries(lib2 PRIVATE lib1 external)
endif()
CMake 将生成以下链接表达式
AppleClang
:-force_load /path/to/lib1.a -force_load libexternal.a
GNU
:-Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal -Wl,--pop-state
MSVC
:/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
将库链接为弱引用¶
在 macOS 上,可以将库以弱模式链接(库及其所有引用都被标记为弱导入)。对于通过文件路径指定的库和通过名称指定的库,必须使用不同的标志。此约束可以使用 PATH{}
和 NAME{}
包装器来解决。同样,以下示例展示了如何为某些链接器实现此功能,但这仅用于说明目的。项目应使用内置的 WEAK_FRAMEWORK
或 WEAK_LIBRARY
特性(请参阅 预定义特性),它们提供了此功能的更完整、更健壮的实现。
if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
set(CMAKE_LINK_LIBRARY_USING_weak_library
"PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
)
set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
endif()
add_library(lib SHARED ...)
add_executable(main ...)
if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
else()
target_link_libraries(main PRIVATE lib external)
endif()
使用 AppleClang
工具链链接 main
时,CMake 将生成以下链接器命令行片段
-weak_library /path/to/lib -Xlinker -weak-lexternal
.
预定义功能¶
CMake 预定义了以下内置库特性
DEFAULT
此特性对应标准链接,本质上等同于不使用任何特性。它通常仅与
LINK_LIBRARY_OVERRIDE
和LINK_LIBRARY_OVERRIDE_<LIBRARY>
目标属性一起使用。WHOLE_ARCHIVE
在将静态库作为消耗 可执行文件、共享库 和 模块库 的依赖项进行链接时,强制包含静态库的所有成员。此特性仅支持以下平台,并附带说明的限制
Linux。
所有 BSD 变体。
SunOS。
所有 Apple 变体。库必须指定为 CMake 目标名称、库文件名(例如
libfoo.a
)或库文件路径(例如/path/to/libfoo.a
)。由于 Apple 链接器的限制,不能将其指定为纯库名,如foo
,其中foo
不是 CMake 目标。Windows。使用 MSVC 或类似 MSVC 工具链时,MSVC 版本必须大于 1900。
Cygwin。
MSYS。
FRAMEWORK
此选项告诉链接器使用
-framework
链接器选项搜索指定的框架。它只能在 Apple 平台上使用,并且只能与理解该选项的链接器一起使用(即 Xcode 提供的链接器或与之兼容的链接器)。框架可以指定为 CMake 框架目标、裸框架名称或文件路径。如果给出目标,则该目标必须将
FRAMEWORK
目标属性设置为 true。对于文件路径,如果它包含目录部分,则该目录将被添加为框架搜索路径。add_library(lib SHARED ...) target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>") # The constructed linker command line will contain: # -F/path/to -framework my_framework
文件路径必须符合以下模式之一(
*
是通配符,可选部分显示为[...]
)[/path/to/]FwName[.framework]
[/path/to/]FwName.framework/FwName[suffix]
[/path/to/]FwName.framework/Versions/*/FwName[suffix]
请注意,CMake 会识别并自动处理框架目标,即使不使用
$<LINK_LIBRARY:FRAMEWORK,...>
表达式。如果项目希望明确说明,仍然可以使用 CMake 目标,但这不是必需的。使用生成器表达式或不使用生成器表达式时,链接器命令行可能存在一些差异,但最终结果应该相同。另一方面,如果给出文件路径,CMake 会自动识别某些路径,但并非所有情况。项目可能希望使用$<LINK_LIBRARY:FRAMEWORK,...>
来处理文件路径,以明确预期的行为。版本 3.25 中添加:
FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
目标属性以及框架库名称的suffix
现在得到FRAMEWORK
特性的支持。NEEDED_FRAMEWORK
这与
FRAMEWORK
特性类似,但它会强制链接器链接该框架,即使未使用其中的任何符号。它使用-needed_framework
选项,并具有与FRAMEWORK
相同的链接器限制。REEXPORT_FRAMEWORK
这与
FRAMEWORK
特性类似,但它会告诉链接器该框架应可供链接到正在创建的库的客户端使用。它使用-reexport_framework
选项,并具有与FRAMEWORK
相同的链接器限制。WEAK_FRAMEWORK
这与
FRAMEWORK
特性类似,但它会强制链接器将框架及其所有引用标记为弱导入。它使用-weak_framework
选项,并具有与FRAMEWORK
相同的链接器限制。NEEDED_LIBRARY
这与
NEEDED_FRAMEWORK
特性类似,但用于非框架目标或库(仅限 Apple 平台)。它使用适当的-needed_library
或-needed-l
选项,并具有与NEEDED_FRAMEWORK
相同的链接器限制。REEXPORT_LIBRARY
这与
REEXPORT_FRAMEWORK
特性类似,但用于非框架目标或库(仅限 Apple 平台)。它使用适当的-reexport_library
或-reexport-l
选项,并具有与REEXPORT_FRAMEWORK
相同的链接器限制。WEAK_LIBRARY
这与
WEAK_FRAMEWORK
特性类似,但用于非框架目标或库(仅限 Apple 平台)。它使用适当的-weak_library
或-weak-l
选项,并具有与WEAK_FRAMEWORK
相同的链接器限制。