1CMAKE-COMPILE-FEATURES(7)            CMake           CMAKE-COMPILE-FEATURES(7)
2
3
4

NAME

6       cmake-compile-features - CMake Compile Features Reference
7

INTRODUCTION

9       Project source code may depend on, or be conditional on, the availabil‐
10       ity of certain features of the compiler.   There  are  three  use-cases
11       which  arise:  Compile  Feature Requirements, Optional Compile Features
12       and Conditional Compilation Options.
13
14       While features are typically specified in  programming  language  stan‐
15       dards,  CMake  provides a primary user interface based on granular han‐
16       dling of the features, not the language standard  that  introduced  the
17       feature.
18
19       The      CMAKE_C_KNOWN_FEATURES,     CMAKE_CUDA_KNOWN_FEATURES,     and
20       CMAKE_CXX_KNOWN_FEATURES global properties  contain  all  the  features
21       known  to  CMake,  regardless of compiler support for the feature.  The
22       CMAKE_C_COMPILE_FEATURES,     CMAKE_CUDA_COMPILE_FEATURES     ,     and
23       CMAKE_CXX_COMPILE_FEATURES  variables  contain all features CMake knows
24       are known to the compiler, regardless of language standard  or  compile
25       flags needed to use them.
26
27       Features  known to CMake are named mostly following the same convention
28       as the Clang feature test macros.  There are some exceptions,  such  as
29       CMake  using cxx_final and cxx_override instead of the single cxx_over‐
30       ride_control used by Clang.
31
32       Note that there are no separate compile features  properties  or  vari‐
33       ables  for  the OBJC or OBJCXX languages.  These are based off C or C++
34       respectively, so the properties and variables for  their  corresponding
35       base language should be used instead.
36

COMPILE FEATURE REQUIREMENTS

38       Compile  feature  requirements  may  be  specified with the target_com‐
39       pile_features() command.  For example, if a  target  must  be  compiled
40       with compiler support for the cxx_constexpr feature:
41
42          add_library(mylib requires_constexpr.cpp)
43          target_compile_features(mylib PRIVATE cxx_constexpr)
44
45       In  processing  the requirement for the cxx_constexpr feature, cmake(1)
46       will ensure that the in-use C++ compiler is capable of the feature, and
47       will  add any necessary flags such as -std=gnu++11 to the compile lines
48       of C++ files in the mylib target.  A FATAL_ERROR is issued if the  com‐
49       piler is not capable of the feature.
50
51       The exact compile flags and language standard are deliberately not part
52       of the user interface for this use-case.  CMake will compute the appro‐
53       priate  compile  flags to use by considering the features specified for
54       each target.
55
56       Such compile flags are added even if the compiler supports the particu‐
57       lar  feature  without  the flag. For example, the GNU compiler supports
58       variadic templates (with a  warning)  even  if  -std=gnu++98  is  used.
59       CMake adds the -std=gnu++11 flag if cxx_variadic_templates is specified
60       as a requirement.
61
62       In the above example, mylib requires cxx_constexpr when it is built it‐
63       self,  but  consumers of mylib are not required to use a compiler which
64       supports cxx_constexpr.  If the interface of  mylib  does  require  the
65       cxx_constexpr  feature (or any other known feature), that may be speci‐
66       fied with the PUBLIC or  INTERFACE  signatures  of  target_compile_fea‐
67       tures():
68
69          add_library(mylib requires_constexpr.cpp)
70          # cxx_constexpr is a usage-requirement
71          target_compile_features(mylib PUBLIC cxx_constexpr)
72
73          # main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr.
74          add_executable(myexe main.cpp)
75          target_link_libraries(myexe mylib)
76
77       Feature  requirements  are evaluated transitively by consuming the link
78       implementation.  See cmake-buildsystem(7) for more on transitive behav‐
79       ior of build properties and usage requirements.
80
81   Requiring Language Standards
82       In projects that use a large number of commonly available features from
83       a particular  language  standard  (e.g.  C++  11)  one  may  specify  a
84       meta-feature  (e.g.  cxx_std_11)  that  requires use of a compiler mode
85       that is at minimum aware of that standard, but could be greater.   This
86       is  simpler than specifying all the features individually, but does not
87       guarantee the existence of any particular feature.  Diagnosis of use of
88       unsupported features will be delayed until compile time.
89
90       For  example,  if  C++  11 features are used extensively in a project's
91       header files, then clients must use a compiler mode  that  is  no  less
92       than C++ 11.  This can be requested with the code:
93
94          target_compile_features(mylib PUBLIC cxx_std_11)
95
96       In this example, CMake will ensure the compiler is invoked in a mode of
97       at-least C++ 11 (or  C++  14,  C++  17,  ...),  adding  flags  such  as
98       -std=gnu++11  if  necessary.   This  applies to sources within mylib as
99       well as any dependents (that may include headers from mylib).
100
101   Availability of Compiler Extensions
102       The <LANG>_EXTENSIONS target property defaults to  the  compiler's  de‐
103       fault  (see  CMAKE_<LANG>_EXTENSIONS_DEFAULT).  Note  that because most
104       compilers enable extensions by default,  this  may  expose  portability
105       bugs in user code or in the headers of third-party dependencies.
106
107       <LANG>_EXTENSIONS used to default to ON. See CMP0128.
108

OPTIONAL COMPILE FEATURES

110       Compile features may be preferred if available, without creating a hard
111       requirement.   This can be achieved by  not  specifying  features  with
112       target_compile_features()  and  instead checking the compiler capabili‐
113       ties with preprocessor conditions in project code.
114
115       In this use-case, the project may wish to establish a  particular  lan‐
116       guage  standard  if  available  from the compiler, and use preprocessor
117       conditions to detect the features actually available.  A language stan‐
118       dard  may  be  established  by  Requiring Language Standards using tar‐
119       get_compile_features() with meta-features like cxx_std_11, or  by  set‐
120       ting the CXX_STANDARD target property or CMAKE_CXX_STANDARD variable.
121
122       See  also  policy  CMP0120 and legacy documentation on Example Usage of
123       the deprecated WriteCompilerDetectionHeader module.
124

CONDITIONAL COMPILATION OPTIONS

126       Libraries may provide entirely different header files depending on  re‐
127       quested compiler features.
128
129       For example, a header at with_variadics/interface.h may contain:
130
131          template<int I, int... Is>
132          struct Interface;
133
134          template<int I>
135          struct Interface<I>
136          {
137            static int accumulate()
138            {
139              return I;
140            }
141          };
142
143          template<int I, int... Is>
144          struct Interface
145          {
146            static int accumulate()
147            {
148              return I + Interface<Is...>::accumulate();
149            }
150          };
151
152       while a header at no_variadics/interface.h may contain:
153
154          template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
155          struct Interface
156          {
157            static int accumulate() { return I1 + I2 + I3 + I4; }
158          };
159
160       It  may be possible to write an abstraction interface.h header contain‐
161       ing something like:
162
163          #ifdef HAVE_CXX_VARIADIC_TEMPLATES
164          #include "with_variadics/interface.h"
165          #else
166          #include "no_variadics/interface.h"
167          #endif
168
169       However this could be unmaintainable if there are  many  files  to  ab‐
170       stract.  What  is  needed is to use alternative include directories de‐
171       pending on the compiler capabilities.
172
173       CMake provides a COMPILE_FEATURES  generator  expression  to  implement
174       such  conditions.   This  may  be used with the build-property commands
175       such as target_include_directories() and target_link_libraries() to set
176       the appropriate buildsystem properties:
177
178          add_library(foo INTERFACE)
179          set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
180          set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
181          target_include_directories(foo
182            INTERFACE
183              "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
184              "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
185            )
186
187       Consuming  code  then  simply links to the foo target as usual and uses
188       the feature-appropriate include directory
189
190          add_executable(consumer_with consumer_with.cpp)
191          target_link_libraries(consumer_with foo)
192          set_property(TARGET consumer_with CXX_STANDARD 11)
193
194          add_executable(consumer_no consumer_no.cpp)
195          target_link_libraries(consumer_no foo)
196

SUPPORTED COMPILERS

198       CMake is currently aware of the  C++  standards  and  compile  features
199       available  from the following compiler ids as of the versions specified
200       for each:
201
202AppleClang: Apple Clang for Xcode versions 4.4+.
203
204Clang: Clang compiler versions 2.9+.
205
206GNU: GNU compiler versions 4.4+.
207
208MSVC: Microsoft Visual Studio versions 2010+.
209
210SunPro: Oracle SolarisStudio versions 12.4+.
211
212Intel: Intel compiler versions 12.1+.
213
214       CMake is currently aware of the C standards and compile features avail‐
215       able  from  the following compiler ids as of the versions specified for
216       each:
217
218       • all compilers and versions listed above for C++.
219
220GNU: GNU compiler versions 3.4+
221
222       CMake is currently aware of the  C++  standards  and  their  associated
223       meta-features  (e.g.  cxx_std_11) available from the following compiler
224       ids as of the versions specified for each:
225
226Cray: Cray Compiler Environment version 8.1+.
227
228Fujitsu: Fujitsu HPC compiler 4.0+.
229
230PGI: PGI version 12.10+.
231
232NVHPC: NVIDIA HPC compilers version 11.0+.
233
234TI: Texas Instruments compiler.
235
236XL: IBM XL version 10.1+.
237
238       CMake is currently aware  of  the  C  standards  and  their  associated
239       meta-features (e.g. c_std_99) available from the following compiler ids
240       as of the versions specified for each:
241
242       • all compilers and versions listed above with only  meta-features  for
243         C++.
244
245       CMake  is  currently  aware  of the CUDA standards and their associated
246       meta-features (e.g. cuda_std_11) available from the following  compiler
247       ids as of the versions specified for each:
248
249Clang: Clang compiler 5.0+.
250
251NVIDIA: NVIDIA nvcc compiler 7.5+.
252
254       2000-2022 Kitware, Inc. and Contributors
255
256
257
258
2593.22.2                           Jan 25, 2022        CMAKE-COMPILE-FEATURES(7)
Impressum