CheckLinkerFlag

在 3.18 版本中新增。

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

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

include(CheckLinkerFlag)

命令

此模块提供以下命令

check_linker_flag

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

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

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

参数为

<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。还将自动添加对检查命令的 result variable 参数指定的名称的定义。

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 变量的值给出。

例如，对于 Clang，"LINKER:-z,defs" 会变成 -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()

另请参阅