Integrating feature-test macros into the C++ WD

Preface

This revision of this paper is a hastily-prepared starting point, describing proposed directions for incorporating feature-test macros into the working draft of the C++ standard.

Obviously, its life started by incorporating the text of SD-6. I have deleted all the rationale and examples for individual features, and written this new preface. Other than that, virtually all the changes are added editorial notes suggesting what should be done with the text that follows; this is mainly to make life easier for both the reader and the author.

Contents

1. Introduction
2. Explanation and rationale for the approach
   1. Problem statement
   2. Status quo
   3. Characteristics of the proposed solution
3. Recommendations
   1. Introduction
   2. Testing for the presence of a header: __has_include
   3. Testing for the presence of an attribute: __has_cpp_attribute
   4. C++17 features
   5. C++14 features
   6. C++11 features
   7. C++98 features
   8. Features published and later removed
4. Annex: Recommendations from Technical Specifications
5. Annex: Model wording for a Technical Specification
6. Revision history

Introduction

There would be no point in adding this, or anything like it, to the WD.

At the September 2013 (Chicago) meeting of WG21, there was a five-way poll of all of the C++ experts in attendance – approximately 80 – concerning their support for the approach described herein for feature-testing in C++. The results of the poll:

General support for these recommendations was reaffirmed at the 2015 October (Kona) meeting, as indicated by the following straw poll:

Should WG21 encourage, but not require, feature-test macros for proposals?

Strongly favor	Favor	Neutral	Against	Strongly against
50	13	7	3	2

This document was subsequently designated WG21's SD-6 (sixth standing document), which will continue to be maintained by SG10.

Explanation and rationale for the approach

Probably some parts of this section should become a new informative annex.

Problem statement

Some of this may make sense in the annex, or it may be better to rewrite it.

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.

Status quo

This section should probably not be added to the WD.

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.

Characteristics of the proposed solution

This section should probably be incorporated into the informative annex much as it is, although it's easy to imagine that it could be improved by tweaks and additions.

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, the feature-test macro name generally consists of 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 is 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:

template<typename T>
struct use_empty_base_opt :
	std::integral_constant<bool, 
		std::is_empty<T>::value
#if __cpp_lib_is_final
		&& !std::is_final<T>::value
#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.

Recommendations

Most of this section should become a new normative annex.

Introduction

This section would have to be modified to describe requirements (“shall”) instead of recommendations (“should”).

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 standard feature should define a macro with the recommended name and value, 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. Therefore, if the most useful purpose for a feature-test macro would be to control the inclusion of a #error directive if the feature is unavailable, that is considered inadequate justification for the macro. Note that the usefulness of a test macro for a feature is completely independent of the usefulness of the feature itself.)

Testing for the presence of a header: __has_include

This section was already incorporated into C++17, so it should be ignored.

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.

Syntax

h-preprocessing-token:

any preprocessing-token other than >

h-pp-tokens:

h-preprocessing-token

h-pp-tokens h-preprocessing-token

has-include-expression:

__has_include ( header-name )

__has_include ( string-literal )

__has_include ( < h-pp-tokens > )

Semantics

In the first form of the has-include-expression, the parenthesized header-name token is not subject to macro expansion. The second and third forms are considered only if the first form does not match, and the preprocessing tokens are processed just as in normal text.

A has-include-expression shall appear only in the controlling constant expression of a #if or #elif directive ([cpp.cond] 16.1). Prior to the evaluation of such an expression, the source file identified by the parenthesized preprocessing token sequence in each contained has-include-expression is searched for as if that preprocessing token sequence were the pp-tokens in a #include directive, except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of a #include directive, the program is ill-formed. The has-include-expression is replaced by the pp-number 1 if the search for the source file succeeds, and by the pp-number 0 if the search fails.

The #ifdef and #ifndef directives, and the defined conditional inclusion operator, shall treat __has_include as if it were the name of a defined macro. The identifier __has_include shall not appear in any context not mentioned in this section.

Example

This demonstrates a way to use a library optional facility only if it is available.

#ifdef __has_include
#  if __has_include(<optional>)
#    include <optional>
#    define have_optional 1
#  elif __has_include(<experimental/optional>)
#    include <experimental/optional>
#    define have_optional 1
#    define experimental_optional
#  else
#    define have_optional 0
#  endif
#endif

Testing for the presence of an attribute: __has_cpp_attribute

This section should be incorporated into the description of the preprocessor.

A C++ program cannot directly, reliably, and portably determine whether or not a standard or vendor-specific attribute is available for use. Testing for attribute support generally requires complex macro logic, as illustrated above for language features in general.

To solve this general problem, WG21 recommends that implementers provide, and programmers use, the __has_cpp_attribute feature.

Syntax

has-attribute-expression:

__has_cpp_attribute ( attribute-token )

Semantics

A has-attribute-expression shall appear only in the controlling constant expression of a #if or #elif directive ([cpp.cond] 16.1). The has-attribute-expression is replaced by a non-zero pp-number if the implementation supports an attribute with the specified name, and by the pp-number 0 otherwise.

For a standard attribute, the value of the __has_cpp_attribute macro is based on the year and month in which the attribute was voted into the working draft. In the case where the attribute is vendor-specific, the value is implementation-defined. However, in most cases it is expected that the availability of an attribute can be detected by any non-zero result.

The #ifdef and #ifndef directives, and the defined conditional inclusion operator, shall treat __has_cpp_attribute as if it were the name of a defined macro. The identifier __has_cpp_attribute shall not appear in any context not mentioned in this section.

Example

This demonstrates a way to use the attribute [[deprecated]] only if it is available.

#ifndef __has_cpp_attribute
# define __has_cpp_attribute(x) 0
#endif
#if __has_cpp_attribute(deprecated)
# define ATTR_DEPRECATED(msg) [[deprecated(msg)]]
#else
# define ATTR_DEPRECATED(msg)
#endif

C++17 features

This paragraph probably isn't needed in the WD.

The following table itemizes all the changes that were made to the working draft for C++17 as specified in a WG21 technical document. (Changes that were made as specified in a core or library issue are not generally included.)

Whether the "Primary Section" column should appear, how the table should be sorted, and what links should be included in the WD, are all editorial questions that will need to be decided.

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” annex of this document. When the recommendation is to change the value of a macro previously recommended to be defined, the “Value” column links to the table entry for the previous recommendation.

The most important change here would be that any library macro be defined by including <version>, as well as the header specified in the table.

For library features, the “Header“ column identifies the header that is expected to define the macro, although the macro may also be predefined. For language features, the macro must be predefined.

C++14 features

Ideally, these paragraphs should not be repeated.

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 generally 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” annex of this document. When the recommendation is to change the value of a macro previously recommended to be defined, the “Value” column links to the table entry for the previous recommendation.

For library features, the “Header“ column identifies the header that is expected to define the macro, although the macro may also be predefined. For language features, the macro must be predefined.

Obviously, how far back to go with these tables will be an interesting question. From my perspective, it would be most useful to include all of them.

C++11 features

C++98 features

With very few exceptions, the features of C++98 have all been implemented in virtually every C++ compiler. But in many compilers, some of them can be enabled/disabled. It is recommended that the macros in the following table should be used to indicate whether one of these features is enabled in the current compilation.

Features published and later removed

SG10 considered the stability of these recommendations to be very important, hence these tables. I believe that, going forward with having the macros in the WD, having information about features once included but later removed will still be necessary or desirable. But it may make more sense to have this information in SD-6 instead of the WD.

Features removed from C++17

Features removed from C++14

The intention is that an implementation which provides runtime-sized arrays as specified in the first CD should define __cpp_runtime_arrays as 201304. The expectation is that a later document specifying runtime-sized arrays will specify a different value for __cpp_runtime_arrays.

Annex: Recommendations from Technical Specifications (informative)

These annexes to SD-6 would probably make no sense in the WD.

In this annex, feature-test macros from all WG21 Technical Specifications are collected, for convenience.

C++ Extensions for Library Fundamentals

The recommended macro name is "__cpp_lib_experimental_" followed by the string in the "Macro Name Suffix" column.

C++ Extensions for Parallelism

File System Technical Specification

C++ Extensions for Transactional Memory

The Technical Specification for transactional memory specifies a new attribute, but does not specify a value for a has-attribute-expression for that attribute.

Annex: Model wording for a Technical Specification

It is recommended that Technical Specifications include the wording below. yyyymm indicates the year and month of the date of the TS.

1.x Feature testing [intro.features]

An implementation that provides support for this Technical Specification shall define the feature test macro(s) in Table X.

Table X — Feature Test Macro(s)

Name	Value	Header
__cpp_name	yyyymm	“predefined” OR “<name>”

Revision history