.. _cxx20_modules_support:

C++20 Modules Support

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

|short_name| provides a C++20 module interface unit, tbb.cppm, that lets you use |short_name| 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 <https://cmake.org/cmake/help/latest/manual/cmake-cxxmodules.7.html>_ for the list of supported compilers and generators.

.. code:: cmake

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:

.. literalinclude:: ./examples/cxx20_module_example.cpp :language: c++ :prepend: import tbb; :start-after: /* begin_cxx20_modules_basic_example / :end-before: / end_cxx20_modules_basic_example */

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

Enabling Preview Features

|short_name| 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:

.. code:: cmake

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 |short_name| 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.

.. literalinclude:: ./examples/cxx20_module_example.cpp :language: c++ :start-after: /* begin_cxx20_modules_macro_example / :end-before: / end_cxx20_modules_macro_example */