CheckLinkerFlag

New in version 3.18.

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

Load this module in a CMake project with:

include(CheckLinkerFlag)

Commands

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.

New in version 3.19: Support for CUDA language.

New in version 3.21: Support for HIP language.

New in version 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.

Note

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.

Variables Affecting the Check

The following variables may be set before calling this command to modify the way the check is run:

CMAKE_REQUIRED_FLAGS

A space-separated string of additional flags to pass to the compiler. A semicolon-separated list will not work. The contents of CMAKE_<LANG>_FLAGS and its associated configuration-specific CMAKE_<LANG>_FLAGS_<CONFIG> variables are automatically prepended to the compiler command before the contents of this variable.

CMAKE_REQUIRED_DEFINITIONS

A semicolon-separated list of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically.

CMAKE_REQUIRED_INCLUDES

A semicolon-separated list of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES directory property will be ignored.

CMAKE_REQUIRED_LIBRARIES

A semicolon-separated list of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets (see try_compile() for further details).

CMAKE_REQUIRED_LINK_DIRECTORIES

New in version 3.31.

A semicolon-separated list of library search paths to pass to the linker (see try_compile() for further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed.

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".

Note

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

Examples

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

See Also

  • 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.