## Overview

This directory contains the internal Makefile infrastructure for Intel® Threading Building Blocks (Intel® TBB).

See below for how to build Intel TBB and how to port Intel TBB to a new platform, operating system or architecture.

## Files

The files here are not intended to be used directly. See below for usage.

Makefile.tbb
  Main Makefile to build the Intel TBB library. Invoked via 'make tbb' from top-level Makefile.
Makefile.tbbmalloc
  Main Makefile to build the Intel TBB scalable memory allocator library as well as its tests. Invoked via 'make tbbmalloc' from top-level Makefile.
Makefile.test
  Main Makefile to build and run the tests for the Intel TBB library. Invoked via 'make test' from top-level Makefile.
common.inc
  Main common included Makefile that includes OS-specific and compiler-specific Makefiles.
<os>.inc
  OS-specific Makefile for a particular <os>.
<os>.<compiler>.inc
  Compiler-specific Makefile for a particular <os> / <compiler> combination.
*.sh
  Infrastructure utilities for Linux* OS, macOS*, and UNIX*-related operating systems.
*.js, *.bat
  Infrastructure utilities for Windows* OS.

## To Build

To port Intel TBB to a new platform, operating system or architecture, see the porting directions below.

### Software prerequisites:

1. C++ compiler for the platform, operating system and architecture of interest. Either the native compiler for your system, or, optionally, the appropriate Intel® C++ Compiler, may be used.
2. GNU make utility. On Windows OS, if a UNIX* emulator is used to run GNU make, it should be able to run Windows OS utilities and commands. On Linux OS, macOS, etc., shell commands issued by GNU make should execute in a Bourne or BASH compatible shell. In the following examples, replace `make` with the correct GNU make command for your system (for example, `gmake`). GNU make version 3.80 and more recent are supported.

Intel TBB libraries can be built by performing the following steps. On systems that support only one ABI (e.g., 32-bit), these steps build the libraries for that ABI. On systems that support both 64-bit and 32-bit libraries, these steps build the 64-bit libraries (Linux OS, macOS, and related systems) or whichever ABI is selected in the development environment (Windows OS).

1. Change to the top-level directory of the installed software.
2. If using the Intel® C++ Compiler, make sure the appropriate compiler is available in your PATH (e.g., by sourcing the appropriate iccvars script for the compiler to be used).
3. Invoke GNU make using no arguments, for example, `make`.

To build Intel TBB libraries for other than the default ABI (e.g., to build 32-bit libraries on Linux OS, macOS, or related systems that support both 64-bit and 32-bit libraries), perform the following steps:

1. Change to the top-level directory of the installed software.
2. If using the Intel® C++ Compiler, make sure the appropriate compiler is available in your PATH (e.g., by sourcing the appropriate iccvars script for the compiler to be used).
3. Explicitly specify the architecture when invoking GNU make, e.g. `make arch=ia32`.

The default make target will build the release and debug versions of the Intel TBB library.

Other targets are available in the top-level Makefile. You might find the following targets useful:

- `make test` will build and run Intel TBB unit-tests;
- `make examples` will build and run Intel TBB examples. Available in the open-source version only. For the commercial version, you can download Intel TBB Samples at the Intel® Software Product Samples and Tutorials website;
- `make all` will do all of the above. Available in the open-source version only.

See also the list of other targets below.

By default, the libraries will be built in sub-directories within the build/ directory. The sub-directories are named according to the operating system, architecture, compiler and software environment used (the sub-directory names also distinguish release vs. debug libraries). On Linux OS, the software environment comprises the GCC, libc and kernel version used. On macOS, the software environment comprises the GCC and OS version used. On Windows OS, the software environment comprises the Microsoft* Visual Studio* version used. See below for how to change the default build directory.

To perform different build and/or test operations, use the following steps.

1. Change to the top-level directory of the installed software.
2. If using the Intel® C++ Compiler, make sure the appropriate compiler is available in your PATH (e.g., by sourcing the appropriate iccvars script for the compiler to be used).
3. Invoke GNU make by using one or more of the following commands.
   `make`
     Default build. Equivalent to `make tbb tbbmalloc`.
   `make all`
     Equivalent to `make tbb tbbmalloc test examples`. Available in the open-source version only.
   `cd src;make release`
     Build and test release libraries only.
   `cd src;make debug`
     Build and test debug libraries only.
   `make tbb`
     Make Intel TBB release and debug libraries.
   `make tbbmalloc`
     Make Intel TBB scalable memory allocator libraries.
   `make test`
     Compile and run unit-tests
   `make examples`
     Build libraries and run all examples, like doing `make debug clean release` from the general example Makefile. Available in the open-source version only.
   `make python`
     Build, install, and test Python* API for Intel TBB. See details here.
   `make compiler={icl, icc, gcc, clang} [(above options or targets)]`
     Build and run as above, but use specified compilers instead of default, native compilers
     1. `{icl, icc}` - to use Intel® compilers (`icl` on Windows OS, `icc` on Linux OS or macOS).
     2. `gcc` - to use g++ (e.g. MinGW on Windows OS)
     3. `clang` - to use Clang compiler
   `make compiler=clang stdlib=libc++ [(above options or targets)]`
     Build and run as above, but use `libc++` as a standard c++ library for clang.
   `make stdver={c++11, c++14, ...} [(above options or targets)]`
     Build and run as above, but additionally specify the version of the C++ standard or dialect to be used by the compiler. The specified value of `stdver` will be used as a parameter to the appropriate compiler option (such as `-std`); the behavior in case of unsupported value is compiler-specific.
   `make target_app={win8ui, uwp} [target_mode=store] [(above options or targets)]`
     Build and run as above, but use API that is compliant with Universal Windows* applications. Use `win8ui` option, if you want to use Intel TBB in Windows* 8 Universal application and `uwp` in case of Windows* 10 Universal Windows application. `target_mode=store` is used to produce binaries that are compliant with Windows Store* application container. In later case they won't work with Intel TBB unit tests but work only with Windows Store* applications.
   `ndk-build target=android [(above options or targets)]`
     Build and run as above, but build libraries for Android* OS by Android NDK that should be installed. Makefiles were tested with revision 8.
   `make arch={ia32, intel64, ia64} [(above options or targets)]`
     Build and run as above, but build libraries for the selected ABI. Might be useful for cross-compilation; ensure proper environment is set before running this command.
   `make tbb_root={(Intel TBB directory)} [(above options or targets)]`
     Build and run as above; for use when invoking `make` from a directory other than the top-level directory.
   `make tbb_build_dir={(build directory)} [(above options or targets)]`
     Build and run as above, but place the built libraries in the specified directory, rather than in the default sub-directory within the build/ directory. This command might have troubles with the build in case the sources installed to the directory with spaces in the path.
   `make tbb_build_prefix={(build sub-directory)} [(above options or targets)]`
     Build and run as above, but place the built libraries in the specified sub-directory within the build/ directory, rather than using the default sub-directory name.
   `make tbb_cpf=1 [(above options or targets)]`
     Build and run as above, but build and use libraries with the Community Preview Features enabled, rather than the default libraries.
   `make [(above options)] clean`
     Remove any executables or intermediate files produced by the above commands. Includes build directories, object files, libraries and test executables.

## To Port

This section provides information on how to port Intel TBB to a new platform, operating system or architecture. A subset or a superset of these steps may be required for porting to a given platform.

#### To port the Intel TBB source code:

1. If porting to a new architecture, create a file that describes the architecture-specific details for that architecture.
   - Create a <os>_<architecture>.h file in the include/tbb/machine directory that describes these details.
     - The <os>_<architecture>.h is named after the operating system and architecture as recognized by include/tbb/tbb_machine.h and the Makefile infrastructure.
     - This file defines the implementations of synchronization operations, and also the scheduler yield function, for the operating system and architecture.
     - Several examples of <os>_<architecture>.h files can be found in the include/tbb/machine directory.
       - A minimal implementation defines the 4-byte and 8-byte compare-and-swap operations, and the scheduler yield function. See include/tbb/machine/mac_ppc.h for an example of a minimal implementation.
       - More complex implementation examples can also be found in the include/tbb/machine directory that implement all the individual variants of synchronization operations that Intel TBB uses. Such implementations are more verbose but may achieve better performance on a given architecture.
       - In a given implementation, any synchronization operation that is not defined is implemented, by default, in terms of 4-byte or 8-byte compare-and-swap. More operations can thus be added incrementally to increase the performance of an implementation.
       - In most cases, synchronization operations are implemented as inline assembly code; examples also exist, (e.g., for Intel® Itanium® processors) that use out-of-line assembly code in *.s or *.asm files (see the assembly code sub-directories in the src/tbb directory).
   - Modify include/tbb/tbb_machine.h, if needed, to invoke the appropriate <os>_<architecture>.h file in the include/tbb/machine directory.
2. Add an implementation of DetectNumberOfWorkers() in src/tbb/tbb_misc.h, that returns the number of cores found on the system in case it is not supported by the current implementation. This is used to determine the default number of threads for the Intel TBB task scheduler.
3. Either properly define FillDynamicLinks for use in src/tbb/cache_aligned_allocator.cpp, or hardcode the allocator to be used.
4. Additional types might be required in the union defined in include/tbb/aligned_space.h to ensure proper alignment on your platform.
5. Changes may be required in include/tbb/tick_count.h for systems that do not provide gettimeofday.

#### To port the Makefile infrastructure:

Modify the appropriate files in the Makefile infrastructure to add a new platform, operating system or architecture as needed. See the Makefile infrastructure files for examples.

1. The top-level Makefile includes common.inc to determine the operating system.
   - To add a new operating system, add the appropriate test to common.inc, and create the needed <os>.inc and <os>.<compiler>.inc files (see below).
2. The <os>.inc file makes OS-specific settings for a particular operating systems.
   - For example, linux.inc makes settings specific to Linux operating systems.
   - This file performs OS-dependent tests to determine the specific platform and/or architecture, and sets other platform-dependent values.
   - Add a new <os>.inc file for each new operating system added.
3. The <os>.<compiler>.inc file makes compiler-specific settings for a particular <os> / <compiler> combination.
   - For example, linux.gcc.inc makes specific settings for using GCC on Linux OS, and linux.icc.inc makes specific settings for using the Intel® C++ compiler on Linux OS.
   - This file sets particular compiler, assembler and linker options required when using a particular <os> / <compiler> combination.
   - Add a new <os>.<compiler>.inc file for each new <os> / <compiler> combination added.

Up to parent directory

Copyright © 2005-2017 Intel Corporation. All Rights Reserved.

Intel, the Intel logo and Itanium 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.