Building and Installing

This page describes how to set up Taskflow in your project. We will also go through the building process of unit tests and examples.

Supported Compilers

To use Taskflow, you only need a compiler that supports C++17:

• GNU C++ Compiler at least v8.4 with -std=c++17
• Clang C++ Compiler at least v6.0 with -std=c++17
• Microsoft Visual Studio at least v15.7 (MSVC++ 19.14)
• AppleClang Xode Version at least v12.0 with -std=c++17
• Nvidia CUDA Toolkit and Compiler (nvcc) at least v11.1 with -std=c++17
• Intel C++ Compiler (nvcc) at least v19.0.1 with -std=c++17
• Intel DPC++ Clang Compiler at least v13.0.0 with -std=c++17 and SYCL20

Taskflow works on Linux, Windows, and Mac OS X.

Integrate Taskflow to Your Project

Taskflow is header-only and there is no need for installation. Simply download the source and copy the headers under the directory taskflow/ to your project.

~$ git clone https://github.com/taskflow/taskflow.git
~$ cd taskflow/
~$ cp -r taskflow myproject/include/

Taskflow is written in C++17 and is built on top of C++ standardized threading libraries to improve portability. To compile a Taskflow program, say simple.cpp, you need to tell the compiler where to find the Taskflow header files and link it through the system thread library (usually POSIX threads in Linux-like systems). Take gcc for an example:

~$ g++ simple.cpp -std=c++17 -I myproject/include/ -O2 -pthread -o simple

Build Examples and Unit Tests

Taskflow uses CMake to build examples and unit tests. We recommend using out-of-source build.

~$ cd path/to/taskflow
~$ mkdir build
~$ cd build
~$ cmake ../
~$ make                         # compile all examples and unittests
~$ make test

Running tests...
/usr/bin/ctest --force-new-ctest-process
Test project /home/tsung-wei/Code/taskflow/build
        Start   1: passive_vector
  1/254 Test   #1: passive_vector ...................   Passed    0.04 sec
        Start   2: function_traits
  2/254 Test   #2: function_traits ..................   Passed    0.00 sec
        Start   3: object_pool.sequential
  3/254 Test   #3: object_pool.sequential ...........   Passed    0.10 sec
...

100% tests passed, 0 tests failed out of 254

Total Test time (real) =  29.67 sec

When the building completes, you can find the executables for examples and tests under the two folders, examples/ and unittests/.

Configure CMake Options

You can list a set of available options in the cmake.

~$ cmake -LA
...
TF_BUILD_EXAMPLES:BOOL=ON       # by default, we compile examples
TF_BUILD_TESTS:BOOL=ON          # by default, we compile tests
TF_BUILD_BENCHMARKS:BOOL=OFF    # by default, we don't compile benchmarks 
TF_BUILD_CUDA:BOOL=OFF          # by default, we don't compile CUDA code
...
... more options

Currently, our CMake script supports the following options:

To enable or disable a specific option, use -D in the CMake build. For example:

~$ cmake ../ -DTF_BUILD_EXAMPLES=OFF

The above command turns off building Taskflow examples.

Build CUDA Examples and Unit Tests

To build CUDA code, including unit tests and examples, enable the CMake option TF_BUILD_CUDA to ON. Cmake will automatically detect the existence of nvcc and use it to compile and link .cu code.

~$ cmake ../ -DTF_BUILD_CUDA=ON
~$ make

Compile Taskflow with CUDA

Please visit the page Compile Taskflow with CUDA for details.

Build SYCL Code Examples and Unit Tests

To build SYCL code, including unit tests and examples, enable the CMake option TF_BUILD_SYCL to ON and direct the CMake compiler CMAKE_CXX_COMPILER to the location of DPC++ clang compiler. You can acquire the DPC++ clang compiler at the official page of Getting Started with oneAPI DPC++.

# after succesfully build Intel DPCPP clang: https://intel.github.io/llvm-docs/
~$ export DPCPP_HOME=/path/to/your/dpcpp/workspace
~$ export PATH=$DPCPP_HOME/llvm/build/bin:$PATH
~$ export LD_LIBRARY_PATH=$DPCPP_HOME/llvm/build/lib:$LD_LIBRARY_PATH

# build Taskflow SYCL code using Intel oneAPI dpc++ clang compiler
~$ cmake ../ -DTF_BUILD_SYCL=ON -DCMAKE_CXX_COMPILER=clang++
~$ make

Compile Taskflow with SYCL

Please visit the page Compile Taskflow with SYCL for details.

Build Benchmarks

The Taskflow project contains a set of benchmarks to evaluate and compare the performance of Taskflow with existing parallel programming libraries. To build the benchmark code, enable the CMake option TF_BUILD_BENCHMARKS to ON as follows:

~$ cmake ../ -DTF_BUILD_BENCHMARKS=ON
~$ make

Benchmark Taskflow

Please visit the page Benchmark Taskflow for details.

Build Documentation

Taskflow uses Doxygen and m.css to generate this documentation. The source of documentation is located in the folder taskflow/doxygen and the generated html is output to the folder taskflow/docs. To generate the documentation, clone the m.css project and enter the m.css/documentation directory:

~$ git clone git://github.com/mosra/m.css
~$ cd m.css/documentation

The script doxygen.py requires Python 3.6, depends on Jinja2 for templating and Pygments for code block highlighting. You can install the dependencies via pip or your distribution package manager:

# You may need sudo here
# More details are available at https://mcss.mosra.cz/documentation/doxygen/
~$ pip3 install jinja2 Pygments

Next, invoke doxygen.py and point it to the taskflow/doxygen/conf.py:

~$ ./doxygen.py path/to/taskflow/doxygen/conf.py

You can find the documentation output in taskflow/docs.