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
39       target_compile_features() command.  For example, if a  target  must  be
40       compiled 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
67       target_compile_features():
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       NOTE:
102          If the compiler's default standard level is at least that of the re‐
103          quested  feature, CMake may omit the -std= flag.  The flag may still
104          be added if the compiler's default extensions mode  does  not  match
105          the  <LANG>_EXTENSIONS  target  property,  or if the <LANG>_STANDARD
106          target property is set.
107
108   Availability of Compiler Extensions
109       The <LANG>_EXTENSIONS target property defaults to  the  compiler's  de‐
110       fault  (see  CMAKE_<LANG>_EXTENSIONS_DEFAULT).  Note  that because most
111       compilers enable extensions by default,  this  may  expose  portability
112       bugs in user code or in the headers of third-party dependencies.
113
114       <LANG>_EXTENSIONS used to default to ON. See CMP0128.
115

OPTIONAL COMPILE FEATURES

117       Compile features may be preferred if available, without creating a hard
118       requirement.   This can be achieved by  not  specifying  features  with
119       target_compile_features()  and  instead checking the compiler capabili‐
120       ties with preprocessor conditions in project code.
121
122       In this use-case, the project may wish to establish a  particular  lan‐
123       guage  standard  if  available  from the compiler, and use preprocessor
124       conditions to detect the features actually available.  A language stan‐
125       dard   may   be  established  by  Requiring  Language  Standards  using
126       target_compile_features() with meta-features  like  cxx_std_11,  or  by
127       setting  the  CXX_STANDARD  target property or CMAKE_CXX_STANDARD vari‐
128       able.
129
130       See also policy CMP0120 and legacy documentation on  Example  Usage  of
131       the deprecated WriteCompilerDetectionHeader module.
132

CONDITIONAL COMPILATION OPTIONS

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

SUPPORTED COMPILERS

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

LANGUAGE STANDARD FLAGS

262       In    order    to    satisfy    requirements    specified    by     the
263       target_compile_features()  command  or  the CMAKE_<LANG>_STANDARD vari‐
264       able, CMake may pass a language standard flag to the compiler, such  as
265       -std=c++11.
266
267       For Visual Studio Generators, CMake cannot precisely control the place‐
268       ment of the language standard flag on the compiler command  line.   For
269       Ninja Generators, Makefile Generators, and Xcode, CMake places the lan‐
270       guage  standard  flag  just  after   the   language-wide   flags   from
271       CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG>.
272
273       Changed  in  version  3.26: The language standard flag is placed before
274       flags    specified    by    other    abstractions    such    as     the
275       target_compile_options()  command.   Prior  to CMake 3.26, the language
276       standard flag was placed after them.
277
278
280       2000-2023 Kitware, Inc. and Contributors
281
282
283
284
2853.27.7                           Oct 07, 2023        CMAKE-COMPILE-FEATURES(7)
Impressum