mirror of
https://github.com/Kitware/CMake.git
synced 2025-10-14 02:08:27 +08:00
CheckLinkerFlag: Update documentation
- Added intro code block showing how to include this module. - Added a list of variables that can affect the check. The CMAKE_REQUIRED_LINK_OPTIONS is skipped as it is currently internally overridden by the module's check command. - Added examples section. - Described command arguments as a list. - Added included section describing the `LINKER:` (and `SHELL:`) prefix. - Added link to the module in target_link_options() docs.
This commit is contained in:
Peter Kokot
@@ -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.
|
||||
|
||||
@@ -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>)
|
||||
|
||||
Check that the link ``<flag>`` is accepted by the ``<lang>`` compiler without
|
||||
a diagnostic. Stores the result in an internal cache entry named ``<var>``.
|
||||
This command checks once whether the linker flag ``<flag>`` is accepted
|
||||
by the ``<lang>`` 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.
|
||||
``<lang>``
|
||||
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_<LANG>_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.
|
||||
|
||||
``<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_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)
|
||||
|
||||
Reference in New Issue
Block a user