The project uses CMake* build configuration.

The following controls are available during the configure stage:

TBB_TEST:BOOL - Enable testing (ON by default)
TBB_EXAMPLES:BOOL - Enable build of TBB examples (OFF by default)
TBB_STRICT:BOOL - Treat compiler warnings as errors (ON by default)
TBB_SANITIZE:STRING - Sanitizer parameter, passed to compiler/linker
TBB_SIGNTOOL:FILEPATH - Tool for digital signing, used in post-install step for libraries if provided.
TBB_SIGNTOOL_ARGS:STRING - Additional arguments for TBB_SIGNTOOL, used if TBB_SIGNTOOL is set.
BUILD_SHARED_LIBS:BOOL - Standard CMake variable controlling whether oneTBB is built as shared libraries (ON by default).
           Setting it to OFF produces static archives; this configuration is highly discouraged and is not
           supported. See "Building oneTBB as a Static Library" below.
TBB_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) build (ON by default)
TBB_FIND_PACKAGE - Enable search for external oneTBB using find_package instead of build from sources (OFF by default)
TBBMALLOC_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) memory allocator build (ON by default)
TBBMALLOC_PROXY_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) memory allocator proxy build (requires TBBMALLOC_BUILD. ON by default)
TBB4PY_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) Python module build (OFF by default)
TBB_INSTALL:BOOL - Enable installation (ON by default)
TBB_INSTALL_VARS:BOOL - Enable auto-generated vars installation(packages generated by `cpack` and `make install` will also include the vars script)(OFF by default)
TBB_VALGRIND_MEMCHECK:BOOL - Enable scan for memory leaks using Valgrind (OFF by default)
TBB_DISABLE_HWLOC_AUTOMATIC_SEARCH - Disable HWLOC automatic search by pkg-config tool (OFF by default)
TBB_ENABLE_IPO - Enable Interprocedural Optimization (IPO) during the compilation (ON by default)
TBB_CONTROL_FLOW_GUARD:BOOL - Enable Control Flow Guard (CFG) during the compilation (OFF by default)
TBB_BUILD_APPLE_FRAMEWORKS - Enable the Apple* frameworks instead of dylibs, only available on the Apple platform. (OFF by default)
TBB_FILE_TRIM - Enable __FILE__ trim, replace a build-time full path with a relative path in the debug info and macro __FILE__; use it to make
           reproducible location-independent builds (ON by default)
TBB_VERIFY_DEPENDENCY_SIGNATURE - On Windows* enable verification of signatures for dependencies linked at run-time. (ON by default)
TBB_FUZZ_TESTING:BOOL - Enable fuzz testing (OFF by default)
TCM_BUILD - Enable Thread Composability Manager (TCM) build (ON by default)

To perform an out-of-source build, create a build directory and go there:

mkdir /tmp/my-build
cd /tmp/my-build

cmake <options> <repo_root>

Some useful options:

• -G <generator> - specify particular project generator. See cmake --help for details.
• -DCMAKE_BUILD_TYPE=Debug - specify for Debug build. It is not applicable for multi-config generators, e.g., Microsoft* Visual Studio* generator.

TIP: It is recommended to install the HWLOC* library. See oneTBB documentation for details.

The TBBbind library has three versions: tbbbind, tbbbind_2_0, and tbbbind_2_5. Each of these versions is linked with the corresponding HWLOC* library version:

• tbbbind links with HWLOC 2.x which was built as an archive library on Linux* (.a file) or a static library on Windows* (.lib file)
• tbbbind_2_0 links with HWLOC 2.1–2.4
• tbbbind_2_5 links with HWLOC 2.5 and later

The search for a suitable version of the HWLOC library is enabled by default. If you want to use a specific version of the library, you can specify the path to it manually using the following CMake variables:

• CMAKE_HWLOC_<HWLOC_VER>_LIBRARY_PATH - path to the corresponding HWLOC version shared library on Linux* OS or path to .lib file on Windows* OS
• CMAKE_HWLOC_<HWLOC_VER>_INCLUDE_PATH - path to the corresponding HWLOC version including directory

NOTE: Automatic HWLOC searching requires CMake version 3.6 or higher.

Windows* OS requires an additional variable for correct TBBBind library building:

• CMAKE_HWLOC_<HWLOC_VER>_DLL_PATH - path to the corresponding HWLOC version .dll file.

The HWLOC_VER substring used earlier can be replaced with one of the three values:

• STATIC for the tbbbind library configuration
• 2 for the tbbbind_2_0 library configuration
• 2_5 for the tbbbind_2_5 library configuration

If you specify variables for several TBBBind versions, the building process for all of these versions is performed during a single build session.

TIP

Specify the TBB_DISABLE_HWLOC_AUTOMATIC_SEARCH to turn off the HWLOC library's automatic search.

cmake --build . <options>

Some useful options:

• --target <target> - specific target, "all" is the default.
• --config <Release|Debug> - build configuration, applicable only for multi-config generators, e.g., Visual Studio* generator.

The binaries are placed to ./<compiler-id>_<compiler-ver>_cxx<stdver>_<build-type>. For example, ./gnu_4.8_cxx11_release.

• Intel(R) Compiler. Source Intel(R) C++ Compiler with ia32 and build as usual.
• MSVC. Use switch for generator (e.g., -A Win32 for VS2019) during the configuration stage and then build as usual.
• GCC/Clang. Specify -m32 during the configuration. It can be CXXFLAGS=-m32 cmake .. or cmake -DCMAKE_CXX_FLAGS=-m32 ..
• For any other compiler, which builds for 64-bit by default, specify a 32-bit compiler key during the configuration as above.

NOTE

The following builds require CMake version 3.15 or higher.

• Dynamic linkage with C Runtime Library (CRT). The default behavior can be explicitly specified by setting CMAKE_MSVC_RUNTIME_LIBRARY to MultiThreadedDLL or MultiThreadedDebugDLL.

cmake ..  # dynamic linkage is used by default

cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL ..

cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDebugDLL -DCMAKE_BUILD_TYPE=Debug ..

• Static linkage with CRT. Set CMAKE_MSVC_RUNTIME_LIBRARY to MultiThreaded or MultiThreadedDebug.

cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded ..

cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDebug -DCMAKE_BUILD_TYPE=Debug ..

• Windows OS 10 Universal Windows application build. Set CMAKE_SYSTEM_NAME to WindowsStore and CMAKE_SYSTEM_VERSION to 10.0.

NOTE

Set TBB_NO_APPCONTAINER to ON to apply the /APPCONTAINER:NO option during the compilation (used for testing).

cmake -DCMAKE_SYSTEM_NAME:STRING=WindowsStore -DCMAKE_SYSTEM_VERSION:STRING=10.0 ..

• Universal Windows OS Driver build. Set TBB_WINDOWS_DRIVER to ON and use static linkage with CRT.

cmake -DTBB_WINDOWS_DRIVER=ON -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded ..

cmake -DCMAKE_CXX_COMPILER=icpx -DCMAKE_C_COMPILER=icx -DTBB_TEST=off -DCMAKE_HWLOC_2_5_LIBRARY_PATH=<path_to_hwloc_library_file>/libhwloc.so.15
-DCMAKE_HWLOC_2_5_INCLUDE_PATH=<path_to_hwloc_header_directory> -DCMAKE_INSTALL_PREFIX=<path_to_install_oneTBB>/oneTBB_install ..
make -j8 && make install

NOTE

The library path points to a file, while the include path points to a directory and not to hwloc.h.

To build a test, use the default target all:

cmake --build .

Or use a specific test target:

cmake --build . --target <test> # e.g. test_version

You can run a test by using CTest:

ctest

Or by using the test target:

cmake --build . --target test # currently does not work on Windows* OS

CAUTION

Static linking of oneTBB is highly discouraged and has limited support.

IMPORTANT

oneTBB manages a resource that is owned by the whole program - the machine's hardware threads - so its task scheduler and worker thread pool are intended to be a process-wide singleton.

See Static Linking of oneTBB for the rationale, the features that become unavailable, and the risks of ending up with more than one copy of oneTBB in a process. If you choose this configuration, validating your application is your responsibility.

oneTBB is built as a shared library by default. To build static archives instead, set BUILD_SHARED_LIBS to OFF during the configuration:

mkdir build && cd build
cmake -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install_dir> ..
cmake --build . --parallel
cmake --install .

The configuration step prints the following warning, which is expected:

You are building oneTBB as a static library. This is highly discouraged and such
configuration is not supported. Consider building a dynamic library to avoid
unforeseen issues.

The build produces archives instead of shared libraries:

Setting BUILD_SHARED_LIBS to OFF also changes the following:

CMAKE_POSITION_INDEPENDENT_CODE is set to ON so that the archive can be linked into a shared object. It is only defaulted, so an explicit value specified during the configuration is respected.

The tbbbind proxy libraries are loaded at run time, which a static build does not support, so they are skipped and the configuration step reports TBBBind build targets are disabled due to unsupported environment. As a result, tbb::info and tbb::task_arena::constraints cannot report or apply topology-based constraints. See TBBBind Library Configuration.

tbbmalloc_proxy is not built even though TBBMALLOC_PROXY_BUILD is ON by default. The proxy replaces the memory allocation functions of the C library, which requires a shared library. The scalable allocator is still available through the explicit interfaces, such as tbb::scalable_allocator and scalable_malloc.

oneTBB loads the TCM library dynamically, so a static build cannot coordinate with other threading runtimes through it, regardless of TCM_BUILD or the TCM_ENABLE environment variable.

IPO is applied only to shared library builds, so TBB_ENABLE_IPO=ON has no effect and a static oneTBB may be marginally slower than the shared one.

On Windows* OS, BUILD_SHARED_LIBS controls how oneTBB itself is linked, not how oneTBB links the CRT. To link the CRT statically as well, set CMAKE_MSVC_RUNTIME_LIBRARY. See Windows* OS-Specific Builds.

Consuming a static build works the same way as a shared one. The generated TBBConfig.cmake adds a Threads dependency for static builds, so the platform thread library is linked transitively:

find_package(TBB REQUIRED)
target_link_libraries(my_app PRIVATE TBB::tbb)

See TBBConfig - Integration of Binary Packages for details about the configuration module.

WARNING

Static builds receive only light validation coverage. The tests that depend on HWLOC or on tbbmalloc_proxy are excluded automatically, so a passing ctest run does not indicate the same coverage as it does for a shared build.

mkdir build
cd build
cmake -DTBB_SANITIZE=thread ..  # or -DTBB_SANITIZE=memory or any other sanitizer
make -j
ctest -V

• Valgrind tool executable

mkdir build
cd build
cmake -DTBB_VALGRIND_MEMCHECK=ON ..
make -j memcheck-<test name> # or memcheck-all to scan all tests 

Use Doxygen* to generate oneTBB test specification:

mkdir build
cd build
cmake -DTBB_TEST_SPEC=ON ..
make test_spec

It is a configuration module that is used for the integration of prebuilt oneTBB. It consists of two files (TBBConfig.cmake and TBBConfigVersion.cmake) and can be used via the find_package function.

To use this module in your CMake project:

1. Let CMake know where to search for TBBConfig, e.g. specify the location of TBBConfig.cmake in TBB_DIR (for more details about search paths, see find_package).
2. Use find_package to find oneTBB.
3. Use provided variables and/or imported targets (described below) to work with the found oneTBB.

Example:

add_executable(foo foo.cpp)
find_package(TBB)
target_link_libraries(foo TBB::tbb)

oneTBB components can be passed to find_package after keyword COMPONENTS or REQUIRED. Use basic names of components (tbb, tbbmalloc, etc.).

If components are not specified, then the default set is used: tbb, tbbmalloc, and tbbmalloc_proxy.

If tbbmalloc_proxy is requested, the tbbmalloc component is also added and set as a dependency for tbbmalloc_proxy.

TBBConfig creates imported targets as shared libraries using the following format: TBB::<component>. For example, TBB::tbb or TBB::tbbmalloc.

To search only for release oneTBB version, set TBB_FIND_RELEASE_ONLY to TRUE before calling find_package. This variable helps to avoid simultaneous linkage of release and debug oneTBB versions when CMake configuration is Debug, but a third-party component depends on the release oneTBB version.

Variables set during TBB configuration:

Starting from oneTBB 2021.1, GitHub* release TBBConfig files in the binary packages are located under <tbb-root>/lib/cmake/TBB. For example, TBB_DIR should be set to <tbb-root>/lib/cmake/TBB.

TBBConfig files are automatically created during the build from source code and can be installed together with the library. Also, oneTBB provides a helper function that creates TBBConfig files from predefined templates. See tbb_generate_config in cmake/config_generation.cmake.

The TBB4PY_BUILD Cmake option provides the ability to build a Python module for oneTBB.

• irml - build IPC RML server
• python_build - build oneTBB module for Python

python_build target requirements:

• Python version 3.5 or newer
• SWIG version 3.0.6 or newer

Compile and link options may be specific for certain compilers. This part is handled in cmake/compilers/* files.

Options in TBB CMake are handled via variables in two ways for convenience:

• by options group
• by the specific option

Naming convention is the following: TBB_<SCOPE>_<STAGE>_<CATEGORY>, where:

• <SCOPE> can be:
  • LIB - options applied during libraries build.
  • TEST - options applied during test build.
  • BENCH - options applied during benchmarks build.
  • COMMON - options applied during all (libraries, test, benchmarks) builds.
• <STAGE> can be:
  • COMPILE - options applied during the compilation.
  • LINK - options applied during the linkage.
• <CATEGORY> can be:
  • FLAGS - list of flags
  • LIBS - list of libraries

Examples

Specify the LINK options prefixed with a dash(-) for MSVC(Visual Studio) compiler with CMake < 3.13 to avoid issues caused by target_link_libraries CMake command usage.

If the option is used only in part of the places (library, tests, benchmarks) and adding this option to the group of other options is not possible, then the option must be named using common sense.

Warning suppressions should be added to the TBB_WARNING_SUPPRESS variable, which is applied during the compilation of libraries, tests, and benchmarks. Additional warnings should be added to the TBB_WARNING_TEST_FLAGS variable, which is applied during the compilation of tests.