Introduction

Many developers use CMake to manage their development projects, so the Threading Building Blocks (TBB) team created the set of CMake modules to simplify integration of the TBB library into a CMake project. The modules are available starting from TBB 2017 U7 in <tbb_root>/cmake <https://github.com/01org/tbb/tree/tbb_2017/cmake>.

About TBB

TBB is a library that supports scalable parallel programming using standard ISO C++ code. It does not require special languages or compilers. It is designed to promote scalable data parallel programming. Additionally, it fully supports nested parallelism, so you can build larger parallel components from smaller parallel components. To use the library, you specify tasks, not threads, and let the library map tasks onto threads in an efficient manner.

Many of the library interfaces employ generic programming, in which interfaces are defined by requirements on types and not specific types. The C++ Standard Template Library (STL) is an example of generic programming. Generic programming enables TBB to be flexible yet efficient. The generic interfaces enable you to customize components to your specific needs.

The net result is that TBB enables you to specify parallelism far more conveniently than using raw threads, and at the same time can improve performance.

References

Official TBB open source site
Official GitHub repository

Engineering team contacts

The TBB team is very interested in convenient integration of the TBB library into customer projects. These CMake modules were created to provide such a possibility for CMake projects using a simple but powerful interface. We hope you will try these modules and we are looking forward to receiving your feedback!

E-mail us: inteltbbdevelopers@intel.com.

Visit our forum.

Release Notes

Minimum supported CMake version: 3.0.0.
TBB versioning via find_package has the following format: find_package(TBB <major>.<minor> ...).

Use cases of TBB integration into CMake-aware projects

There are two types of TBB packages:

Binary packages with pre-built binaries for Windows* OS, Linux* OS and macOS*. They are available on the releases page of the Github repository: https://github.com/01org/tbb/releases. The main purpose of the binary package integration is the ability to build TBB header files and binaries into your CMake-aware project.
A source package is also available to download from the release page via the "Source code" link. In addition, it can be cloned from the repository by git clone https://github.com/01org/tbb.git. The main purpose of the source package integration is to allow you to do a custom build of the TBB library from the source files and then build that into your CMake-aware project.

There are four types of CMake modules that can be used to integrate TBB: TBBConfig, TBBGet, TBBMakeConfig and TBBBuild. See Technical documentation for CMake modules section for additional details.

Binary package integration

The following use case is valid for packages starting from TBB 2017 U7:

Download package manually and make integration.

Pre-condition: Location of TBBConfig.cmake is available via TBB_DIR or CMAKE_PREFIX_PATH contains path to TBB root.
CMake code for integration:
find_package(TBB <options>)

The following use case is valid for all TBB 2017 packages.

Download package using TBBGet and make integration.

Pre-condition: TBB CMake modules are available via <path-to-tbb-cmake-modules>.
CMake code for integration:
include(<path-to-tbb-cmake-modules>/TBBGet.cmake)
tbb_get(TBB_ROOT tbb_root CONFIG_DIR TBB_DIR)
find_package(TBB <options>)

Source package integration

Build TBB from existing source files using TBBBuild and make integration.

Pre-condition: TBB source code is available via <tbb_root> and TBB CMake modules are available via <path-to-tbb-cmake-modules>.
CMake code for integration:
include(<path-to-tbb-cmake-modules>/TBBBuild.cmake)
tbb_build(TBB_ROOT <tbb_root> CONFIG_DIR TBB_DIR)
find_package(TBB <options>)

Download TBB source files using TBBGet, build it using TBBBuild and make integration.

Pre-condition: TBB CMake modules are available via <path-to-tbb-cmake-modules>.
CMake code for integration:
include(<path-to-tbb-cmake-modules>/TBBGet.cmake)
include(<path-to-tbb-cmake-modules>/TBBBuild.cmake)
tbb_get(TBB_ROOT tbb_root SOURCE_CODE)
tbb_build(TBB_ROOT ${tbb_root} CONFIG_DIR TBB_DIR)
find_package(TBB <options>)

Tutorials: TBB integration using CMake

Binary TBB integration to the sub_string_finder sample (Windows* OS)

In this example, we will integrate binary TBB package into the sub_string_finder sample on Windows* OS (Microsoft* Visual Studio). This example is also applicable for other platforms with slight changes. Place holders <version> and <date> should be replaced with the actual values for the TBB package being used. The example is written for CMake 3.7.1.

Precondition:

Microsoft* Visual Studio 11 or higher.
CMake 3.0.0 or higher.

Download the latest binary package for Windows from this page and unpack it to the directory C:\demo_tbb_cmake.

In the directory C:\demo_tbb_cmake\tbb<version>_<date>oss\examples\GettingStarted\sub_string_finder create CMakeLists.txt file with the following content:

cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR)

project(sub_string_finder CXX)
add_executable(sub_string_finder sub_string_finder.cpp)

# find_package will search for available TBBConfig using variables CMAKE_PREFIX_PATH and TBB_DIR.
find_package(TBB REQUIRED tbb)

# Link TBB imported targets to the executable;
# "TBB::tbb" can be used instead of "${TBB_IMPORTED_TARGETS}".
target_link_libraries(sub_string_finder ${TBB_IMPORTED_TARGETS})

Run CMake GUI and:
- Fill the following fields (you can use the buttons Browse Source... and Browse Build... accordingly)
- Where is the source code: C:/demo_tbb_cmake/tbb<version>_<date>oss/examples/GettingStarted/sub_string_finder
- Where to build the binaries: C:/demo_tbb_cmake/tbb<version>_<date>oss/examples/GettingStarted/sub_string_finder/build
- Add new cache entry using button Add Entry to let CMake know where to search for TBBConfig:
- Name: CMAKE_PREFIX_PATH
- Type: PATH
- Value: C:/demo_tbb_cmake/tbb<version>_<date>oss
- Push the button Generate and choose a proper generator for your Microsoft* Visual Studio version.
Now you can open the generated solution C:/demo_tbb_cmake/tbb<version>_<date>oss/examples/GettingStarted/sub_string_finder/build/sub_string_finder.sln in your Microsoft* Visual Studio and build it.

Source code integration of TBB to the sub_string_finder sample (Linux* OS)

In this example, we will build TBB from source code with enabled Community Preview Features and link the sub_string_finder sample with the built library. This example is also applicable for other platforms with slight changes.

Precondition:

CMake 3.0.0 or higher.
Git (to clone the TBB repository from GitHub)

#. Create the directory ~/demo_tbb_cmake, go to the created directory and clone the TBB repository there:

mkdir ~/demo_tbb_cmake ; cd ~/demo_tbb_cmake ; git clone https://github.com/01org/tbb.git

#. In the directory ~/demo_tbb_cmake/tbb/examples/GettingStarted/sub_string_finder create CMakeLists.txt file with following content:

cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR)

project(sub_string_finder CXX)
add_executable(sub_string_finder sub_string_finder.cpp)

include(${TBB_ROOT}/cmake/TBBBuild.cmake)

# Build TBB with enabled Community Preview Features (CPF).
tbb_build(TBB_ROOT ${TBB_ROOT} CONFIG_DIR TBB_DIR MAKE_ARGS tbb_cpf=1)

find_package(TBB REQUIRED tbb_preview)

# Link TBB imported targets to the executable;
# "TBB::tbb_preview" can be used instead of "${TBB_IMPORTED_TARGETS}".
target_link_libraries(sub_string_finder ${TBB_IMPORTED_TARGETS})

#. Create a build directory for the sub_string_finder sample to perform build out of source, go to the created directory

mkdir ~/demo_tbb_cmake/tbb/examples/GettingStarted/sub_string_finder/build ; cd ~/demo_tbb_cmake/tbb/examples/GettingStarted/sub_string_finder/build

#. Run CMake to prepare Makefile for the sub_string_finder sample and provide TBB location (root) where to perform build:

cmake -DTBB_ROOT=${HOME}/demo_tbb_cmake/tbb ..

#. Make an executable and run it:

make ; ./sub_string_finder

Technical documentation for CMake modules

TBBConfig

Configuration module for TBB library.

How to use this module in your CMake project:

Add location of TBB (root) to CMAKE_PREFIX_PATH or specify location of TBBConfig.cmake in TBB_DIR.
Use find_package to configure TBB.
Use provided variables and/or imported targets (described below) to work with TBB.

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

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

If tbbmalloc_proxy is requested, tbbmalloc component will also be added and set as dependency for tbbmalloc_proxy.

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

Variables set during TBB configuration:

Variable	Description
`TBB_FOUND`	TBB library is found
`TBB_<component>_FOUND`	specific TBB component is found
`TBB_IMPORTED_TARGETS`	all created TBB imported targets
`TBB_VERSION`	TBB version (format: `<major>.<minor>`)
`TBB_INTERFACE_VERSION`	TBB interface version (can be empty, see below for details)

TBBInstallConfig

Module for generation and installation of TBB CMake configuration files (TBBConfig.cmake and TBBConfigVersion.cmake files) on Linux, macOS and Windows.

Provides the following functions:

tbb_install_config(INSTALL_DIR <install_dir> SYSTEM_NAME Linux|Darwin|Windows
                   [TBB_VERSION <major>.<minor>|TBB_VERSION_FILE <version_file>]
                   [LIB_REL_PATH <lib_rel_path> INC_REL_PATH <inc_rel_path>]
                   [LIB_PATH <lib_path> INC_PATH <inc_path>])``

Note: the module overwrites existing TBBConfig.cmake and TBBConfigVersion.cmake files in <install_dir>.

tbb_config_installer.cmake allows to run TBBInstallConfig.cmake from command line. It accepts the same parameters as tbb_install_config function, run cmake -P tbb_config_installer.cmake to get help.

Use cases

Prepare TBB CMake configuration files for custom TBB package.

The use case is applicable for package maintainers who create own TBB packages and want to create TBBConfig.cmake and TBBConfigVersion.cmake for these packages.

Parameter	Description
`INSTALL_DIR <directory>`	Directory to install CMake configuration files
`SYSTEM_NAME Linux\|Darwin\|Windows`	OS name to generate config files for
`TBB_VERSION_FILE <version_file>`	Path to `tbb_stddef.h` to parse version from and write it to TBBConfigVersion.cmake
`TBB_VERSION <major>.<minor>`	Directly specified TBB version; alternative to `TBB_VERSION_FILE` parameter; `TBB_INTERFACE_VERSION` is set to empty value in this case
`LIB_REL_PATH <lib_rel_path>`	Relative path to TBB binaries (.lib files on Windows), default: `../../../lib`
`BIN_REL_PATH <bin_rel_path>`	Relative path to TBB DLLs, default: `../../../bin` (applicable for Windows only)
`INC_REL_PATH <inc_rel_path>`	Relative path to TBB headers, default: `../../../include`

Example

Assume your package is installed to the following structure:

Binaries go to <prefix>/lib

Headers go to <prefix>/include

CMake configuration files go to <prefix>/lib/cmake/<package>

The package is packed from /my/package/content directory.

cmake -DINSTALL_DIR=/my/package/content/lib/cmake/TBB -DSYSTEM_NAME=Linux -DTBB_VERSION_FILE=/my/package/content/include/tbb/tbb_stddef.h -P tbb_config_installer.cmake (default relative paths will be used)

Install TBB CMake configuration files for installed TBB.

The use case is applicable for users who have installed TBB, but do not have (or have incorrect) CMake configuration files for this TBB.

Parameter	Description
`INSTALL_DIR <directory>`	Directory to install CMake configuration files
`SYSTEM_NAME Linux\|Darwin\|Windows`	OS name to generate config files for
`LIB_PATH <lib_path>`	Path to installed TBB binaries (.lib files on Windows)
`BIN_PATH <bin_path>`	Path to installed TBB DLLs (applicable for Windows only)
`INC_PATH <inc_path>`	Path to installed TBB headers

LIB_PATH and INC_PATH will be converted to relative paths based on INSTALL_DIR. By default TBB version will be parsed from <inc_path>/tbb/tbb_stddef.h, but it can be overridden by optional parameters TBB_VERSION_FILE or TBB_VERSION.

Example

TBB is installed to /usr directory. In order to create TBBConfig.cmake and TBBConfigVersion.cmake in /usr/lib/cmake/TBB run

cmake -DINSTALL_DIR=/usr/lib/cmake/TBB -DSYSTEM_NAME=Linux -DLIB_PATH=/usr/lib -DINC_PATH=/usr/include -P tbb_config_installer.cmake.

TBBGet

Module for getting TBB library from GitHub.

Provides the following functions:

tbb_get(TBB_ROOT <variable> [RELEASE_TAG <release_tag>|LATEST] [SAVE_TO <path>] [SYSTEM_NAME Linux|Windows|Darwin] [CONFIG_DIR <variable> | SOURCE_CODE])

downloads TBB from GitHub and creates TBBConfig for the downloaded binary package if there is no TBBConfig.

Parameter	Description
`TBB_ROOT <variable>`	a variable to save TBB root in, `<variable>-NOTFOUND` will be provided in case `tbb_get` is unsuccessful
`RELEASE_TAG <release_tag>\|LATEST`	TBB release tag to be downloaded (for example, `2017_U6`), `LATEST` is used by default
`SAVE_TO <path>`	path to location at which to unpack downloaded TBB, `${CMAKE_CURRENT_BINARY_DIR}/tbb_downloaded` is used by default
`SYSTEM_NAME Linux\|Windows\|Darwin`	operating system name to download a binary package for, value of CMAKE_SYSTEM_NAME is used by default
`CONFIG_DIR <variable>`	a variable to save location of TBBConfig.cmake and TBBConfigVersion.cmake. Ignored if `SOURCE_CODE` specified
`SOURCE_CODE`	flag to get TBB source code (instead of binary package)

TBBMakeConfig

Module for making TBBConfig in official TBB binary packages published on GitHub.

This module is to be used for packages that do not have TBBConfig.

Provides the following functions:

tbb_make_config(TBB_ROOT <path> CONFIG_DIR <variable> [SYSTEM_NAME Linux|Windows|Darwin])

creates CMake configuration files (TBBConfig.cmake and TBBConfigVersion.cmake) for TBB binary package.

Parameter	Description
`TBB_ROOT <variable>`	path to TBB root
`CONFIG_DIR <variable>`	a variable to store location of the created configuration files
`SYSTEM_NAME Linux\|Windows\|Darwin`	operating system name of the binary TBB package, value of CMAKE_SYSTEM_NAME is used by default

TBBBuild

Module for building TBB library from the source code.

Provides the following functions:

tbb_build(TBB_ROOT <tbb_root> CONFIG_DIR <variable> [MAKE_ARGS <custom_make_arguments>])

builds TBB from source code using the Makefile, creates and provides the location of the CMake configuration files (TBBConfig.cmake and TBBConfigVersion.cmake) .

Parameter Description

TBB_ROOT <variable> path to TBB root

CONFIG_DIR <variable>

a variable to store location of the created configuration files, <variable>-NOTFOUND will be provided in case tbb_build is unsuccessful

MAKE_ARGS <custom_make_arguments>

custom arguments to be passed to make tool.

The following arguments are always passed with automatically detected values to make tool if they are not redefined in <custom_make_arguments>:

compiler=<compiler>

tbb_build_dir=<tbb_build_dir>

tbb_build_prefix=<tbb_build_prefix>

-j<n>

Intel and the Intel logo are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

* Other names and brands may be claimed as the property of others.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.rst

README.rst

Introduction

About TBB

References

Engineering team contacts

Release Notes

Use cases of TBB integration into CMake-aware projects

Binary package integration

Source package integration

Tutorials: TBB integration using CMake

Binary TBB integration to the sub_string_finder sample (Windows* OS)

Source code integration of TBB to the sub_string_finder sample (Linux* OS)

Technical documentation for CMake modules

TBBConfig

TBBInstallConfig

Use cases

TBBGet

TBBMakeConfig

TBBBuild

Files

README.rst

Latest commit

History

README.rst

File metadata and controls

Introduction

About TBB

References

Engineering team contacts

Release Notes

Use cases of TBB integration into CMake-aware projects

Binary package integration

Source package integration

Tutorials: TBB integration using CMake

Binary TBB integration to the sub_string_finder sample (Windows* OS)

Source code integration of TBB to the sub_string_finder sample (Linux* OS)

Technical documentation for CMake modules

TBBConfig

TBBInstallConfig

Use cases

TBBGet

TBBMakeConfig

TBBBuild