cmake/README.rst

   1 .. contents::
   2
   3 Introduction
   4 ------------
   5 Many developers use CMake to manage their development projects, so the Threading Building Blocks (TBB)
   6 team created the set of CMake modules to simplify integration of the TBB library into a CMake project.
   7 The modules are available starting from TBB 2017 U7 in `<tbb_root>/cmake <https://github.com/01org/tbb/tree/tbb_2017/cmake>`_.
   8
   9 About TBB
  10 ^^^^^^^^^^^^^^^
  11 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.
  12
  13 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.
  14
  15 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.
  16
  17 References
  18 ^^^^^^^^^^
  19 * `Official TBB open source site <https://www.threadingbuildingblocks.org/>`_
  20 * `Official GitHub repository <https://github.com/01org/tbb>`_
  21
  22 Engineering team contacts
  23 ^^^^^^^^^^^^^^^^^^^^^^^^^
  24 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!
  25
  26 E-mail us: `inteltbbdevelopers@intel.com <mailto:inteltbbdevelopers@intel.com>`_.
  27
  28 Visit our `forum <https://software.intel.com/en-us/forums/intel-threading-building-blocks/>`_.
  29
  30 Release Notes
  31 -------------
  32 * Minimum supported CMake version: ``3.0.0``.
  33 * TBB versioning via `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ has the following format: ``find_package(TBB <major>.<minor>.<interface> ...)``. TBB interface version can also be obtained in the customer project via the ``TBB_INTERFACE_VERSION`` variable.
  34
  35 Use cases of TBB integration into CMake-aware projects
  36 ------------------------------------------------------------
  37 There are two types of TBB packages:
  38  * 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.
  39  * 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.
  40
  41 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.
  42
  43 Binary package integration
  44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  45
  46 The following use case is valid for packages starting from TBB 2017 U7:
  47
  48 * Download package manually and make integration.
  49
  50  Pre-condition: Location of TBBConfig.cmake is available via ``TBB_DIR`` or ``CMAKE_PREFIX_PATH`` contains path to TBB root.
  51
  52  CMake code for integration:
  53   .. code:: cmake
  54
  55    find_package(TBB <options>)
  56
  57 The following use case is valid for all TBB 2017 packages.
  58
  59 * Download package using TBBGet_ and make integration.
  60
  61  Pre-condition: TBB CMake modules are available via <path-to-tbb-cmake-modules>.
  62
  63  CMake code for integration:
  64   .. code:: cmake
  65
  66    include(<path-to-tbb-cmake-modules>/TBBGet.cmake)
  67    tbb_get(TBB_ROOT tbb_root CONFIG_DIR TBB_DIR)
  68    find_package(TBB <options>)
  69
  70 Source package integration
  71 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  72 * Build TBB from existing source files using TBBBuild_ and make integration.
  73
  74  Pre-condition: TBB source code is available via <tbb_root> and TBB CMake modules are available via <path-to-tbb-cmake-modules>.
  75
  76  CMake code for integration:
  77   .. code:: cmake
  78
  79    include(<path-to-tbb-cmake-modules>/TBBBuild.cmake)
  80    tbb_build(TBB_ROOT <tbb_root> CONFIG_DIR TBB_DIR)
  81    find_package(TBB <options>)
  82
  83 * Download TBB source files using TBBGet_, build it using TBBBuild_ and make integration.
  84
  85  Pre-condition: TBB CMake modules are available via <path-to-tbb-cmake-modules>.
  86
  87  CMake code for integration:
  88   .. code:: cmake
  89
  90    include(<path-to-tbb-cmake-modules>/TBBGet.cmake)
  91    include(<path-to-tbb-cmake-modules>/TBBBuild.cmake)
  92    tbb_get(TBB_ROOT tbb_root SOURCE_CODE)
  93    tbb_build(TBB_ROOT ${tbb_root} CONFIG_DIR TBB_DIR)
  94    find_package(TBB <options>)
  95
  96 Tutorials: TBB integration using CMake
  97 --------------------------------------------
  98 Binary TBB integration to the sub_string_finder sample (Windows* OS)
  99 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 100
 101 In this example, we will integrate binary TBB package into the sub_string_finder sample on Windows* OS (Microsoft* Visual Studio).
 102 This example is also applicable for other platforms with slight changes.
 103 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`.
 104
 105 Precondition:
 106   * `Microsoft* Visual Studio 11` or higher.
 107   * `CMake 3.0.0` or higher.
 108
 109 #. Download the latest binary package for Windows from `this page <https://github.com/01org/tbb/releases/latest>`_ and unpack it to the directory ``C:\demo_tbb_cmake``.
 110 #. In the directory ``C:\demo_tbb_cmake\tbb<version>_<date>oss\examples\GettingStarted\sub_string_finder`` create ``CMakeLists.txt`` file with the following content:
 111     .. code:: cmake
 112
 113         cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR)
 114
 115         project(sub_string_finder CXX)
 116         add_executable(sub_string_finder sub_string_finder.cpp)
 117
 118         # find_package will search for available TBBConfig using variables CMAKE_PREFIX_PATH and TBB_DIR.
 119         find_package(TBB REQUIRED tbb)
 120
 121         # Link TBB imported targets to the executable;
 122         # "TBB::tbb" can be used instead of "${TBB_IMPORTED_TARGETS}".
 123         target_link_libraries(sub_string_finder ${TBB_IMPORTED_TARGETS})
 124 #. Run CMake GUI and:
 125     * Fill the following fields (you can use the buttons ``Browse Source...`` and ``Browse Build...`` accordingly)
 126
 127      * Where is the source code: ``C:/demo_tbb_cmake/tbb<version>_<date>oss/examples/GettingStarted/sub_string_finder``
 128      * Where to build the binaries: ``C:/demo_tbb_cmake/tbb<version>_<date>oss/examples/GettingStarted/sub_string_finder/build``
 129
 130     * Add new cache entry using button ``Add Entry`` to let CMake know where to search for TBBConfig:
 131
 132      * Name: ``CMAKE_PREFIX_PATH``
 133      * Type: ``PATH``
 134      * Value: ``C:/demo_tbb_cmake/tbb<version>_<date>oss``
 135
 136     * Push the button ``Generate`` and choose a proper generator for your Microsoft* Visual Studio version.
 137 #. 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.
 138
 139 Source code integration of TBB to the sub_string_finder sample (Linux* OS)
 140 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 141
 142 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.
 143 This example is also applicable for other platforms with slight changes.
 144
 145 Precondition:
 146   * `CMake 3.0.0` or higher.
 147   * `Git` (to clone the TBB repository from GitHub)
 148
 149 #. Create the directory ``~/demo_tbb_cmake``, go to the created directory and clone the TBB repository there:
 150     ``mkdir ~/demo_tbb_cmake ; cd ~/demo_tbb_cmake ; git clone https://github.com/01org/tbb.git``
 151 #. In the directory ``~/demo_tbb_cmake/tbb/examples/GettingStarted/sub_string_finder`` create ``CMakeLists.txt`` file with following content:
 152     .. code:: cmake
 153
 154      cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR)
 155
 156      project(sub_string_finder CXX)
 157      add_executable(sub_string_finder sub_string_finder.cpp)
 158
 159      include(${TBB_ROOT}/cmake/TBBBuild.cmake)
 160
 161      # Build TBB with enabled Community Preview Features (CPF).
 162      tbb_build(TBB_ROOT ${TBB_ROOT} CONFIG_DIR TBB_DIR MAKE_ARGS tbb_cpf=1)
 163
 164      find_package(TBB REQUIRED tbb_preview)
 165
 166      # Link TBB imported targets to the executable;
 167      # "TBB::tbb_preview" can be used instead of "${TBB_IMPORTED_TARGETS}".
 168      target_link_libraries(sub_string_finder ${TBB_IMPORTED_TARGETS})
 169 #. Create a build directory for the sub_string_finder sample to perform build out of source, go to the created directory
 170     ``mkdir ~/demo_tbb_cmake/tbb/examples/GettingStarted/sub_string_finder/build ; cd ~/demo_tbb_cmake/tbb/examples/GettingStarted/sub_string_finder/build``
 171 #. Run CMake to prepare Makefile for the sub_string_finder sample and provide TBB location (root) where to perform build:
 172     ``cmake -DTBB_ROOT=${HOME}/demo_tbb_cmake/tbb ..``
 173 #. Make an executable and run it:
 174     ``make ; ./sub_string_finder``
 175
 176 Technical documentation for CMake modules
 177 -----------------------------------------
 178 TBBConfig
 179 ^^^^^^^^^
 180
 181 Configuration module for TBB library.
 182
 183 How to use this module in your CMake project:
 184  #. Add location of TBB (root) to `CMAKE_PREFIX_PATH <https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html>`_
 185     or specify location of TBBConfig.cmake in ``TBB_DIR``.
 186  #. Use `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ to configure TBB.
 187  #. Use provided variables and/or imported targets (described below) to work with TBB.
 188
 189 TBB components can be passed to `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_
 190 after keyword ``COMPONENTS`` or ``REQUIRED``.
 191 Use basic names of components (``tbb``, ``tbbmalloc``, ``tbb_preview``, etc.).
 192
 193 If components are not specified then default are used: ``tbb``, ``tbbmalloc`` and ``tbbmalloc_proxy``.
 194
 195 If ``tbbmalloc_proxy`` is requested, ``tbbmalloc`` component will also be added and set as dependency for ``tbbmalloc_proxy``.
 196
 197 TBBConfig creates `imported targets <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#imported-targets>`_ as
 198 shared libraries using the following format: ``TBB::<component>`` (for example, ``TBB::tbb``, ``TBB::tbbmalloc``).
 199
 200 Variables set during TBB configuration:
 201
 202 =========================  ================================================
 203          Variable                            Description
 204 =========================  ================================================
 205 ``TBB_FOUND``              TBB library is found
 206 ``TBB_<component>_FOUND``  specific TBB component is found
 207 ``TBB_IMPORTED_TARGETS``   all created TBB imported targets
 208 ``TBB_VERSION``            TBB version (format: ``<major>.<minor>``)
 209 ``TBB_INTERFACE_VERSION``  TBB interface version
 210 =========================  ================================================
 211
 212 TBBInstallConfig
 213 ^^^^^^^^^^^^^^^^
 214
 215 Module for generation and installation of TBB CMake configuration files (TBBConfig.cmake and TBBConfigVersion.cmake files) on Linux, macOS and Windows.
 216
 217 Provides the following functions:
 218
 219  .. code:: cmake
 220
 221   tbb_install_config(INSTALL_DIR <install_dir> SYSTEM_NAME Linux|Darwin|Windows
 222                      [TBB_VERSION <major>.<minor>.<interface>|TBB_VERSION_FILE <version_file>]
 223                      [LIB_REL_PATH <lib_rel_path> INC_REL_PATH <inc_rel_path>]
 224                      [LIB_PATH <lib_path> INC_PATH <inc_path>])``
 225
 226 **Note: the module overwrites existing TBBConfig.cmake and TBBConfigVersion.cmake files in <install_dir>.**
 227
 228 ``tbb_config_installer.cmake`` allows to run ``TBBInstallConfig.cmake`` from command line.
 229 It accepts the same parameters as ``tbb_install_config`` function, run ``cmake -P tbb_config_installer.cmake`` to get help.
 230
 231 Use cases
 232 """""""""
 233 **Prepare TBB CMake configuration files for custom TBB package.**
 234
 235 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.
 236
 237 ===========================================  ===========================================================
 238               Parameter                                      Description
 239 ===========================================  ===========================================================
 240 ``INSTALL_DIR <directory>``                  Directory to install CMake configuration files
 241 ``SYSTEM_NAME Linux|Darwin|Windows``         OS name to generate config files for
 242 ``TBB_VERSION_FILE <version_file>``          Path to ``tbb_stddef.h`` to parse version from and
 243                                              write it to TBBConfigVersion.cmake
 244 ``TBB_VERSION <major>.<minor>.<interface>``  Directly specified TBB version;
 245                                              alternative to ``TBB_VERSION_FILE`` parameter
 246 ``LIB_REL_PATH <lib_rel_path>``              Relative path to TBB binaries (.lib files on Windows), default: ``../../../lib``
 247 ``BIN_REL_PATH <bin_rel_path>``              Relative path to TBB DLLs, default: ``../../../bin`` (applicable for Windows only)
 248 ``INC_REL_PATH <inc_rel_path>``              Relative path to TBB headers, default: ``../../../include``
 249 ===========================================  ===========================================================
 250
 251 *Example*
 252
 253  Assume your package is installed to the following structure:
 254
 255  * Binaries go to ``<prefix>/lib``
 256  * Headers go to ``<prefix>/include``
 257  * CMake configuration files go to ``<prefix>/lib/cmake/<package>``
 258
 259  The package is packed from ``/my/package/content`` directory.
 260
 261  ``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)
 262
 263 **Install TBB CMake configuration files for installed TBB.**
 264
 265 The use case is applicable for users who have installed TBB, but do not have (or have incorrect) CMake configuration files for this TBB.
 266
 267 ====================================  ==============================================
 268       Parameter                            Description
 269 ====================================  ==============================================
 270 ``INSTALL_DIR <directory>``           Directory to install CMake configuration files
 271 ``SYSTEM_NAME Linux|Darwin|Windows``  OS name to generate config files for
 272 ``LIB_PATH <lib_path>``               Path to installed TBB binaries (.lib files on Windows)
 273 ``BIN_PATH <bin_path>``               Path to installed TBB DLLs (applicable for Windows only)
 274 ``INC_PATH <inc_path>``               Path to installed TBB headers
 275 ====================================  ==============================================
 276
 277 ``LIB_PATH`` and ``INC_PATH`` will be converted to relative paths based on ``INSTALL_DIR``.
 278 By default TBB version will be parsed from ``<inc_path>/tbb/tbb_stddef.h``,
 279 but it can be overridden by optional parameters ``TBB_VERSION_FILE`` or ``TBB_VERSION``.
 280
 281 *Example*
 282
 283  TBB is installed to ``/usr`` directory.
 284  In order to create TBBConfig.cmake and TBBConfigVersion.cmake in ``/usr/lib/cmake/TBB`` run
 285
 286  ``cmake -DINSTALL_DIR=/usr/lib/cmake/TBB -DSYSTEM_NAME=Linux -DLIB_PATH=/usr/lib -DINC_PATH=/usr/include -P tbb_config_installer.cmake``.
 287
 288 TBBGet
 289 ^^^^^^
 290
 291 Module for getting TBB library from `GitHub <https://github.com/01org/tbb>`_.
 292
 293 Provides the following functions:
 294  ``tbb_get(TBB_ROOT <variable> [RELEASE_TAG <release_tag>|LATEST] [SAVE_TO <path>] [SYSTEM_NAME Linux|Windows|Darwin] [CONFIG_DIR <variable> | SOURCE_CODE])``
 295   downloads TBB from GitHub and creates TBBConfig for the downloaded binary package if there is no TBBConfig.
 296
 297   ====================================  ====================================
 298                      Parameter                       Description
 299   ====================================  ====================================
 300   ``TBB_ROOT <variable>``               a variable to save TBB root in, ``<variable>-NOTFOUND`` will be provided in case ``tbb_get`` is unsuccessful
 301   ``RELEASE_TAG <release_tag>|LATEST``  TBB release tag to be downloaded (for example, ``2017_U6``), ``LATEST`` is used by default
 302   ``SAVE_TO <path>``                    path to location at which to unpack downloaded TBB, ``${CMAKE_CURRENT_BINARY_DIR}/tbb_downloaded`` is used by default
 303   ``SYSTEM_NAME Linux|Windows|Darwin``  operating system name to download a binary package for,
 304                                         value of `CMAKE_SYSTEM_NAME <https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_NAME.html>`_ is used by default
 305   ``CONFIG_DIR <variable>``             a variable to save location of TBBConfig.cmake and TBBConfigVersion.cmake. Ignored if ``SOURCE_CODE`` specified
 306   ``SOURCE_CODE``                       flag to get TBB source code (instead of binary package)
 307   ====================================  ====================================
 308
 309 TBBMakeConfig
 310 ^^^^^^^^^^^^^
 311
 312 Module for making TBBConfig in `official TBB binary packages published on GitHub <https://github.com/01org/tbb/releases>`_.
 313
 314 This module is to be used for packages that do not have TBBConfig.
 315
 316 Provides the following functions:
 317  ``tbb_make_config(TBB_ROOT <path> CONFIG_DIR <variable> [SYSTEM_NAME Linux|Windows|Darwin])``
 318   creates CMake configuration files (TBBConfig.cmake and TBBConfigVersion.cmake) for TBB binary package.
 319
 320   ====================================  ====================================
 321                      Parameter                       Description
 322   ====================================  ====================================
 323   ``TBB_ROOT <variable>``               path to TBB root
 324   ``CONFIG_DIR <variable>``             a variable to store location of the created configuration files
 325   ``SYSTEM_NAME Linux|Windows|Darwin``  operating system name of the binary TBB package,
 326                                         value of `CMAKE_SYSTEM_NAME <https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_NAME.html>`_ is used by default
 327   ====================================  ====================================
 328
 329 TBBBuild
 330 ^^^^^^^^
 331
 332 Module for building TBB library from the source code.
 333
 334 Provides the following functions:
 335  ``tbb_build(TBB_ROOT <tbb_root> CONFIG_DIR <variable> [MAKE_ARGS <custom_make_arguments>])``
 336   builds TBB from source code using the ``Makefile``, creates and provides the location of the CMake configuration files (TBBConfig.cmake and TBBConfigVersion.cmake) .
 337
 338   =====================================  ====================================
 339                 Parameter                             Description
 340   =====================================  ====================================
 341   ``TBB_ROOT <variable>``                path to TBB root
 342   ``CONFIG_DIR <variable>``              a variable to store location of the created configuration files,
 343                                          ``<variable>-NOTFOUND`` will be provided in case ``tbb_build`` is unsuccessful
 344   ``MAKE_ARGS <custom_make_arguments>``  custom arguments to be passed to ``make`` tool.
 345
 346                                          The following arguments are always passed with automatically detected values to
 347                                          ``make`` tool if they are not redefined in ``<custom_make_arguments>``:
 348
 349                                            - ``compiler=<compiler>``
 350                                            - ``tbb_build_dir=<tbb_build_dir>``
 351                                            - ``tbb_build_prefix=<tbb_build_prefix>``
 352                                            - ``-j<n>``
 353   =====================================  ====================================
 354
 355
 356 ------------
 357
 358 Intel and the Intel logo are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.
 359
 360 ``*`` Other names and brands may be claimed as the property of others.