Configuration
CMake Options
These are the options available when building the project with CMake:
| Option | Description | Default |
|---|---|---|
FUTURES_BUILD_INSTALLER |
Build installer target | ON if running CMake from the root directory |
FUTURES_BUILD_PACKAGE |
Build package | ON if running CMake from the root directory |
FUTURES_USE_FIND_PACKAGE |
Do not use find_package to find dependencies | ON if not crosscompiling |
FUTURES_USE_FETCH_CONTENT |
Do not use FetchContent to fetch dependencies | ON if not crosscompiling |
FUTURES_PREFER_STANDALONE_ASIO |
Prefer standalone Asio if available | OFF |
FUTURES_PREFER_BOOST |
Prefer Boost.Asio if available | OFF |
FUTURES_PREFER_BUNDLED |
Prefer bundled dependencies | OFF |
FUTURES_BUILD_WITH_EXCEPTIONS |
Add compiler flags to use exceptions if needed. | ON |
By setting these CMake options, the CMake futures target will already define whatever configuration macros are
necessary.
All dependencies are bundled. Whenever a dependency is not found, the bundled version is used.
Configuration Macros
Set the following macros to define how the library is compiled.
| Option | Description |
|---|---|
FUTURES_HAS_STANDALONE_ASIO |
Macro used to indicate standalone asio is available. |
FUTURES_HAS_BOOST |
Macro used to indicate Boost is available. |
FUTURES_PREFER_STANDALONE_ASIO |
Macro used to indicate we prefer using standalone Asio over Boost.Asio. |
FUTURES_PREFER_BOOST |
Macro used to indicate we prefer using Boost.Asio over standalone Asio. |
FUTURES_SEPARATE_COMPILATION |
Use separately compiled source code for implementation. |
FUTURES_NO_EXCEPTIONS |
Macro used to disable exception handling. |
FUTURES_CUSTOM_EXCEPTION_HANDLE |
Customize exception handling. |
CMake Developer Options
The following options are available only when building the library in developer mode:
| Option | Description | Default |
|---|---|---|
FUTURES_DEVELOPER_MODE |
Enable developer mode | OFF |
BUILD_SHARED_LIBS |
Build shared libs. | OFF |
FUTURES_BUILD_TESTS |
Build tests | ON |
FUTURES_BUILD_SINGLE_TARGET_TESTS |
Build tests | OFF |
FUTURES_BUILD_EXAMPLES |
Build examples | ON |
FUTURES_BUILD_DOCS |
Build documentation | OFF |
FUTURES_BUILD_COVERAGE_REPORT |
Enable coverage support | OFF |
FUTURES_BUILD_LINT |
Enable linting | OFF |
FUTURES_BUILD_LINTER |
Build C++ project linter | ON |
FUTURES_ALWAYS_LINT |
Run the linter before running unit tests | ON if not compiling with MSVC |
FUTURES_PEDANTIC_WARNINGS |
Use pedantic warnings. | ON |
FUTURES_WARNINGS_AS_ERRORS |
Treat warnings as errors. | ON |
FUTURES_SANITIZERS |
Build with sanitizers. | ON if compiling in Debug mode |
FUTURES_THREAD_SANITIZER |
Use thread sanitizer instead of other sanitizers. | OFF |
FUTURES_CATCH2_REPORTER |
Reporter Catch2 should use when invoked from ctest. | console |
FUTURES_TESTS_SMALL_POOL |
Run tests with a default thread pool of size 1. | OFF |
FUTURES_TIME_TRACE |
Enable clang time-trace. | ON |
FUTURES_BUILD_WITH_UTF8 |
Accept utf-8 in MSVC by default. | ON |
Macros
Public configuration macros.
This file defines public configuration macros. These are the macros the user is allowed to define to change how the library is compiled.
FUTURES_HAS_STANDALONE_ASIO
#define FUTURES_HAS_STANDALONE_ASIO
Macro used to indicate standalone asio is available.
Description
This macro can be defined to indicate the standalone version of Asio is available.
If both the standalone and the Boost versions of Asio are available, the standalone version is preferred unless FUTURES_PREFER_BOOST is defined.
If both the standalone and the Boost versions of Asio are unavailable, a bundled version of the subset of Asio required by library is used.
Default value
In C++17, this macro is determined by the availability of the asio.hpp header.
When using the CMake package, the futures target will already define this macro if appropriate.
In all other cases, the macro is undefined by default. If standalone Asio is available, it should be defined manually.
References
FUTURES_HAS_BOOST
#define FUTURES_HAS_BOOST
Macro used to indicate Boost is available.
Description
This macro can be defined to indicate that Boost is available as a dependency.
If both the standalone and the Boost versions of Asio are available, the standalone version is preferred unless FUTURES_PREFER_BOOST is defined.
If both the standalone and the Boost versions of Asio are unavailable, a bundled version of the subset of Boost required by library is used.
Default value
In C++17, this macro is determined by the availability of the asio.hpp header.
When using the CMake package, the futures target will already define this macro if appropriate.
In all other cases, the macro is undefined by default. If standalone Asio is available, it should be defined manually.
References
FUTURES_PREFER_STANDALONE_ASIO
#define FUTURES_PREFER_STANDALONE_ASIO
Macro used to indicate we prefer using standalone Asio over Boost.Asio.
Description
This macro can be defined to indicate that we should prefer standalone Asio over Boost whenever standalone Asio is available.
If both the standalone and the Boost versions of Asio are available, this macro ensure the standalone version is used.
The availability of standalone Asio and Boost.Asio can be indicated with the FUTURES_HAS_STANDALONE_ASIO and FUTURES_HAS_BOOST macros.
Default value
In C++17, this macro is defined whenever FUTURES_HAS_STANDALONE_ASIO is defined and FUTURES_PREFER_BOOST is undefined.
When using the CMake package, the futures target will already define this macro when standalone Asio is available.
In all other cases, the macro is undefined by default. If standalone Asio is available, it should be defined manually.
If both FUTURES_HAS_STANDALONE_ASIO and FUTURES_HAS_BOOST are undefined, a bundled subset of Boost dependencies required by the library is used.
References
FUTURES_PREFER_BOOST
#define FUTURES_PREFER_BOOST
Macro used to indicate we prefer using Boost.Asio over standalone Asio.
Description
This macro can be defined to indicate that we should prefer Boost.Asio over standalone Asio over Boost whenever standalone Boost is available.
If both the standalone and the Boost versions of Asio are available, this macro ensure the Boost version is used.
The availability of standalone Asio and Boost.Asio can be indicated with the FUTURES_HAS_STANDALONE_ASIO and FUTURES_HAS_BOOST macros.
Default value
In C++17, this macro is defined whenever FUTURES_HAS_BOOST is defined and FUTURES_PREFER_STANDALONE_ASIO is undefined.
When using the CMake package, the futures target will already define this macro when standalone Asio is unavailable.
In all other cases, the macro is undefined by default. If Boost is available, it should be defined manually.
If both FUTURES_HAS_STANDALONE_ASIO and FUTURES_HAS_BOOST are undefined, a bundled subset of Boost dependencies required by the library is used.
References
FUTURES_SEPARATE_COMPILATION
#define FUTURES_SEPARATE_COMPILATION
Use separately compiled source code for implementation.
Description
By default, Futures is a header-only library.
To reduce compile times, users can also build the library using separately compiled source code.
If the library is integrated with CMake, the appropriate macros should already define the appropriate macros for separate compilation.
To do this without a build system, add #include <futures/impl/src.hpp> to one (and only one) source file of your program, then build the program with FUTURES_SEPARATE_COMPILATION defined in the project\/compiler settings.
When using this library with Asio, this option is independent of the ASIO_SEPARATE_COMPILATION or BOOST_ASIO_SEPARATE_COMPILATION options. FUTURES_SEPARATE_COMPILATION only implies in BOOST_ASIO_SEPARATE_COMPILATION when both standalone Asio and Boost.Asio are unavailable and the bundled version of Asio is used.
FUTURES_NO_EXCEPTIONS
#define FUTURES_NO_EXCEPTIONS
Macro used to disable exception handling.
Description
This macro can be defined to indicate that the library should not throw exceptions.
When exceptions are disabled, the library might call std::terminate or a user-defined function.
Default value
The macro will be automatically defined if lack of exception support is detected.
FUTURES_CUSTOM_EXCEPTION_HANDLE
FUTURES_CUSTOM_EXCEPTION_HANDLE
#define FUTURES_CUSTOM_EXCEPTION_HANDLE
Customize exception handling.
Description
If FUTURES_NO_EXCEPTIONS is defined, this macro can be defined to indicate that the library should use a custom user function to handle exceptions.
The function futures::handle_exception should be defined to determine how exceptions will be handled.
Default value
This macro is undefined by default.