diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 07ef7e972b..cbbd7201fb 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -66,3 +66,6 @@ See Also * :variable:`CMAKE__FLAGS` and :variable:`CMAKE__FLAGS_` add language-wide flags passed to all invocations of the compiler. This includes invocations that drive compiling and those that drive linking. + +* The :module:`CheckLinkerFlag` module to check whether a linker flag is + supported by the compiler. diff --git a/Modules/CheckLinkerFlag.cmake b/Modules/CheckLinkerFlag.cmake index ca37ab56a1..1639aad6cf 100644 --- a/Modules/CheckLinkerFlag.cmake +++ b/Modules/CheckLinkerFlag.cmake @@ -7,34 +7,141 @@ CheckLinkerFlag .. versionadded:: 3.18 -Check whether the compiler supports a given link flag. +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: + +.. code-block:: cmake + + include(CheckLinkerFlag) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_linker_flag + Checks once whether the compiler supports a given link flag: + .. code-block:: cmake - check_linker_flag( ) + check_linker_flag( ) -Check that the link ```` is accepted by the ```` compiler without -a diagnostic. Stores the result in an internal cache entry named ````. + This command checks once whether the linker flag ```` is accepted + by the ```` compiler without producing a diagnostic message. -This command temporarily sets the ``CMAKE_REQUIRED_LINK_OPTIONS`` variable -and calls the :command:`check_source_compiles` command from the -:module:`CheckSourceCompiles` module. See that module's documentation -for a listing of variables that can otherwise modify the build. + The arguments are: -The underlying implementation relies on the :prop_tgt:`LINK_OPTIONS` property -to check the specified flag. The ``LINKER:`` prefix, as described in the -:command:`target_link_options` command, can be used as well. + ```` + The language of the compiler used for the check. Supported languages are + ``C``, ``CXX``, ``CUDA``, ``Fortran``, ``HIP``, ``OBJC``, ``OBJCXX``, + and ``Swift``. -A positive result from this check indicates only that the compiler did not -issue a diagnostic message when given the link flag. Whether the flag has any -effect or even a specific one is beyond the scope of this module. + .. versionadded:: 3.19 + Support for ``CUDA`` language. -.. note:: - Since the :command:`try_compile` command forwards flags from variables - like :variable:`CMAKE__FLAGS`, unknown flags in such variables may - cause a false negative for this check. + .. versionadded:: 3.21 + Support for ``HIP`` language. + + .. versionadded:: 3.26 + Support for ``Swift`` language. + + ```` + Linker flag(s) to check. Multiple flags can be specified in one + argument as a string using a :ref:`semicolon-separated list + `. + + The underlying implementation uses the :prop_tgt:`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. + + ```` + 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 :command:`check_source_compiles` command from the + :module:`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 :command:`try_compile` command also uses flags from + variables like :variable:`CMAKE__FLAGS`, unknown or unsupported + flags in those variables may result in a false negative for this check. + + .. rubric:: Variables Affecting the Check + + The following variables may be set before calling this command to modify + the way the check is run: + + .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst + + .. include:: /module/include/CMAKE_REQUIRED_DEFINITIONS.rst + + .. include:: /module/include/CMAKE_REQUIRED_INCLUDES.rst + + .. include:: /module/include/CMAKE_REQUIRED_LIBRARIES.rst + + .. include:: /module/include/CMAKE_REQUIRED_LINK_DIRECTORIES.rst + + .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst + +.. include:: /command/include/LINK_OPTIONS_LINKER.rst + +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 +:command:`target_link_options`. The ``LINKER:`` prefix is used to pass the +flag to the linker in a portable and compiler-independent way. + +.. code-block:: cmake + + 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: + +.. code-block:: cmake + + 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 :variable:`CMAKE_LINKER_TYPE` variable to specify the linker, which + will be used also by this module. #]=======================================================================] include_guard(GLOBAL)