1# Build System Description 2 3The project uses CMake* build configuration. 4 5The following controls are available during the configure stage: 6``` 7TBB_TEST:BOOL - Enable testing (ON by default) 8TBB_STRICT:BOOL - Treat compiler warnings as errors (ON by default) 9TBB_SANITIZE:STRING - Sanitizer parameter, passed to compiler/linker 10TBB_SIGNTOOL:FILEPATH - Tool for digital signing, used in post-install step for libraries if provided. 11TBB_SIGNTOOL_ARGS:STRING - Additional arguments for TBB_SIGNTOOL, used if TBB_SIGNTOOL is set. 12TBB_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) build (ON by default) 13TBBMALLOC_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) memory allocator build (ON by default) 14TBBMALLOC_PROXY_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) memory allocator proxy build (requires TBBMALLOC_BUILD. ON by default) 15TBB4PY_BUILD:BOOL - Enable Intel(R) oneAPI Threading Building Blocks (oneTBB) Python module build (OFF by default) 16TBB_CPF:BOOL - Enable preview features of the library (OFF by default) 17TBB_INSTALL:BOOL - Enable installation (ON by default) 18TBB_INSTALL_VARS:BOOL - Enable auto-generated vars installation(packages generated by `cpack` and `make install` will also include the vars script)(OFF by default) 19TBB_VALGRIND_MEMCHECK:BOOL - Enable scan for memory leaks using Valgrind (OFF by default) 20TBB_DISABLE_HWLOC_AUTOMATIC_SEARCH - Disable HWLOC automatic search by pkg-config tool (OFF by default) 21TBB_ENABLE_IPO - Enable Interprocedural Optimization (IPO) during the compilation (ON by default) 22``` 23 24## Configure, Build, and Test 25 26### Preparation 27 28To perform an out-of-source build, create a build directory and go there: 29 30```bash 31mkdir /tmp/my-build 32cd /tmp/my-build 33``` 34 35### Configure 36 37```bash 38cmake <options> <repo_root> 39``` 40 41Some useful options: 42- `-G <generator>` - specify particular project generator. See `cmake --help` for details. 43- `-DCMAKE_BUILD_TYPE=Debug` - specify for Debug build. It is not applicable for multi-config generators, e.g., Microsoft* Visual Studio* generator. 44 45#### TBBBind Library Configuration 46 47> **_TIP:_** It is recommended to install the HWLOC* library. See [oneTBB documentation](https://oneapi-src.github.io/oneTBB/GSG/next_steps.html#hybrid-cpu-and-numa-support) for details. 48 49The 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: 50- `tbbbind` links with `HWLOC 1.11.x` 51- `tbbbind_2_0` links with `HWLOC 2.1–2.4` 52- `tbbbind_2_5` links with `HWLOC 2.5` and later 53 54The 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: 55 56 - `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 57 - `CMAKE_HWLOC_<HWLOC_VER>_INCLUDE_PATH` - path to the corresponding HWLOC version including directory 58 59 60--- 61**NOTE:** Automatic HWLOC searching requires CMake version 3.6 or higher. 62 63--- 64 65 66Windows* OS requires an additional variable for correct TBBBind library building: 67 - `CMAKE_HWLOC_<HWLOC_VER>_DLL_PATH` - path to the corresponding HWLOC version `.dll` file. 68 69The `HWLOC_VER` substring used earlier can be replaced with one of the three values: 70- `1_11` for the `tbbbind` library configuration 71- `2` for the `tbbbind_2_0` library configuration 72- `2_5` for the `tbbbind_2_5` library configuration 73 74If you specify variables for several TBBBind versions, the building process for all of these versions is performed during a single build session. 75 76--- 77**TIP** 78 79Specify the `TBB_DISABLE_HWLOC_AUTOMATIC_SEARCH` to turn off the HWLOC library's automatic search. 80 81--- 82 83 84### Build 85 86```bash 87cmake --build . <options> 88``` 89 90Some useful options: 91- `--target <target>` - specific target, "all" is the default. 92- `--config <Release|Debug>` - build configuration, applicable only for multi-config generators, e.g., Visual Studio* generator. 93 94The binaries are placed to `./<compiler-id>_<compiler-ver>_cxx<stdver>_<build-type>`. For example, `./gnu_4.8_cxx11_release`. 95 96#### Build For 32-bit 97 98* **Intel(R) Compiler**. Source Intel(R) C++ Compiler with `ia32` and build as usual. 99* **MSVC**. Use switch for [generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) (e.g., `-A Win32` for [VS2019](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2016%202019.html)) during the configuration stage and then build as usual. 100* **GCC/Clang**. Specify `-m32` during the configuration. It can be `CXXFLAGS=-m32 cmake ..` or `cmake -DCMAKE_CXX_FLAGS=-m32 ..` 101* For any other compiler, which builds for 64-bit by default, specify a 32-bit compiler key during the configuration as above. 102 103#### Windows* OS-Specific Builds 104 105--- 106**NOTE** 107 108The following builds require CMake version 3.15 or higher. 109 110--- 111 112* **Dynamic linkage with C Runtime Library (CRT)**. The default behavior can be explicitly specified by setting `CMAKE_MSVC_RUNTIME_LIBRARY` to `MultiThreadedDLL` or `MultiThreadedDebugDLL`. 113```bash 114cmake .. # dynamic linkage is used by default 115``` 116```bash 117cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL .. 118``` 119```bash 120cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDebugDLL -DCMAKE_BUILD_TYPE=Debug .. 121``` 122* **Static linkage with CRT**. Set `CMAKE_MSVC_RUNTIME_LIBRARY` to `MultiThreaded` or `MultiThreadedDebug`. 123```bash 124cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded .. 125``` 126```bash 127cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDebug -DCMAKE_BUILD_TYPE=Debug .. 128``` 129* **Windows OS 10 Universal Windows application build**. Set `CMAKE_SYSTEM_NAME` to `WindowsStore` and `CMAKE_SYSTEM_VERSION` to `10.0`. 130 131--- 132**NOTE** 133 134Set `TBB_NO_APPCONTAINER` to `ON` to apply the `/APPCONTAINER:NO` option during the compilation (used for testing). 135 136--- 137 138```bash 139cmake -DCMAKE_SYSTEM_NAME:STRING=WindowsStore -DCMAKE_SYSTEM_VERSION:STRING=10.0 .. 140``` 141 142* **Universal Windows OS Driver build**. Set `TBB_WINDOWS_DRIVER` to `ON` and use static linkage with CRT. 143 144```bash 145cmake -DTBB_WINDOWS_DRIVER=ON -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded .. 146``` 147 148#### Example 149 150```bash 151cmake -DCMAKE_CXX_COMPILER=icpc -DCMAKE_C_COMPILER=icc -DTBB_TEST=off -DCMAKE_HWLOC_1_11_LIBRARY_PATH=<path_to_hwloc_library_file>/libhwloc.so.15 152-DCMAKE_HWLOC_1_11_INCLUDE_PATH=<path_to_hwloc_header_directory> -DCMAKE_INSTALL_PREFIX=<path_to_install_oneTBB>/oneTBB_install .. 153make -j8 && make install 154``` 155 156--- 157**NOTE** 158 159The library path points to a file, while the include path points to a directory and not to ``hwloc.h``. 160 161--- 162 163### Test 164 165#### Build test 166To build a test, use the default target ``all``: 167``` 168cmake --build . 169``` 170 171Or use a specific test target: 172``` 173cmake --build . --target <test> # e.g. test_version 174``` 175 176#### Run Test 177 178You can run a test by using CTest: 179```bash 180ctest 181``` 182 183Or by using the ``test`` target: 184```bash 185cmake --build . --target test # currently does not work on Windows* OS 186``` 187 188## Installation 189See [Installation from Sources](../INSTALL.md) to learn how to install oneTBB. 190 191## Sanitizers - Configure, Build, and Run 192 193```bash 194mkdir build 195cd build 196cmake -DTBB_SANITIZE=thread .. # or -DTBB_SANITIZE=memory or any other sanitizer 197make -j 198ctest -V 199``` 200 201## Valgrind Memcheck - Configure, Build, and Run 202 203### Prerequisites 204* Valgrind tool executable 205### Example 206```bash 207mkdir build 208cd build 209cmake -DTBB_VALGRIND_MEMCHECK=ON .. 210make -j memcheck-<test name> # or memcheck-all to scan all tests 211``` 212 213## Test Specification 214 215Use Doxygen* to generate oneTBB test specification: 216 217```bash 218mkdir build 219cd build 220cmake -DTBB_TEST_SPEC=ON .. 221make test_spec 222``` 223 224## TBBConfig - Integration of Binary Packages 225 226It 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](https://cmake.org/cmake/help/latest/command/find_package.html) function. 227 228To use this module in your CMake project: 229 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](https://cmake.org/cmake/help/latest/command/find_package.html)). 230 2. Use [find_package](https://cmake.org/cmake/help/latest/command/find_package.html) to find oneTBB. 231 3. Use provided variables and/or imported targets (described below) to work with the found oneTBB. 232 233Example: 234 235```cmake 236add_executable(foo foo.cpp) 237find_package(TBB) 238target_link_libraries(foo TBB::tbb) 239``` 240 241oneTBB components can be passed to [find_package](https://cmake.org/cmake/help/latest/command/find_package.html) after keyword ``COMPONENTS`` or ``REQUIRED``. 242Use basic names of components (`tbb`, `tbbmalloc`, etc.). 243 244If components are not specified, then the default set is used: `tbb`, `tbbmalloc`, and ``tbbmalloc_proxy``. 245 246If `tbbmalloc_proxy` is requested, the `tbbmalloc` component is also added and set as a dependency for `tbbmalloc_proxy`. 247 248TBBConfig creates [imported targets](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#imported-targets>) as 249shared libraries using the following format: `TBB::<component>`. For example, `TBB::tbb` or `TBB::tbbmalloc`. 250 251To 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. 252 253Variables set during TBB configuration: 254 255Variable | Description 256--- | --- 257`TBB_FOUND` | oneTBB is found 258`TBB_<component>_FOUND` | Specific oneTBB component is found 259`TBB_VERSION` | oneTBB version (format: `<major>.<minor>.<patch>.<tweak>`) 260`TBB_IMPORTED_TARGETS` | All created oneTBB imported targets (not supported for builds from source code) 261 262Starting from [oneTBB 2021.1](https://github.com/oneapi-src/oneTBB/releases/tag/v2021.1), GitHub* release TBBConfig files in the binary packages are located under `<tbb-root>/lib/cmake/TBB`. 263For example, `TBB_DIR` should be set to `<tbb-root>/lib/cmake/TBB`. 264 265TBBConfig files are automatically created during the build from source code and can be installed together with the library. 266Also, oneTBB provides a helper function that creates TBBConfig files from predefined templates. See `tbb_generate_config` in `cmake/config_generation.cmake`. 267 268## oneTBB Python Module Support 269The `TBB4PY_BUILD` Cmake option provides the ability to build a Python module for oneTBB. 270 271### Targets: 272 - `irml` - build IPC RML server 273 - `python_build` - build oneTBB module for Python 274 275`python_build` target requirements: 276 - Python version 3.5 or newer 277 - SWIG version 3.0.6 or newer 278 279## CMake Files 280 281### Compile and Link Options 282 283Compile and link options may be specific for certain compilers. This part is handled in `cmake/compilers/*` files. 284 285Options in TBB CMake are handled via variables in two ways for convenience: 286 287* by options group 288* by the specific option 289 290#### Options Group 291 292Naming convention is the following: `TBB_<SCOPE>_<STAGE>_<CATEGORY>`, where: 293 294* `<SCOPE>` can be: 295 * `LIB` - options applied during libraries build. 296 * `TEST` - options applied during test build. 297 * `BENCH` - options applied during benchmarks build. 298 * `COMMON` - options applied during all (libraries, test, benchmarks) builds. 299* `<STAGE>` can be: 300 * `COMPILE` - options applied during the compilation. 301 * `LINK` - options applied during the linkage. 302* `<CATEGORY>` can be: 303 * `FLAGS` - list of flags 304 * `LIBS` - list of libraries 305 306*Examples* 307 308Variable | Description 309--- | --- 310`TBB_COMMON_COMPILE_FLAGS` | Applied to libraries, tests, and benchmarks as compile options 311`TBB_LIB_LINK_FLAGS` | Applied to libraries as link options 312`TBB_LIB_LINK_LIBS ` | Applied to libraries as link libraries 313`TBB_TEST_COMPILE_FLAGS` | Applied to tests as compile options 314 315Specify 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. 316 317#### Specific Options 318 319If 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, 320then the option must be named using common sense. 321 322Warning suppressions should be added to the `TBB_WARNING_SUPPRESS` variable, which is applied during the compilation of libraries, tests, and benchmarks. 323Additional warnings should be added to the `TBB_WARNING_TEST_FLAGS` variable, which is applied during the compilation of tests. 324