Doc. No.: | N3694 |
---|---|
Date: | 2013-06-27 |
Reply to: | Clark Nelson |
Title: | Feature-testing recommendations for C++ |
The more time that passes without any sort of feature-testing recommendation, the more confusion will affect programmers and implementers interested in features of C++14, of the sort that has plagued C++11 for years. So whatever action should be taken in this arena should not be delayed any more than can be avoided.
SG10 intends to produce its recommendations solely as a WG21 document, without any balloting at higher levels. This is partly to save time, but also to avoid making significant conformance changes. It is hoped that compiler and library implementers will follow these recommendations voluntarily, even without the threat of claims of non-conformance. To improve the chances of that happening, it is considered important to have a record of the endorsement of WG21 – or at least of the C++ technical experts who attend WG21 meetings.
So SG10 would like to bring this document forward for some sort of approval vote at the Chicago meeting. Formally speaking, no action by the committee is requested, so this vote should probably be just a straw poll.
Note that this document recommends that the __has_include
feature be
provided in the C++14 time frame, even though it is not included in the CD for C++14.
A conceivable alternative would be to add __has_include
to C++14 before
its final publication.
This revision of this document contains STUBS for sections expected to be filled in later.
The pace of innovation in the standardization of C++ makes long-term stability of implementations unlikely. Features are added to the language because programmers want to use those features. Features are added to (the working draft of) the standard as the features become well-specified. In many cases a feature is added to an implementation well before or well after the standard officially introducing it is approved.
This process makes it difficult for programmers who want to use a feature to know
whether it is available in any given implementation. Implementations rarely leap
from one formal revision of the standard directly to the next; the implementation
process generally proceeds by smaller steps. As a result, testing for a specific
revision of the standard (e.g. by examining the value of the __cplusplus
macro) often gives the wrong answer. Implementers generally don't want to appear
to be claiming full conformance to a standard revision until all of its features
are implemented. That leaves programmers with no portable way to determine which
features are actually available to them.
It is often possible for a program to determine, in a manner specific to a single implementation, what features are supported by that implementation; but the means are often poorly documented and ad hoc, and sometimes complex – especially when the availability of a feature is controlled by an invocation option. To make this determination for a variety of implementations in a single source base is complex and error-prone.
Here is some code that attempts to determine whether rvalue references are available in the implementation in use:
#ifndef __USE_RVALUE_REFERENCES #if (__GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 3) || \ _MSC_VER >= 1600 #if __EDG_VERSION__ > 0 #define __USE_RVALUE_REFERENCES (__EDG_VERSION__ >= 410) #else #define __USE_RVALUE_REFERENCES 1 #endif #elif __clang__ #define __USE_RVALUE_REFERENCES __has_feature(cxx_rvalue_references) #else #define __USE_RVALUE_REFERENCES 0 #endif #endif
First, the GNU and Microsoft version numbers are checked to see if they are high enough. But then a check is made of the EDG version number, since that front end also has compatibility modes for both those compilers, and defines macros indicating (claimed) compatibility with them. If the feature wasn't implemented in the indicated EDG version, it is assumed that the feature is not available – even though it is possible for a customer of EDG to implement a feature before EDG does.
Fortunately Clang has ways to test specifically for the presence of specific features. But unfortunately, the function-call-like syntax used for such tests won't work with a standard preprocessor, so this fine new feature winds up adding its own flavor of complexity to the mix.
Also note that this code is only the beginning of a real-world solution. A complete solution would need to take into account more compilers, and also command-line option settings specific to various compilers.
To preserve implementers' freedom to add features in the order that makes the most sense for themselves and their customers, implementers should indicate the availability of each separate feature by adding a definition of a macro with the name corresponding to that feature.
Important note: By recommending the use of these macros, WG21 is not making any feature optional; the absence of a definition for the relevant feature-test macro does not make an implementation that lacks a feature conform to a standard that requires the feature. However, if implementers and programmers follow these recommendations, portability of code between real-world implementations should be improved.
To a first approximation, a feature is identified by the WG21 paper in which it is specified, and by which it is introduced into the working draft of the standard. Not every paper introduces a new feature worth a feature-test macro, but every paper that is not just a collection of issue resolutions is considered a candidate; exceptions are explicitly justified.
For C++14, it is preferred for the feature-test macro to be named using some combination of words from the title of the paper. In the future, it is hoped that every paper will include its own recommendations concerning feature-test macro names.
The value specified for a feature-test macro is based on the year and month in which the feature is voted into the working draft. In a case where a feature is subsequently changed in a significant way, but arguably remains the same feature, the value of the macro can be changed to indicate the “revision level” of the specification of the feature. However, in most cases it is expected that the presence of a feature can be determined by the presence of any non-zero macro value; for example:
#if __cpp_binary_literals int const packed_zero_to_three = 0b00011011; #else int const packed_zero_to_three = 0x1B; #endif
To avoid the user's namespace, names of macros for language features are prefixed
by “__cpp_
”; for library features, by “__cpp_lib_
”.
A library feature that doesn't introduce a new header is expected to be defined
by the header(s) that implement the feature.
For the sake of improved portability between partial implementations of various C++ standards, WG21 (the ISO technical committee for the C++ programming language) recommends that implementers and programmers follow the guidelines in this document concerning feature-test macros.
Implementers who provide a new feature should define a macro with the recommended name, in the same circumstances under which the feature is available (for example, taking into account relevant command-line options), to indicate the presence of support for that feature.
Programmers who wish to determine whether a feature is available in an implementation should base that determination on the state of the macro with the recommended name. (The absence of a tested feature may result in a program with decreased functionality, or the relevant functionality may be provided in a different way. A program that strictly depends on support for a feature can just try to use the feature unconditionally; presumably, on an implementation lacking necessary support, translation will fail.)
__has_include
It is impossible for a C++ program to directly, reliably and portably determine whether or not a library header is available for inclusion. Conditionally including a header requires the use of a configuration macro, whose setting can be determined by a configuration-test process at build time (reliable, but less portable), or by some other means (often not reliable or portable).
To solve this general problem, WG21 recommends that implementers provide, and programmers
use, the __has_include
feature.
The following description of this feature is adapted from the Clang 3.4 Language
Extensions documentation on clang.llvm.org
. All references to the related
__has_include_next
feature have been deleted, but otherwise the text
is verbatim. A more formal description of this feature should be expected in a revision
of this document for the pre-Chicago mailing.
Not all development systems have the same include files. The __has_include
macro allows you to check for the existence of an include file before doing a possibly
failing #include
directive. It must be used as an expression in a
#if
or #elif
preprocessing directive.
The __has_include
function-like macro takes a single file name string
argument that is the name of an include file. It evaluates to 1 if the file can
be found using the include paths, or 0 otherwise:
// Note the two possible file name string formats. #if __has_include("myinclude.h") && __has_include(<stdint.h>) # include "myinclude.h" #endif // To avoid problem with compilers not having this macro. #if defined(__has_include) && __has_include("myinclude.h") # include "myinclude.h" #endif
To test for this feature, use #if defined(__has_include)
.
The following table itemizes all the changes that were made to the working draft for C++14 as specified in a WG21 technical document. (Changes that were made as specified in a core or library issue are not included.)
The table is sorted by the section of the standard primarily affected. The “Doc. No.” column links to the paper itself on the committee web site. The “Macro Name” column links to the relevant portion of the “Detailed explanation and rationale” section of this document.
Significant changes to C++14 | |||||
---|---|---|---|---|---|
Doc. No. | Title | Primary Section | Macro Name | Value | Header |
N3472 | Binary Literals in the C++ Core Language | 2.14 | __cpp_binary_literals |
201304 | predefined |
N3323 | A Proposal to Tweak Certain C++ Contextual Conversions | 4 | none | ||
N3648 | Wording Changes for Generalized Lambda-capture | 5.1 | __cpp_init_captures |
201304 | predefined |
N3649 | Generic (Polymorphic) Lambda Expressions | 5.1 | __cpp_generic_lambdas |
201304 | predefined |
N3664 | Clarifying Memory Allocation | 5.3 | none | ||
N3624 | Core Issue 1512: Pointer comparison vs qualification conversions | 5.9, 5.10 | none | ||
N3652 | Relaxing constraints on constexpr functions / constexpr member functions and implicit const | 5.19, 7.1 | __cpp_constexpr |
201304 | predefined |
N3638 | Return type deduction for normal functions | 7.1 | __cpp_decltype_auto |
201304 | predefined |
__cpp_return_type_deduction |
201304 | predefined | |||
N3639 | Runtime-sized arrays with automatic storage duration | 8.3 | __cpp_runtime_arrays |
201304 | predefined |
N3653 | Member initializers and aggregates | 8.5 | __cpp_aggregate_nsdmi |
201304 | predefined |
N3667 | Drafting for Core 1402 | 12.8 | none | ||
N3651 | Variable Templates | 14, 14.7 | __cpp_variable_templates |
201304 | predefined |
N3669 | Fixing constexpr member functions without const | various | none | ||
N3673 | C++ Library Working Group Ready Issues Bristol 2013 | various | none | ||
N3471 | Constexpr Library Additions: utilities | 20.2-20.4 | __cpp_lib_constexpr_functions
|
201210 | <utility> |
N3469 | Constexpr Library Additions: chrono | 20.11 | <chrono> |
||
N3470 | Constexpr Library Additions: containers | 23.3 | <array> |
||
N3658 | Compile-time integer sequences | 20 | __cpp_lib_integer_sequence |
201304 | <utility> |
N3668 | exchange() utility function | 20 | __cpp_lib_exchange_function |
201304 | <utility> |
N3670 | Wording for Addressing Tuples by Type | 20.2-20.4 | __cpp_lib_tuples_by_type |
201304 | <utility> |
N3672 | A proposal to add a utility class to represent optional objects | 20.5 | __has_include(<optional>)
|
1 | predefined |
N3656 | make_unique | 20.7 | __cpp_lib_make_unique |
201304 | <memory> |
N3421 | Making Operator Functors greater<> | 20.8 | __cpp_lib_transparent_operators |
201210 | <functional> |
N3462 | std::result_of and SFINAE | 20.9 | __cpp_lib_result_of_sfinae |
201210 | <functional> |
N3545 | An Incremental Improvement to integral_constant | 20.9 | __cpp_lib_integral_constant_callable |
201304 | <type_traits> |
N3655 | TransformationTraits Redux | 20.9 | __cpp_lib_transformation_trait_aliases |
201304 | <type_traits> |
N3642 | User-defined Literals for Standard Library Types | 20.11 | __cpp_lib_chrono_udls |
201304 | <chrono> |
21.7 | __cpp_lib_string_udls |
201304 | <string> |
||
N3662 | C++ Dynamic Arrays | 23.2, 23.3 | __has_include(<dynarray>)
|
1 | predefined |
N3657 | Adding heterogeneous comparison lookup to associative containers | 23.4 | __cpp_lib_generic_associative_lookup |
201304 | <map> <set> |
N3644 | Null Forward Iterators | 24.2 | __cpp_lib_null_iterators |
201304 | <iterator> |
N3671 | Making non-modifying sequence operations more robust | 25.2 | __cpp_lib_robust_nonmodifying_seq_ops |
201304 | <algorithm> |
N3654 | Quoted Strings Library Proposal | 27.7 | __cpp_lib_quoted_string_io |
201304 | <iomanip> |
N3659 | Shared locking in C++ | 30.4 | __cpp_lib_shared_mutex |
201304 | <mutex> |
STUB: this table should be considered a very rough, preliminary, incomplete draft
Significant features of C++11 | |||||
---|---|---|---|---|---|
Doc. No. | Title | Primary Section | Macro name | Value | Header |
N2249 | New Character Types in C++ | 2.13 | __cpp_unicode_characters |
200704 | predefined |
N2442 | Raw and Unicode String Literals Unified Proposal | 2.13 | __cpp_raw_strings |
200710 | predefined |
__cpp_unicode_literals |
200710 | predefined | |||
N2765 | User-defined Literals | 2.13, 13.5 | __cpp_user_defined_literals |
200809 | predefined |
N2235 | Generalized Constant Expressions | 5.19, 7.1 | __cpp_constexpr |
200704 | predefined |
N2343 | Decltype | 7.1 | __cpp_decltype |
200707 | predefined |
N2761 | Towards support for attributes in C++ | 7.6 | __cpp_attributes |
200809 | predefined |
N2118 | A Proposal to Add an Rvalue Reference to the C++ Language | 8.3 | __cpp_rvalue_reference |
200610 | predefined |
N2242 | Proposed Wording for Variadic Templates | 8.3, 14 | __cpp_variadic_templates |
200704 | predefined |
STUB
STUB: especially for exception handling and RTTI
This paper specifies a small change that is considered to be more of a bug fix than a new feature, so no macro is considered necessary.
These papers specify closely related, textually minor changes to different library headers. It is considered unlikely that they would be applied to an implementation at different times, so one macro is recommended for all three.
This paper contained the wording changes to resolve a core issue. It did not introduce a new feature, so no macro is considered necessary.
This paper describes two separate features: the ability to deduce the return type
of a function from the return statements contained in its body, and the ability
to use decltype(auto)
. These features can be implemented independently,
so a macro is recommended for each.
This paper specifies user-defined literal operators for two different standard library types, which could be implemented independently. Furthermore, user-defined literal operators are expected to be added later for at least one other library type. So for consistency and flexibility, each type is given its own macro.
The major change proposed by this paper is considered to be strictly a further development
of the constexpr
feature of C++11. Consequently, the recommendation
here is to give an increased value to the macro indicating C++11 support for constexpr
.
We have a long-term solution that uses __has_include
. There was not
sufficient support and a number of objections against adding macros to existing
library header files, as there was not consensus on a place to put them.
There is also a simple workaround for users that are not using libraries that define the header file: supplying their own header that is further down the search path than the library headers.
The substantive change in this paper just relaxes a restriction on implementations. There is no new feature for a programmer to use, so no macro is considered necessary.
This paper contained the wording changes to resolve a core issue. It did not introduce a new feature, so no macro is considered necessary.
This paper contained the wording changes to ensure that a minor change proposed by N3652 did not impact the standard library. It did not introduce a new feature, so no macro is considered necessary.
See N3662.
This paper was just a collection of library issues. It did not introduce a new feature, so no macro is considered necessary.