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 and CMAKE_CXX_KNOWN_FEATURES global proper‐
20 ties contain all the features known to CMake, regardless of compiler
21 support for the feature. The CMAKE_C_COMPILE_FEATURES and
22 CMAKE_CXX_COMPILE_FEATURES variables contain all features CMake knows
23 are known to the compiler, regardless of language standard or compile
24 flags needed to use them.
25 Features known to CMake are named mostly following the same convention
27 as the Clang feature test macros. The are some exceptions, such as
28 CMake using cxx_final and cxx_override instead of the single cxx_over‐
29 ride_control used by Clang.
30
32 Compile feature requirements may be specified with the target_com‐
33 pile_features() command. For example, if a target must be compiled
34 with compiler support for the cxx_constexpr feature:
35 add_library(mylib requires_constexpr.cpp)
37 target_compile_features(mylib PRIVATE cxx_constexpr)
38 In processing the requirement for the cxx_constexpr feature, cmake(1)
40 will ensure that the in-use C++ compiler is capable of the feature, and
41 will add any necessary flags such as -std=gnu++11 to the compile lines
42 of C++ files in the mylib target. A FATAL_ERROR is issued if the com‐
43 piler is not capable of the feature.
44 The exact compile flags and language standard are deliberately not part
46 of the user interface for this use-case. CMake will compute the appro‐
47 priate compile flags to use by considering the features specified for
48 each target.
49 Such compile flags are added even if the compiler supports the particu‐
51 lar feature without the flag. For example, the GNU compiler supports
52 variadic templates (with a warning) even if -std=gnu++98 is used.
53 CMake adds the -std=gnu++11 flag if cxx_variadic_templates is specified
54 as a requirement.
55 In the above example, mylib requires cxx_constexpr when it is built
57 itself, but consumers of mylib are not required to use a compiler which
58 supports cxx_constexpr. If the interface of mylib does require the
59 cxx_constexpr feature (or any other known feature), that may be speci‐
60 fied with the PUBLIC or INTERFACE signatures of target_compile_fea‐
61 tures():
62 add_library(mylib requires_constexpr.cpp)
64 # cxx_constexpr is a usage-requirement
65 target_compile_features(mylib PUBLIC cxx_constexpr)
66 # main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr.
68 add_executable(myexe main.cpp)
69 target_link_libraries(myexe mylib)
70 Feature requirements are evaluated transitively by consuming the link
72 implementation. See cmake-buildsystem(7) for more on transitive behav‐
73 ior of build properties and usage requirements.
74 Requiring Language Standards
76 In projects that use a large number of commonly available features from
77 a particular language standard (e.g. C++ 11) one may specify a
78 meta-feature (e.g. cxx_std_11) that requires use of a compiler mode
79 aware of that standard. This is simpler than specifying all the fea‐
80 tures individually, but does not guarantee the existence of any partic‐
81 ular feature. Diagnosis of use of unsupported features will be delayed
82 until compile time.
83 For example, if C++ 11 features are used extensively in a project’s
85 header files, then clients must use a compiler mode aware of C++ 11 or
86 above. This can be requested with the code:
87 target_compile_features(mylib PUBLIC cxx_std_11)
89 In this example, CMake will ensure the compiler is invoked in a mode
91 that is aware of C++ 11 (or above), adding flags such as -std=gnu++11
92 if necessary. This applies to sources within mylib as well as any
93 dependents (that may include headers from mylib).
94 Availability of Compiler Extensions
96 Because the CXX_EXTENSIONS target property is ON by default, CMake uses
97 extended variants of language dialects by default, such as -std=gnu++11
98 instead of -std=c++11. That target property may be set to OFF to use
99 the non-extended variant of the dialect flag. Note that because most
100 compilers enable extensions by default, this could expose cross-plat‐
101 form bugs in user code or in the headers of third-party dependencies.
102
104 Compile features may be preferred if available, without creating a hard
105 requirement. For example, a library may provides alternative implemen‐
106 tations depending on whether the cxx_variadic_templates feature is
107 available:
108 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
110 template<int I, int... Is>
111 struct Interface;
112 template<int I>
114 struct Interface<I>
115 {
116 static int accumulate()
117 {
118 return I;
119 }
120 };
121 template<int I, int... Is>
123 struct Interface
124 {
125 static int accumulate()
126 {
127 return I + Interface<Is...>::accumulate();
128 }
129 };
130 #else
131 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
132 struct Interface
133 {
134 static int accumulate() { return I1 + I2 + I3 + I4; }
135 };
136 #endif
137 Such an interface depends on using the correct preprocessor defines for
139 the compiler features. CMake can generate a header file containing
140 such defines using the WriteCompilerDetectionHeader module. The module
141 contains the write_compiler_detection_header function which accepts
142 parameters to control the content of the generated header file:
143 write_compiler_detection_header(
145 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
146 PREFIX Foo
147 COMPILERS GNU
148 FEATURES
149 cxx_variadic_templates
150 )
151 Such a header file may be used internally in the source code of a
153 project, and it may be installed and used in the interface of library
154 code.
155 For each feature listed in FEATURES, a preprocessor definition is cre‐
157 ated in the header file, and defined to either 1 or 0.
158 Additionally, some features call for additional defines, such as the
160 cxx_final and cxx_override features. Rather than being used in #ifdef
161 code, the final keyword is abstracted by a symbol which is defined to
162 either final, a compiler-specific equivalent, or to empty. That way,
163 C++ code can be written to unconditionally use the symbol, and compiler
164 support determines what it is expanded to:
165 struct Interface {
167 virtual void Execute() = 0;
168 };
169 struct Concrete Foo_FINAL {
171 void Execute() Foo_OVERRIDE;
172 };
173 In this case, Foo_FINAL will expand to final if the compiler supports
175 the keyword, or to empty otherwise.
176 In this use-case, the CMake code will wish to enable a particular lan‐
178 guage standard if available from the compiler. The CXX_STANDARD target
179 property variable may be set to the desired language standard for a
180 particular target, and the CMAKE_CXX_STANDARD may be set to influence
181 all following targets:
182 write_compiler_detection_header(
184 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
185 PREFIX Foo
186 COMPILERS GNU
187 FEATURES
188 cxx_final cxx_override
189 )
190 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
192 # which will expand to 'final' if the compiler supports the requested
193 # CXX_STANDARD.
194 add_library(foo foo.cpp)
195 set_property(TARGET foo PROPERTY CXX_STANDARD 11)
196 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
198 # which will expand to 'final' if the compiler supports the feature,
199 # even though CXX_STANDARD is not set explicitly. The requirement of
200 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
201 # affects the compile flags.
202 add_library(foo_impl foo_impl.cpp)
203 target_compile_features(foo_impl PRIVATE cxx_constexpr)
204 The write_compiler_detection_header function also creates compatibility
206 code for other features which have standard equivalents. For example,
207 the cxx_static_assert feature is emulated with a template and
208 abstracted via the <PREFIX>_STATIC_ASSERT and <PRE‐
209 FIX>_STATIC_ASSERT_MSG function-macros.
210
212 Libraries may provide entirely different header files depending on
213 requested compiler features.
214 For example, a header at with_variadics/interface.h may contain:
216 template<int I, int... Is>
218 struct Interface;
219 template<int I>
221 struct Interface<I>
222 {
223 static int accumulate()
224 {
225 return I;
226 }
227 };
228 template<int I, int... Is>
230 struct Interface
231 {
232 static int accumulate()
233 {
234 return I + Interface<Is...>::accumulate();
235 }
236 };
237 while a header at no_variadics/interface.h may contain:
239 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
241 struct Interface
242 {
243 static int accumulate() { return I1 + I2 + I3 + I4; }
244 };
245 It would be possible to write a abstraction interface.h header contain‐
247 ing something like:
248 #include "foo_compiler_detection.h"
250 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
251 #include "with_variadics/interface.h"
252 #else
253 #include "no_variadics/interface.h"
254 #endif
255 However this could be unmaintainable if there are many files to
257 abstract. What is needed is to use alternative include directories
258 depending on the compiler capabilities.
259 CMake provides a COMPILE_FEATURES generator expression to implement
261 such conditions. This may be used with the build-property commands
262 such as target_include_directories() and target_link_libraries() to set
263 the appropriate buildsystem properties:
264 add_library(foo INTERFACE)
266 set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
267 set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
268 target_include_directories(foo
269 INTERFACE
270 "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
271 "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
272 )
273 Consuming code then simply links to the foo target as usual and uses
275 the feature-appropriate include directory
276 add_executable(consumer_with consumer_with.cpp)
278 target_link_libraries(consumer_with foo)
279 set_property(TARGET consumer_with CXX_STANDARD 11)
280 add_executable(consumer_no consumer_no.cpp)
282 target_link_libraries(consumer_no foo)
283
285 CMake is currently aware of the C++ standards and compile features
286 available from the following compiler ids as of the versions specified
287 for each:
288 · AppleClang: Apple Clang for Xcode versions 4.4 though 6.2.
290 · Clang: Clang compiler versions 2.9 through 3.4.
292 · GNU: GNU compiler versions 4.4 through 5.0.
294 · MSVC: Microsoft Visual Studio versions 2010 through 2017.
296 · SunPro: Oracle SolarisStudio versions 12.4 through 12.6.
298 · Intel: Intel compiler versions 12.1 through 17.0.
300 CMake is currently aware of the C standards and compile features avail‐
302 able from the following compiler ids as of the versions specified for
303 each:
304 · all compilers and versions listed above for C++.
306 · GNU: GNU compiler versions 3.4 through 5.0.
308 CMake is currently aware of the C++ standards and their associated
310 meta-features (e.g. cxx_std_11) available from the following compiler
311 ids as of the versions specified for each:
312 · Cray: Cray Compiler Environment version 8.1 through 8.5.8.
314 · PGI: PGI version 12.10 through 17.5.
316 · XL: IBM XL version 10.1 through 13.1.5.
318 CMake is currently aware of the C standards and their associated
320 meta-features (e.g. c_std_99) available from the following compiler ids
321 as of the versions specified for each:
322 · all compilers and versions listed above with only meta-features for
324 C++.
325 CMake is currently aware of the CUDA standards from the following com‐
327 piler ids as of the versions specified for each:
328 · NVIDIA: NVIDIA nvcc compiler 7.5 though 8.0.
330
332 2000-2018 Kitware, Inc. and Contributors
3333.11.4 May 13, 2019 CMAKE-COMPILE-FEATURES(7)