CheckLinkerFlag

在 3.18 版被加入.

This module provides a command to check whether a given link flag is supported by the compiler.

在 CMake 專案中使用以下命令載入該模組：

include(CheckLinkerFlag)

命令

This module provides the following command:

check_linker_flag

Checks once whether the compiler supports a given link flag:

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

This command checks once whether the linker flag <flag> is accepted by the <lang> compiler without producing a diagnostic message.

The arguments are:

<lang>

The language of the compiler used for the check. Supported languages are C, CXX, CUDA, Fortran, HIP, OBJC, OBJCXX, and Swift.

在 3.19 版被加入: Support for CUDA language.

在 3.21 版被加入: Support for HIP language.

在 3.26 版被加入: Support for Swift language.

<flag>

Linker flag(s) to check. Multiple flags can be specified in one argument as a string using a semicolon-separated list.

The underlying implementation uses the LINK_OPTIONS target property to test the specified flag. The LINKER: (and SHELL:) prefixes may be used, as described in the Handling Compiler Driver Differences section.

<variable>

The name of the variable to store the check result. This variable will be created as an internal cache variable.

This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable and calls the check_source_compiles() command from the CheckSourceCompiles module.

A successful result only indicates that the compiler did not report an error when given the link flag. Whether the flag has any effect, or the intended one, is outside the scope of this module.

備註

Since the underlying try_compile() command also uses flags from variables like CMAKE_<LANG>_FLAGS, unknown or unsupported flags in those variables may result in a false negative for this check.

影響檢查的變數

可以在呼叫此命令之前設定以下變數，以修改檢查的執行方式：

CMAKE_REQUIRED_FLAGS

一個以空格分隔的字串，包含要傳遞給編譯器的額外旗標。分號分隔列表將無法運作。CMAKE_<LANG>_FLAGS 及其關聯的特定組態 CMAKE_<LANG>_FLAGS_<CONFIG> 變數的內容會在該變數的內容之前自動預置到編譯器命令中。

CMAKE_REQUIRED_DEFINITIONS

一個編譯器定義的分號分隔列表，每個定義的形式為 -DFOO 或 -DFOO=bar。由檢查命令的結果變數引數所指定的名稱的定義也會自動新增。

CMAKE_REQUIRED_INCLUDES

一個要傳遞給編譯器的標頭搜尋路徑的分號分隔列表。這些將是唯一使用的標頭搜尋路徑；INCLUDE_DIRECTORIES 目錄屬性的內容將被忽略。

CMAKE_REQUIRED_LIBRARIES

一個要新增到連結命令的程式庫的分號分隔列表。這些可以是系統程式庫的名稱，也可以是 Imported Targets`（詳情請參見 :command:`try_compile）。

CMAKE_REQUIRED_LINK_DIRECTORIES

在 3.31 版被加入.

一個要傳遞給連結器的程式庫搜尋路徑的分號分隔列表（詳情請參見 try_compile()）。

CMAKE_REQUIRED_QUIET

在 3.1 版被加入.

如果此變數的值為布林真值，則與檢查相關的所有狀態訊息都將被抑制。

Handling Compiler Driver Differences

To pass options to the linker tool, each compiler driver has its own syntax. The LINKER: prefix and , separator can be used to specify, in a portable way, options to pass to the linker tool. LINKER: is replaced by the appropriate driver option and , by the appropriate driver separator. The driver prefix and driver separator are given by the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for Clang and -Wl,-z,defs for GNU GCC.

The LINKER: prefix can be specified as part of a SHELL: prefix expression.

The LINKER: prefix supports, as an alternative syntax, specification of arguments using the SHELL: prefix and space as separator. The previous example then becomes "LINKER:SHELL:-z defs".

備註

Specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix is not supported.

範例

Example: Checking Linker Flag

The following example shows how to use this module to check the -z relro linker flag, which is supported on many Unix-like systems to enable read-only relocations for improved binary security. If the flag is supported by the linker, it is conditionally added to the executable target using the target_link_options(). The LINKER: prefix is used to pass the flag to the linker in a portable and compiler-independent way.

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()

Example: Checking Multiple Flags

In the following example, multiple linker flags are checked simultaneously:

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()

另請參見

  • The CMAKE_LINKER_TYPE variable to specify the linker, which will be used also by this module.

  • The CheckCompilerFlag module to check whether a compiler flag is supported.