Integration of Intel Threading Building Blocks in your CMake project

Hi, dear readers habrahabr. In this blog, we would like to announce that we now have CMake modules that allow you to download, build and simply use Intel Threading Building Blocks (Intel TBB) in your CMake projects. Modules are available in the Intel TBB project repository on GitHub , as well as in binary packages for Linux * OS, Windows * OS and macOS *, starting with the release of Intel TBB 2017 Update 7.

Using Intel TBB CMake Modules

The new modules allow simple integration of Intel TBB binary packages into the project, as well as more complex options with downloading certain versions from GitHub and building the library from the source code. Detailed technical description of the modules can be found in the documentation .

Library integration into the project

The TBBConfig.cmake and TBBConfigVersion.cmake configuration files allow you to get the necessary variables and imported targets for using Intel TBB. The files are located in the <tbb_root> / cmake folder in binary packages for Linux * OS, Windows * OS or macOS *, starting with the release of Intel TBB 2017 Update 7.
')
Algorithm:

1. Download and unpack the binary package.
2. Add the location of the root folder of the connected library to the CMAKE_PREFIX_PATH variable or the path to the configuration files to the TBB_DIR variable.
3. Call the find_package (TBB) function, adding the necessary parameters if necessary.
4. Use received variables and / or imported targets.

The required library components can be listed after the COMPONENTS or REQUIRED keyword when calling the find_package function, for example, tbb, tbbmalloc, tbb_preview, etc. By default, the tbb, tbbmalloc and tbbmalloc_proxy components are available. For each component, an imported TBB :: <component> format target is created.

The following variables are defined:

TBB_FOUND	Intel TBB Search Success Flag
TBB_ <component> _FOUND	flag of success of the search for a separate component
TBB_IMPORTED_TARGETS	all created imported targets
TBB_VERSION	Intel TBB version (format: <major>. <minor>)
TBB_INTERFACE_VERSION	Intel TBB interface version

At the moment, when specifying the desired version of the library, there is a restriction: only compatibility of the versions of the <major>. <Minor> format itself is automatically checked, but compatibility of various updates within the same version is not checked. The interface version can be checked using the TBB_INTERFACE_VERSION variable.

Build Intel TBB from source code using TBBBuild

The TBBBuild.cmake module provides the tbb_build function, which allows building a library from source code using the native library infrastructure (Makefile). Building on Linux * OS and macOS * requires the make-utility, and on Windows * OS - gmake. After directly assembling, the necessary configuration files are created in the <tbb_root> / cmake folder.

The tbb_build function takes the following parameters:

TBB_ROOT <variable>	path to the root folder of the library you want to collect
CONFIG_DIR <variable>	variable in which the full path to the folder with the created configuration files is written; <variable> -NOTFOUND will be returned in case of a build error
MAKE_ARGS <custom_make_arguments>	custom arguments for make commands; The following arguments are defined and passed automatically 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>

Example of using the module:

include(<path-to-tbb-cmake-modules>/TBBBuild.cmake) tbb_build(TBB_ROOT <tbb_root> CONFIG_DIR TBB_DIR) find_package(TBB <options>) 

Downloading Intel TBB using TBBGet

The TBBGet.cmake module provides the tbb_get function, which allows you to download and unpack binary packages and source packages for Intel TBB official releases with GitHub . For binary packages older than Intel TBB 2017 Update 7, configuration files are automatically created in the <tbb_root> / cmake folder.

The tbb_get function takes the following parameters:

TBB_ROOT <variable>	a variable in which the full path to the root folder of the downloaded and unpacked package will be written; <variable> -NOTFOUND will be returned in case of an error while downloading
RELEASE_TAG <release_tag> | LATEST	release tag for download; default value is LATEST
SAVE_TO <path>	path to unpack the downloaded package; $ { CMAKE_CURRENT_BINARY_DIR } is the default } / tbb_downloaded
SYSTEM_NAME Linux | Windows | Darwin	OS for which you need to download a binary package; the default value is CMAKE_SYSTEM_NAME
CONFIG_DIR <variable>	variable in which the full path to the configuration files will be written; the parameter is ignored if the SOURCE_CODE flag is specified
SOURCE_CODE	flag indicating the need to download a source package instead of a binary package

Examples of using the module:

1. Download and connect the latest binary package for the current OS
   
   

    include(<path-to-tbb-cmake-modules>/TBBGet.cmake) tbb_get(TBB_ROOT tbb_root CONFIG_DIR TBB_DIR) find_package(TBB <options>) 

   
   
2. Download, build and connect the latest source package
   
   

    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>) 

Demo projects based on the GettingStarted / sub_string_finder example with an Intel TBB connection

Conclusion

The Intel TBB team is interested in easily integrating the library into custom CMake projects. New modules are created just to solve this problem. They provide a simple and flexible interface with many use cases. We hope you try these modules and look forward to your feedback.

Links and contacts:

• Our mail: inteltbbdevelopers@intel.com .
• Our project on github .
• Our forum .

* other names and brands may be declared the intellectual property of others.