Integration of Intel Threading Building Blocks into your CMake project

Hello dear readers of habrahabr. In this blog, we would like to announce that now we have CMake modules that allow you to download, assemble 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 both 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. A detailed technical description of the modules can be found in the documentation .

Library integration in the project

The TBBConfig.cmake and TBBConfigVersion.cmake configuration files provide the necessary variables and imported targets for using Intel TBB. Files are in the folder/ cmake in binary packages for Linux * OS, Windows * OS or macOS *, starting with the release of Intel TBB 2017 Update 7.

Algorithm:

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

The necessary 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, tbb, tbbmalloc, and tbbmalloc_proxy components are available. An imported TBB format target is created for each component:.

The following variables are defined:

TBB_FOUND	Intel TBB Search Success Flag
TBB__FOUND	single component search success flag
TBB_IMPORTED_TARGETS	all created imported goals
TBB_VERSION	Intel TBB version (format: .)
TBB_INTERFACE_VERSION	Intel TBB interface version

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

Build Intel TBB from source using TBBBuild

The TBBBuild.cmake module provides the tbb_build function , which allows you to compile a library from source code using the native library infrastructure (Makefile). To build on Linux * OS and macOS *, you must have a make utility, and on Windows * OS, gmake. After the assembly itself, the necessary configuration files are created in the folder/ cmake.

The tbb_build function accepts the following parameters:

TBB_ROOT	path to the root folder of the library to be collected
CONFIG_DIR	a variable in which the full path to the folder with the created configuration files is written; value-NOTFOUND will be returned in case of build error
MAKE_ARGS	custom arguments for the make command; The following arguments are determined and passed automatically if they are not overridden in: compiler = tbb_build_dir = tbb_build_prefix = -j

An example of using the module:

include(/TBBBuild.cmake)
tbb_build(TBB_ROOT  CONFIG_DIR TBB_DIR)
find_package(TBB )

Download Intel TBB with TBBGet

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

The tbb_get function accepts the following parameters:

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

Examples of using the module:

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

   include(/TBBGet.cmake)
   tbb_get(TBB_ROOT tbb_root CONFIG_DIR TBB_DIR)
   find_package(TBB )

   
   
2. Downloading, building and connecting the latest source package
   
   

   include(/TBBGet.cmake)
   include(/TBBBuild.cmake)
   tbb_get(TBB_ROOT tbb_root SOURCE_CODE)
   tbb_build(TBB_ROOT ${tbb_root} CONFIG_DIR TBB_DIR)
   find_package(TBB )
   

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

Connecting a binary package on Windows * OS

In this example, we will create a CMake project based on GettingStarted / sub_string_finder with the Intel TBB binary package enabled. The example was written for Windows * OS (Microsoft * Visual Studio), but with minor changes it can be used for other OSs.
Keywords and must be replaced with the current values ​​for the downloaded package.

Minimum Requirements:

• CMake 3.0.0
• Microsoft * Visual Studio 11 (for Intel TBB 2017 Update 7)
• Intel TBB 2017 Update 7

Instruction:

1. Download Intel TBB for Windows * OS and unzip it to C: \ demo_tbb_cmake
2. In the folder C: \ demo_tbb_cmake \ tbb_oss \ examples \ GettingStarted \ sub_string_finder create a CMakeLists.txt file with the following contents:
   
   

   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 ищет TBBConfig, используя переменные
   # CMAKE_PREFIX_PATH и TBB_DIR.
   find_package(TBB REQUIRED tbb)
   # "TBB::tbb" можно использовать вместо "${TBB_IMPORTED_TARGETS}"
   target_link_libraries(sub_string_finder ${TBB_IMPORTED_TARGETS})
    

3. Launch the CMake GUI and
   
   • Fill in the fields (you can use the buttons "Browse Source ..." and "Browse Build ..."):
     "Where is the source code":
     C: / demo_tbb_cmake / tbb_oss / examples / GettingStarted / sub_string_finder
     "Where to build the binaries":
     C: / demo_tbb_cmake / tbb_oss / examples / GettingStarted / sub_string_finder / build
   • Add a new variable to the cache with the Add Entry button:
     Name: CMAKE_PREFIX_PATH
     Type: PATH
     Value: C: / demo_tbb_cmake / tbb_oss
   • Create a Microsoft * Visual Studio project by clicking the Generate button.
4. Now the resulting project can be opened in Microsoft * Visual Studio (for example, by clicking the "Open Project" button in the CMake GUI) and built. Path to the generated project:
   C: \ demo_tbb_cmake \ tbb_oss \ examples \ GettingStarted \ sub_string_finder \ build \ sub_string_finder.sln.
   
   CMake GUI window after project generation:
   
   
   

Building a library from source code and connecting to a project

In this example, we will create a CMake project based on GettingStarted / sub_string_finder, in which we will build and connect Intel TBB with Community Preview Features (CPF) enabled . The example is written for Linux * OS, but with minor changes it can be used for other OSs.

Minimum Requirements:

• CMake 3.0.0

Instruction:

1. Clone the Intel TBB repository into the ~ / demo_tbb_cmake folder:
   

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

   
   
2. In the ~ / demo_tbb_cmake / tbb / examples / GettingStarted / sub_string_finder folder, create a CMakeLists.txt file with the following contents:
   

   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)
    # Строим Intel TBB с включенными 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)
    # "TBB::tbb_preview" можно использовать вместо "${TBB_IMPORTED_TARGETS}".
   target_link_libraries(sub_string_finder ${TBB_IMPORTED_TARGETS})
   

   
   
3. Create a folder to build your project and go there:
   
   

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

4. Launch CMake by specifying the root folder of the Intel TBB library:
   

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

5. Build and run the project:
   

   make
   ./sub_string_finder
   

Conclusion

Intel TBB Team is interested in conveniently 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.