1 .\" Man page generated from reStructuredText.

     2 .

     3 .TH "CMAKE-COMPILE-FEATURES" "7" "October 14, 2015" "3.3.2" "CMake"

     4 .SH NAME

     5 cmake-compile-features \- CMake Compile Features Reference

     6 .

     7 .nr rst2man-indent-level 0

     8 .

     9 .de1 rstReportMargin

    10 \\$1 \\n[an-margin]

    11 level \\n[rst2man-indent-level]

    12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

    13 -

    14 \\n[rst2man-indent0]

    15 \\n[rst2man-indent1]

    16 \\n[rst2man-indent2]

    17 ..

    18 .de1 INDENT

    19 .\" .rstReportMargin pre:

    20 . RS \\$1

    21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

    22 . nr rst2man-indent-level +1

    23 .\" .rstReportMargin post:

    24 ..

    25 .de UNINDENT

    26 . RE

    27 .\" indent \\n[an-margin]

    28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

    29 .nr rst2man-indent-level -1

    30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

    31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u

    32 ..

    33 .SH INTRODUCTION

    34 .sp

    35 Project source code may depend on, or be conditional on, the availability

    36 of certain features of the compiler.  There are three use\-cases which arise:

    37 \fI\%Compile Feature Requirements\fP, \fI\%Optional Compile Features\fP

    38 and \fI\%Conditional Compilation Options\fP\&.

    39 .sp

    40 While features are typically specified in programming language standards,

    41 CMake provides a primary user interface based on granular handling of

    42 the features, not the language standard that introduced the feature.

    43 .sp

    44 The \fBCMAKE_C_KNOWN_FEATURES\fP and

    45 \fBCMAKE_CXX_KNOWN_FEATURES\fP global properties contain all the

    46 features known to CMake, regardless of compiler support for the feature.

    47 The \fBCMAKE_C_COMPILE_FEATURES\fP and

    48 \fBCMAKE_CXX_COMPILE_FEATURES\fP variables contain all features

    49 CMake knows are known to the compiler, regardless of language standard

    50 or compile flags needed to use them.

    51 .sp

    52 Features known to CMake are named mostly following the same convention

    53 as the Clang feature test macros.  The are some exceptions, such as

    54 CMake using \fBcxx_final\fP and \fBcxx_override\fP instead of the single

    55 \fBcxx_override_control\fP used by Clang.

    56 .SH COMPILE FEATURE REQUIREMENTS

    57 .sp

    58 Compile feature requirements may be specified with the

    59 \fBtarget_compile_features()\fP command.  For example, if a target must

    60 be compiled with compiler support for the

    61 \fBcxx_constexpr\fP feature:

    62 .INDENT 0.0

    63 .INDENT 3.5

    64 .sp

    65 .nf

    66 .ft C

    67 add_library(mylib requires_constexpr.cpp)

    68 target_compile_features(mylib PRIVATE cxx_constexpr)

    69 .ft P

    70 .fi

    71 .UNINDENT

    72 .UNINDENT

    73 .sp

    74 In processing the requirement for the \fBcxx_constexpr\fP feature,

    75 \fBcmake(1)\fP will ensure that the in\-use C++ compiler is capable

    76 of the feature, and will add any necessary flags such as \fB\-std=gnu++11\fP

    77 to the compile lines of C++ files in the \fBmylib\fP target.  A

    78 \fBFATAL_ERROR\fP is issued if the compiler is not capable of the

    79 feature.

    80 .sp

    81 The exact compile flags and language standard are deliberately not part

    82 of the user interface for this use\-case.  CMake will compute the

    83 appropriate compile flags to use by considering the features specified

    84 for each target.

    85 .sp

    86 Such compile flags are added even if the compiler supports the

    87 particular feature without the flag. For example, the GNU compiler

    88 supports variadic templates (with a warning) even if \fB\-std=gnu++98\fP is

    89 used.  CMake adds the \fB\-std=gnu++11\fP flag if \fBcxx_variadic_templates\fP

    90 is specified as a requirement.

    91 .sp

    92 In the above example, \fBmylib\fP requires \fBcxx_constexpr\fP when it

    93 is built itself, but consumers of \fBmylib\fP are not required to use a

    94 compiler which supports \fBcxx_constexpr\fP\&.  If the interface of

    95 \fBmylib\fP does require the \fBcxx_constexpr\fP feature (or any other

    96 known feature), that may be specified with the \fBPUBLIC\fP or

    97 \fBINTERFACE\fP signatures of \fBtarget_compile_features()\fP:

    98 .INDENT 0.0

    99 .INDENT 3.5

   100 .sp

   101 .nf

   102 .ft C

   103 add_library(mylib requires_constexpr.cpp)

   104 # cxx_constexpr is a usage\-requirement

   105 target_compile_features(mylib PUBLIC cxx_constexpr)

   106 

   107 # main.cpp will be compiled with \-std=gnu++11 on GNU for cxx_constexpr.

   108 add_executable(myexe main.cpp)

   109 target_link_libraries(myexe mylib)

   110 .ft P

   111 .fi

   112 .UNINDENT

   113 .UNINDENT

   114 .sp

   115 Feature requirements are evaluated transitively by consuming the link

   116 implementation.  See \fBcmake\-buildsystem(7)\fP for more on

   117 transitive behavior of build properties and usage requirements.

   118 .sp

   119 Because the \fBCXX_EXTENSIONS\fP target property is \fBON\fP by default,

   120 CMake uses extended variants of language dialects by default, such as

   121 \fB\-std=gnu++11\fP instead of \fB\-std=c++11\fP\&.  That target property may be

   122 set to \fBOFF\fP to use the non\-extended variant of the dialect flag.  Note

   123 that because most compilers enable extensions by default, this could

   124 expose cross\-platform bugs in user code or in the headers of third\-party

   125 dependencies.

   126 .SH OPTIONAL COMPILE FEATURES

   127 .sp

   128 Compile features may be preferred if available, without creating a hard

   129 requirement.  For example, a library may provides alternative

   130 implementations depending on whether the \fBcxx_variadic_templates\fP

   131 feature is available:

   132 .INDENT 0.0

   133 .INDENT 3.5

   134 .sp

   135 .nf

   136 .ft C

   137 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES

   138 template<int I, int... Is>

   139 struct Interface;

   140 

   141 template<int I>

   142 struct Interface<I>

   143 {

   144   static int accumulate()

   145   {

   146     return I;

   147   }

   148 };

   149 

   150 template<int I, int... Is>

   151 struct Interface

   152 {

   153   static int accumulate()

   154   {

   155     return I + Interface<Is...>::accumulate();

   156   }

   157 };

   158 #else

   159 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>

   160 struct Interface

   161 {

   162   static int accumulate() { return I1 + I2 + I3 + I4; }

   163 };

   164 #endif

   165 .ft P

   166 .fi

   167 .UNINDENT

   168 .UNINDENT

   169 .sp

   170 Such an interface depends on using the correct preprocessor defines for the

   171 compiler features.  CMake can generate a header file containing such

   172 defines using the \fBWriteCompilerDetectionHeader\fP module.  The

   173 module contains the \fBwrite_compiler_detection_header\fP function which

   174 accepts parameters to control the content of the generated header file:

   175 .INDENT 0.0

   176 .INDENT 3.5

   177 .sp

   178 .nf

   179 .ft C

   180 write_compiler_detection_header(

   181   FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"

   182   PREFIX Foo

   183   COMPILERS GNU

   184   FEATURES

   185     cxx_variadic_templates

   186 )

   187 .ft P

   188 .fi

   189 .UNINDENT

   190 .UNINDENT

   191 .sp

   192 Such a header file may be used internally in the source code of a project,

   193 and it may be installed and used in the interface of library code.

   194 .sp

   195 For each feature listed in \fBFEATURES\fP, a preprocessor definition

   196 is created in the header file, and defined to either \fB1\fP or \fB0\fP\&.

   197 .sp

   198 Additionally, some features call for additional defines, such as the

   199 \fBcxx_final\fP and \fBcxx_override\fP features. Rather than being used in

   200 \fB#ifdef\fP code, the \fBfinal\fP keyword is abstracted by a symbol

   201 which is defined to either \fBfinal\fP, a compiler\-specific equivalent, or

   202 to empty.  That way, C++ code can be written to unconditionally use the

   203 symbol, and compiler support determines what it is expanded to:

   204 .INDENT 0.0

   205 .INDENT 3.5

   206 .sp

   207 .nf

   208 .ft C

   209 struct Interface {

   210   virtual void Execute() = 0;

   211 };

   212 

   213 struct Concrete Foo_FINAL {

   214   void Execute() Foo_OVERRIDE;

   215 };

   216 .ft P

   217 .fi

   218 .UNINDENT

   219 .UNINDENT

   220 .sp

   221 In this case, \fBFoo_FINAL\fP will expand to \fBfinal\fP if the

   222 compiler supports the keyword, or to empty otherwise.

   223 .sp

   224 In this use\-case, the CMake code will wish to enable a particular language

   225 standard if available from the compiler. The \fBCXX_STANDARD\fP

   226 target property variable may be set to the desired language standard

   227 for a particular target, and the \fBCMAKE_CXX_STANDARD\fP may be

   228 set to influence all following targets:

   229 .INDENT 0.0

   230 .INDENT 3.5

   231 .sp

   232 .nf

   233 .ft C

   234 write_compiler_detection_header(

   235   FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"

   236   PREFIX Foo

   237   COMPILERS GNU

   238   FEATURES

   239     cxx_final cxx_override

   240 )

   241 

   242 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol

   243 # which will expand to \(aqfinal\(aq if the compiler supports the requested

   244 # CXX_STANDARD.

   245 add_library(foo foo.cpp)

   246 set_property(TARGET foo PROPERTY CXX_STANDARD 11)

   247 

   248 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol

   249 # which will expand to \(aqfinal\(aq if the compiler supports the feature,

   250 # even though CXX_STANDARD is not set explicitly.  The requirement of

   251 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which

   252 # affects the compile flags.

   253 add_library(foo_impl foo_impl.cpp)

   254 target_compile_features(foo_impl PRIVATE cxx_constexpr)

   255 .ft P

   256 .fi

   257 .UNINDENT

   258 .UNINDENT

   259 .sp

   260 The \fBwrite_compiler_detection_header\fP function also creates compatibility

   261 code for other features which have standard equivalents.  For example, the

   262 \fBcxx_static_assert\fP feature is emulated with a template and abstracted

   263 via the \fB<PREFIX>_STATIC_ASSERT\fP and \fB<PREFIX>_STATIC_ASSERT_MSG\fP

   264 function\-macros.

   265 .SH CONDITIONAL COMPILATION OPTIONS

   266 .sp

   267 Libraries may provide entirely different header files depending on

   268 requested compiler features.

   269 .sp

   270 For example, a header at \fBwith_variadics/interface.h\fP may contain:

   271 .INDENT 0.0

   272 .INDENT 3.5

   273 .sp

   274 .nf

   275 .ft C

   276 template<int I, int... Is>

   277 struct Interface;

   278 

   279 template<int I>

   280 struct Interface<I>

   281 {

   282   static int accumulate()

   283   {

   284     return I;

   285   }

   286 };

   287 

   288 template<int I, int... Is>

   289 struct Interface

   290 {

   291   static int accumulate()

   292   {

   293     return I + Interface<Is...>::accumulate();

   294   }

   295 };

   296 .ft P

   297 .fi

   298 .UNINDENT

   299 .UNINDENT

   300 .sp

   301 while a header at \fBno_variadics/interface.h\fP may contain:

   302 .INDENT 0.0

   303 .INDENT 3.5

   304 .sp

   305 .nf

   306 .ft C

   307 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>

   308 struct Interface

   309 {

   310   static int accumulate() { return I1 + I2 + I3 + I4; }

   311 };

   312 .ft P

   313 .fi

   314 .UNINDENT

   315 .UNINDENT

   316 .sp

   317 It would be possible to write a abstraction \fBinterface.h\fP header

   318 containing something like:

   319 .INDENT 0.0

   320 .INDENT 3.5

   321 .sp

   322 .nf

   323 .ft C

   324 #include "foo_compiler_detection.h"

   325 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES

   326 #include "with_variadics/interface.h"

   327 #else

   328 #include "no_variadics/interface.h"

   329 #endif

   330 .ft P

   331 .fi

   332 .UNINDENT

   333 .UNINDENT

   334 .sp

   335 However this could be unmaintainable if there are many files to

   336 abstract. What is needed is to use alternative include directories

   337 depending on the compiler capabilities.

   338 .sp

   339 CMake provides a \fBCOMPILE_FEATURES\fP

   340 \fBgenerator expression\fP to implement

   341 such conditions.  This may be used with the build\-property commands such as

   342 \fBtarget_include_directories()\fP and \fBtarget_link_libraries()\fP

   343 to set the appropriate \fBbuildsystem\fP

   344 properties:

   345 .INDENT 0.0

   346 .INDENT 3.5

   347 .sp

   348 .nf

   349 .ft C

   350 add_library(foo INTERFACE)

   351 set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)

   352 set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)

   353 target_include_directories(foo

   354   INTERFACE

   355     "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"

   356     "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"

   357   )

   358 .ft P

   359 .fi

   360 .UNINDENT

   361 .UNINDENT

   362 .sp

   363 Consuming code then simply links to the \fBfoo\fP target as usual and uses

   364 the feature\-appropriate include directory

   365 .INDENT 0.0

   366 .INDENT 3.5

   367 .sp

   368 .nf

   369 .ft C

   370 add_executable(consumer_with consumer_with.cpp)

   371 target_link_libraries(consumer_with foo)

   372 set_property(TARGET consumer_with CXX_STANDARD 11)

   373 

   374 add_executable(consumer_no consumer_no.cpp)

   375 target_link_libraries(consumer_no foo)

   376 .ft P

   377 .fi

   378 .UNINDENT

   379 .UNINDENT

   380 .SH SUPPORTED COMPILERS

   381 .sp

   382 CMake is currently aware of the \fBlanguage standards\fP

   383 and \fBcompile features\fP available from

   384 the following \fBcompiler ids\fP as of the

   385 versions specified for each:

   386 .INDENT 0.0

   387 .IP \(bu 2

   388 \fBAppleClang\fP: Apple Clang for Xcode versions 4.4 though 6.2.

   389 .IP \(bu 2

   390 \fBClang\fP: Clang compiler versions 2.9 through 3.4.

   391 .IP \(bu 2

   392 \fBGNU\fP: GNU compiler versions 4.4 through 5.0.

   393 .IP \(bu 2

   394 \fBMSVC\fP: Microsoft Visual Studio versions 2010 through 2015.

   395 .IP \(bu 2

   396 \fBSunPro\fP: Oracle SolarisStudio version 12.4.

   397 .UNINDENT

   398 .SH COPYRIGHT

   399 2000-2015 Kitware, Inc.

   400 .\" Generated by docutils manpage writer.

   401 .