1CMAKE-COMPILE-FEATURES(7) CMake CMAKE-COMPILE-FEATURES(7)
2
6 cmake-compile-features - CMake Compile Features Reference
7
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 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 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 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 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
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 add_library(mylib requires_constexpr.cpp)
43 target_compile_features(mylib PRIVATE cxx_constexpr)
44 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 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 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 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 add_library(mylib requires_constexpr.cpp)
70 # cxx_constexpr is a usage-requirement
71 target_compile_features(mylib PUBLIC cxx_constexpr)
72 # 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 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 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 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 target_compile_features(mylib PUBLIC cxx_std_11)
95 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 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 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 <LANG>_EXTENSIONS used to default to ON. See CMP0128.
115
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 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 See also policy CMP0120 and legacy documentation on Example Usage of
131 the deprecated WriteCompilerDetectionHeader module.
132
134 Libraries may provide entirely different header files depending on re‐
135 quested compiler features.
136 For example, a header at with_variadics/interface.h may contain:
138 template<int I, int... Is>
140 struct Interface;
141 template<int I>
143 struct Interface<I>
144 {
145 static int accumulate()
146 {
147 return I;
148 }
149 };
150 template<int I, int... Is>
152 struct Interface
153 {
154 static int accumulate()
155 {
156 return I + Interface<Is...>::accumulate();
157 }
158 };
159 while a header at no_variadics/interface.h may contain:
161 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 It may be possible to write an abstraction interface.h header contain‐
169 ing something like:
170 #ifdef HAVE_CXX_VARIADIC_TEMPLATES
172 #include "with_variadics/interface.h"
173 #else
174 #include "no_variadics/interface.h"
175 #endif
176 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 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 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 Consuming code then simply links to the foo target as usual and uses
196 the feature-appropriate include directory
197 add_executable(consumer_with consumer_with.cpp)
199 target_link_libraries(consumer_with foo)
200 set_property(TARGET consumer_with CXX_STANDARD 11)
201 add_executable(consumer_no consumer_no.cpp)
203 target_link_libraries(consumer_no foo)
204
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 • AppleClang: Apple Clang for Xcode versions 4.4+.
211 • Clang: Clang compiler versions 2.9+.
213 • GNU: GNU compiler versions 4.4+.
215 • MSVC: Microsoft Visual Studio versions 2010+.
217 • SunPro: Oracle SolarisStudio versions 12.4+.
219 • Intel: Intel compiler versions 12.1+.
221 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 • all compilers and versions listed above for C++.
227 • GNU: GNU compiler versions 3.4+
229 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 • Cray: Cray Compiler Environment version 8.1+.
235 • Fujitsu: Fujitsu HPC compiler 4.0+.
237 • PGI: PGI version 12.10+.
239 • NVHPC: NVIDIA HPC compilers version 11.0+.
241 • TI: Texas Instruments compiler.
243 • XL: IBM XL version 10.1+.
245 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 • all compilers and versions listed above with only meta-features for
251 C++.
252 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 • Clang: Clang compiler 5.0+.
258 • NVIDIA: NVIDIA nvcc compiler 7.5+.
260
262 2000-2023 Kitware, Inc. and Contributors
2633.25.2 Jan 19, 2023 CMAKE-COMPILE-FEATURES(7)