Compatibility

This library provides an advanced target_compile_features() and write_compiler_detection_header(). The problem with those is that they are controlled via a CMake internal database, which has to be kept manually up-to-date. This version uses check_cxx_source_compiles() instead and is such automatically up-to-date - a compiler supports a feature, if the test code compiles.

Based on the test results, a header file is generated that stores the result and often workaround code, for example a CONSTEXPR macro that is constexpr, if supported, and const otherwise, to use the features anyway.

It also provides the automatic standard deduction from target_compile_features() to activate the right standard.

Example

If you only want the C++ standard activation, simply include() comp_base.cmake and replace target_compile_features() by comp_compile_features().

This is a CMakeLists.txt for a more advanced usage:

# suppose we have a target 'tgt'
include(your/dir/to/comp_base.cmake) # only file you need to download, rest is taken as needed

# we want constexpr, noexcept, std::max_align_t and rtti_support
# instead of cpp11_lang/constexpr and cpp11_lang/noexcept, you could also write cxx_constexpr/cxx_noexcept
comp_target_features(tgt PUBLIC cpp11_lang/constexpr cpp11_lang/noexcept cpp11_lib/max_align_t env/rtti_support)

For convenience we include all generated files in a header named config.hpp. The filenames are made available through macros.

#ifndef CONFIG_HPP
#define CONFIG_HPP

#include COMP_CONSTEXPR_HEADER
#include COMP_NOEXCEPT_HEADER
#include COMP_MAX_ALIGN_T_HEADER
#include COMP_RTTI_SUPPORT_HEADER

#endif

And then we can use it just by including config.hpp in our code:

#include "config.hpp"

// use a workaround macro
COMP_CONSTEXPR int i = 0;

void func() COMP_NOEXCEPT
{
    // use a workaround typedef
    comp::max_align_t foo;

    // or conditional compilation
#if COMP_HAS_RTTI_SUPPORT
    do_sth();
#endif
}

If you don't care about the workarounds, but just want a specific standard, simply call:

comp_target_features(tgt PUBLIC CPP11) # or CPP14 or CPP17

This will only activate C++11/14/17 without doing anything else.

Note: The standard activation is always PRIVATE to allow users of a library to have a different (higher) standard than the library.

Usage

The only file needed is comp_base.cmake. You can either manually download it, use CMakes file(DOWNLOAD facility, or use git submodules. The branch git-submodule only contains comp_base.cmake and is thus perfect for this purpose. Run git submodule add -b "git-submodule" https://github.com/foonathan/compatibility.git to initialize it and fetch the file. Then you only need to run git submodule update --remote to update it to the newest version.

include() it in your CMakeLists.txt now. First it generates CMake options - COMP_CPP11_FLAG, COMP_CPP14_FLAG and COMP_CPP17_FLAG - storing the calculated compiler flag for a given standard, useful if you want to override it, if it can't find one for your compiler. It also provides the following function:

comp_target_features(<target> <PRIVATE|PUBLIC|INTERFACE> <features...>
                     [NOPREFIX | PREFIX <prefix] [NAMESPACE <namespace>]
                     [CMAKE_PATH <path>] [INCLUDE_PATH <include_path>]
                     [NOFLAGS | CPP11 | CPP14 | CPP17] 
                     [LOG <DEBUG | INFO | QUIET | SILENT | ALL>]
                     [NO_HEADER_MACROS] [SINGLE_HEADER <name>])

Ignoring all the other options, it is like target_compile_features(). It takes a list of features to activate for a certain target. A features is a file in this repository without the .cmake extension, e.g. cpp11_lang for all C++11 language features, or cpp14_lang/deprecated for the C++14 deprecated features.

A feature file with name dir/xxx.cmake belonging to a feature dir/xxx consists of the following, where dir is the category of the feature, xxx the feature name in lowercase, XXX the feature name in upper case <PREFIX> the prefix as given to the function, <prefix> the prefix in lowercase and without a trailing underscore:

• a test testing whether or not the compiler supports this feature

• a CMake option with name COMP_HAS_XXX to override its result, useful if you want to act like it doesn't support a feature, or if the test is poorly written (please contact me in this case!)

• a header named <prefix>/xxx.hpp. The header contains at least a macro <PREFIX>HAS_XXX with the same value as the CMake option and often workaround macros or functions that can be used instead of the feature. The workaround uses either the feature, if it is available, or own code. This allows using many new features already, without support. If the compiler gets support, you will be automatically using the native feature or the standard library implementation.

• a globally available macro named <PREFIX>_XXX_HEADER to include the header file.

To use the generated header files, simply write #include <PREFIX>_XXX_HEADER inside your code, the macro is made available automatically (you could also #incluce the file directly but this is not recommended).

What comp_target_features function actually does is the following:

• For each feature, it downloads the latest version of the test file from Github, if it doesn't exist yet. The remote url can be set via the option COMP_REMOTE_URL.

• For each feature, it calls include(feature.cmake) after some set up. This runs the test and generates the header file.

• It calls target_include_directories to allow including the generated header files and target_compile_definitions for the file macro. The INTERFACE/PUBLIC/PRIVATE specifier are only used in these calls.

• Activates the right C++ standard. E.g., if a feature requires C++11, it will be activated if it is available. If it is not, it will only activate the C++ standard required by the workaround code. This activation is always PRIVATE. The flag is exposed through the CACHE variable ${target}_COMP_COMPILE_OPTIONS.

The behavior can be customized with the other options:

• NOPREFIX/PREFIX: The prefix of any generated macros or none if NOPREFIX is set. Default is COMP_.

• NAMESPACE: The namespace name of any generated code, default is comp. A given prefix must always use the same namespace name!

• CMAKE_PATH/INCLUDE_PATH: The download destination for the CMake files/the destination of the generated headers, default is ${CMAKE_BINARY_DIR}/comp.downloaded for cmake and ${CMAKE_BINARY_DIR}/comp.generated for the headers. INCLUDE_PATH is also given to target_include_directories(), but note that the generated headers are in a subfolder <prefix> (this cannot be changed).

• NOFLAGS/CPP11/CPP14/CPP17: Override for the standard detection, if you want to have a newer standard than deduced from the features, or a lower (not recommended). They have priority over the deduction, C++17 over C++14 over C++11. Specify NOFLAGS if you do not want to have any compiler flags set. The latter is useful for INTERFACE libraries which are only there to run the tests and generate the options and headers.

• LOG: Turn down or up the logging for features. There is no default value, but it is fairly verbose by default.

  • Possible options: DEBUG, INFO, QUIET, SILENT, ALL
  • Additionally, setting COMP_LOG_LEVEL at the global level behaves the same way, except any option passed here will override for the current run

• NO_HEADER_MACROS: Disables the definition of the macros that contain the header file location.

• SINGLE_HEADER: Generate a single header file with that name that will include all generated headers.

Feature Reference

A feature named dir/xxx is tested in xxx.cmake, defines an override CMake option COMP_HAS_XXX and a macro <PREFIX>HAS_XXX in a file named <prefix>/xxx.hpp (where prefix is <PREFIX> in lowercase without a trailing underscore), filename also made available over the global macro <PREFIX>XXX_HEADER.

There are also alternative names for the CMake target_compile_features() and SD-6 Feature Test Recommondations that are automatically translated. Where appropriate, it will also generate the SD-6 feature macro as specified. This will override the existing value if the new one is greater or the macro COMP_OVERRIDE_SD6 is defined. If a feature is not supported, it will not change or define anything.

For some features, macros are generated that can be used instead (i.e. for noexcept), they have the form <PREFIX>XXX. Those macros often use compiler extensions. If there is none (or a lacking implementation...), an error message will be emmitted. To prevent this, simply define the macro as no-op or as you want prior to including the file.

There are often workaround functions for library features. Those are defined in a namespace and either use the own implementation or the standard library implementation, if it is available.

Prefix and namespace name can be controlled via parameters, see above. A given prefix must always use the same namespace name on each call.

This library currently tests for the following features. The code below assumes no prefix and a namespace name of comp.

*A feature will only be included (by me) if it is not a pure syntactic feature (like auto or lambdas which can be avoided) but if there is either sensible workaround code, e.g. through to compiler extensions or through reimplementing (small!) standard library functionality, or there can be conditional compilation based on the existense, e.g. optional literal definitions or move constructors.

Note that I'm open to PRs of any kind :)*

C++11 language features

These features are all in the subdirectory cpp11_lang.

Note: In general, it assumes proper C++11 support. The workarounds defined in this library rely on all common C++ features that can not be easily avoided except those listed here with a proper fallback (like noexcept, constexpr, ...).

Get them all by specifying cpp11_lang.

C++11 library features

These features are all in the subdirectory cpp11_lib.

Note: It only checks for minor features where an easy workaround implementation is feasible in the scope of this library.

Get them all by specifying cpp11_lib.

C++14 language features [complete]

These features are all in the subdirectory cpp14_lang.

Get them all by specifying cpp14_lang.

The following features are not and will never be supported:

C++14 library features [complete]

These features are all in the subdirectory cpp14_lib.

Get them all by specifying cpp14_lib.

The following features are not and will never be supported:

C++17 language features

These features are all in the subdirectory cpp17_lang.

C++17 library features [up-to-date]

These features are all in the subdirectory cpp17_lib.

Get them all by specifying cpp17_lib.

The following features are not and will never be supported:

Technical specifications

The technical specifications for the C++ standard library. These features are all in the subdirectory ts.

Get them all by specifying ts.

Environment

Features regarding the general environment. These features are all in the subdirectory env. Note: These checks here aren't that great, it is recommended to set option explicitly.

Get them all by specifying env.

Common extensions

These features are all in the subdirectory ext.

Get them all by specifying ext.cmake.

Contribution

As you probably noted, there are features missing. I wrote this library in a few hours and concentrated on the most important features for me. If you want to extend it or improve a workaround, please don't hesitate to fork and PR (or just write an issue and let me take care of it, when I have time, if you're lazy).

To write a new feature check, just create a new file in the appropriate subdirectory. Note: Do not include comp_base.cmake!.

Inside the feature file you should only use the following CMake functions in the given order:

1. comp_api_version(major[.minor[.patch]]) - checks if the API has the required version. major must match exactly, the rest not higher than the API version. If there is a version mismatch, it is an error.

2. comp_feature(<name> <test_code> <standard> <required...>) - does the feature check. name is the name of the feature without the directory, e.g. constexpr, not cpp11_lang/constexpr. test_code is the code that will be tested to see if the feature is supported. standard is the required C++ standard, this must be one of the COMP_CPPXX_FLAG values or COMP_CPP98_FLAG if no higher standard is needed. required is a list of requirede featuers that need to be supported in order to support this feature. If any of them isn't, this will not be checked.

3. comp_workaround(<name> <workaround_code> <standard> <required...>) - writes workaround code (optional). name must be the same as in comp_feature(). workaround_code is the workaround code itself. It must use ${COMP_PREFIX} for macros and put anything else into the namespace ${COMP_NAMESPACE] (variable expansion works there, so write it exactly like that). The result of the test is available through ${COMP_PREFIX}HAS_NAME, e.g. #if ${COMP_PREFIX}HAS_CONSTEXPR ... #else ... #endif. standard is like in comp_feature() the standard required for the workaround code (the not-supported case, the supported case gets the standard of comp_feature()). required is a list of required features inside the workaround code. Their headers will be included prior to the workaround making it possible to use other workarounds.

4. comp_sd6_macro(<name> <sd6_name> <value>) - writes SD 6 macro (optional, since 1.1). name must be the same as in comp_feature(). sd6_name is the SD-6 macro name and value its value.

5. comp_unit_test(<name> <global_code> <test_code>) - defines a (Catch) unit test for the workaround code (optional). name must be the same as in comp_feature(). global_code will be put into the global namespace right after the including of the appropriate feature header and catch. test_code will be put into a Catch TEST_CASE().

The code for feature checking should be minimal and do not depend on any other advanced features (for example, do not use auto or nullptr) to prevent false failure. The workaround shouldn't use advanced features either, it can use other workarounds though.

The testing code should test the workaround. It will be run by the testing framework for both modes, supported and not supported.

Look at a few other files for example implementations.