Merge topic 'patch-CheckLinkerFlag'

4b0bce12c8 CheckLinkerFlag: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10807

Help/command/target_link_options.rst

@@ -66,3 +66,6 @@ See Also
 * :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
   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.

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(<lang> <flag> <var>)
+    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``.
+
+    .. versionadded:: 3.19
+      Support for ``CUDA`` language.
+
+    .. versionadded:: 3.21
+      Support for ``HIP`` language.
+
+    .. versionadded:: 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 :ref:`semicolon-separated list
+    <CMake Language Lists>`.
+
+    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.
+
+  ``<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 :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_<LANG>_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 that the link ``<flag>`` is accepted by the ``<lang>`` compiler without
-a diagnostic.  Stores the result in an internal cache entry named ``<var>``.
+  check_linker_flag(C "LINKER:-z,relro;LINKER:-z,now" HAVE_FLAGS)
 
-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.
+  add_executable(example main.c)
 
-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.
+  if(HAVE_FLAGS)
+    target_link_options(example PRIVATE LINKER:-z,relro LINKER:-z,now)
+  endif()
 
-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.
+See Also
+^^^^^^^^
 
-.. note::
-  Since the :command:`try_compile` command forwards flags from variables
-  like :variable:`CMAKE_<LANG>_FLAGS`, unknown flags in such variables may
-  cause a false negative for this check.
+* The :variable:`CMAKE_LINKER_TYPE` variable to specify the linker, which
+  will be used also by this module.
 #]=======================================================================]
 
 include_guard(GLOBAL)