CheckLinkerFlag

在 3.18 版本中新增。

此模块提供了一个命令，用于检查编译器是否支持给定的链接器标志。

在 CMake 项目中加载此模块，使用

include(CheckLinkerFlag)

命令

此模块提供以下命令

check_linker_flag

检查编译器是否支持给定的链接器标志（仅检查一次）

check_linker_flag(<lang> <flag> <variable>)

此命令检查一次 <lang> 编译器是否接受链接器标志 <flag>，且不产生诊断消息。

参数为

<lang>

用于检查的编译器的语言。支持的语言有 C、CXX、CUDA、Fortran、HIP、OBJC、OBJCXX 和 Swift。

版本 3.19 中新增： 支持 CUDA 语言。

版本 3.21 新增：支持 HIP 语言。

版本 3.26 新增：支持 Swift 语言。

<flag>

要检查的链接器标志。多个标志可以在一个参数中指定为使用分号分隔列表的字符串。

底层实现使用 LINK_OPTIONS 目标属性来测试指定的标志。LINKER: (和 SHELL:) 前缀可以使用，如 处理编译器驱动器差异 部分所述。

<variable>

用于存储检查结果的变量名称。此变量将被创建为内部缓存变量。

此命令临时设置 CMAKE_REQUIRED_LINK_OPTIONS 变量，并调用 check_source_compiles() 命令，该命令来自 CheckSourceCompiles 模块。

成功的检查结果仅表示编译器在给定链接器标志时未报告错误。标志是否有效或是否达到预期效果，则不在此模块的范围之内。

注意

由于底层的 try_compile() 命令也使用 CMAKE_<LANG>_FLAGS 等变量中的标志，因此这些变量中未知或不支持的标志可能会导致此检查出现假阴性。

影响检查的变量

在调用此命令之前，可以设置以下变量来修改检查的运行方式

CMAKE_REQUIRED_FLAGS

一个空格分隔的字符串，包含要传递给编译器的附加标志。分号分隔列表将不起作用。CMAKE_<LANG>_FLAGS 及其关联的特定配置的 CMAKE_<LANG>_FLAGS_<CONFIG> 变量的内容会自动添加到编译器命令之前，然后才是此变量的内容。

CMAKE_REQUIRED_DEFINITIONS

一个分号分隔列表的编译器定义，每个定义的形式为 -DFOO 或 -DFOO=bar。用于检查命令结果变量参数指定的名称的定义也会自动添加。

CMAKE_REQUIRED_INCLUDES

要传递给编译器的头文件搜索路径的分号分隔列表。这些将是唯一使用的头文件搜索路径；INCLUDE_DIRECTORIES 目录属性的内容将被忽略。

CMAKE_REQUIRED_LIBRARIES

一个分号分隔列表，包含要添加到链接命令中的库。它们可以是系统库的名称，也可以是导入目标（更多详情请参阅 try_compile()）。

CMAKE_REQUIRED_LINK_DIRECTORIES

在版本 3.31 中添加。

一个分号分隔列表，包含要传递给链接器的库搜索路径（更多详情请参阅 try_compile()）。

CMAKE_REQUIRED_QUIET

版本 3.1 中新增。

如果此变量评估为布尔真值，则与检查关联的所有状态消息都将被抑制。

处理编译器驱动器差异

要将选项传递给链接器工具，每个编译器驱动程序都有其自己的语法。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: 前缀。

示例

示例：检查链接器标志

以下示例展示了如何使用此模块检查 -z relro 链接器标志，该标志在许多类 Unix 系统上受支持，可启用只读重定位以提高二进制安全性。如果链接器支持该标志，则使用 target_link_options() 有条件地将其添加到可执行目标。LINKER: 前缀用于以可移植且与编译器无关的方式将标志传递给链接器。

include(CheckLinkerFlag)

check_linker_flag(C "LINKER:-z,relro" HAVE_Z_RELRO)

add_executable(example main.c)

if(HAVE_Z_RELRO)
  target_link_options(example PRIVATE "LINKER:-z,relro")
endif()

示例：检查多个标志

在下面的示例中，同时检查了多个链接器标志

include(CheckLinkerFlag)

check_linker_flag(C "LINKER:-z,relro;LINKER:-z,now" HAVE_FLAGS)

add_executable(example main.c)

if(HAVE_FLAGS)
  target_link_options(example PRIVATE LINKER:-z,relro LINKER:-z,now)
endif()

另请参阅