# CheckLinkerFlag

Added 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`.

    Added in version 3.19: Support for `CUDA` language.

    Added in version 3.21: Support for `HIP` language.

    Added 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`

    Added 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`

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