# C++20 Modules Support

Note

Support for C++20 modules is experimental and subject to change in future releases.

oneTBB provides a C++20 module interface unit, `tbb.cppm`, that lets you use oneTBB via `import tbb;` instead of regular library headers. The module is installed as a source file under `<install-prefix>/include/oneapi/tbb.cppm` and must be compiled as part of your own build target.

## CMake* Integration

To add the `tbb` module to your CMake* target, locate `tbb.cppm` using the `INTERFACE_INCLUDE_DIRECTORIES` property of the `TBB::tbb` target and register it as a `CXX_MODULES` file set:

Note

To support C++20 modules, CMake* 3.28 or later and a compiler and generator with C++20 modules support are required. Refer to the CMake* documentation for the list of supported compilers and generators.

    cmake_minimum_required(VERSION 3.28)
    project(myapp CXX)

    set(CMAKE_CXX_STANDARD 20)

    find_package(TBB REQUIRED)

    add_executable(my_executable main.cpp)
    target_link_libraries(my_executable PRIVATE TBB::tbb)

    get_target_property(_tbb_include_dir TBB::tbb INTERFACE_INCLUDE_DIRECTORIES)
    target_sources(my_executable PRIVATE
        FILE_SET cxx_modules TYPE CXX_MODULES
        BASE_DIRS ${_tbb_include_dir}
        FILES ${_tbb_include_dir}/oneapi/tbb.cppm
    )

An then in your C++ source files, you can import the module:

    import tbb;
    int main() {
        tbb::parallel_for(0, 100, [](int i) { /* ... */ });
    }

Note

Translation units that use `import tbb;` are ABI-compatible with those that use library headers.

## Enabling Preview Features

oneTBB preview features are gated by `TBB_PREVIEW_*` macros that are normally defined before including TBB headers. With modules, macros defined by the consumer before `import tbb;` cannot affect the module’s already-compiled interface.

To enable a preview feature, define the corresponding macro when compiling `tbb.cppm` itself. In CMake*, use `target_compile_definitions`:

    find_package(TBB REQUIRED)

    add_executable(my_executable main.cpp)
    target_link_libraries(my_executable PRIVATE TBB::tbb)

    get_target_property(_tbb_include_dir TBB::tbb INTERFACE_INCLUDE_DIRECTORIES)
    target_sources(my_executable PRIVATE
        FILE_SET cxx_modules TYPE CXX_MODULES
        BASE_DIRS ${_tbb_include_dir}
        FILES ${_tbb_include_dir}/oneapi/tbb.cppm
    )

    # Enable preview feature X when compiling the target that uses the module
    target_compile_definitions(my_executable PRIVATE TBB_PREVIEW_FEATURE_X=1)

After this, the preview API is included in the compiled module and available to all translation units that use `import tbb;`.

## Usage Of Predefined Macros

C++20 modules do not export preprocessor macros. Macros defined in oneTBB library headers (such as version or feature-test macros) are not available after `import tbb;`.

As a workaround, include the <oneapi/tbb/version.h> header alongside the module import.

Caution

In typical usage with CMake* integration, `tbb.cppm` is compiled as part of your target, so `TBB_PREVIEW_*` macros defined via `target_compile_definitions` are already applied when the module is built. There is no need to redefine them in application source files. In any other scenario, make sure to define the same preview macros both when compiling the module and in your source code to avoid a mismatch.

    // It is assumed that the application is compiled with preview macros predefined
    #include <oneapi/tbb/version.h>  // macros available here
    import tbb;

    static_assert(TBB_VERSION_MAJOR >= 2023, "Major version 2023 or later is required");

    // Feature-test macros are also available
    #ifdef TBB_HAS_FEATURE_X
    // use feature X
    #endif