1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file LICENSE.rst or https://cmake.org/licensing for details.
#[=======================================================================[.rst:
CheckLinkerFlag
---------------
.. versionadded:: 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:
.. 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> <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_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.
* The :module:`CheckCompilerFlag` module to check whether a compiler flag
is supported.
#]=======================================================================]
include_guard(GLOBAL)
include(Internal/CheckLinkerFlag)
function(CHECK_LINKER_FLAG _lang _flag _var)
cmake_check_linker_flag(${_lang} "${_flag}" ${_var})
endfunction()
|
