install

# Building and Installing

Compile Taskflow with CUDA
Benchmark Taskflow
Supported Compilers

Supported Compilers

install_1BAISupportedCompilers
Integrate Taskflow to Your Project

Integrate Taskflow to Your Project

install_1BAIIntegrateTaskflowToYourProject
Build Examples and Unit Tests

Build Examples and Unit Tests

install_1BAIBuildExamplesAndUnitTests
Build CUDA Examples and Unit Tests

Build CUDA Examples and Unit Tests

install_1BAIBuildCUDACode
Build Sanitizers

Build Sanitizers

install_1BAIBuildSanitizers
Build Benchmarks

Build Benchmarks

install_1BAIBuildBenchmarks
Build Documentation

Build Documentation

install_1BAIBuildDocumentation

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 Xcode 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.

    {.shell-session}
    ~$gitclonehttps://github.com/taskflow/taskflow.git
    ~$cdtaskflow/
    ~$cp-rtaskflowmyproject/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:

    {.shell-session}
    ~$g++simple.cpp-std=c++17-Imyproject/include/-O2-pthread-osimple

# Build Examples and Unit Tests

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

    {.shell-session}
    ~$cdpath/to/taskflow
    ~$mkdirbuild
    ~$cdbuild
    ~$cmake../
    ~$make#compileallexamplesandunittests
    ~$maketest

    Runningtests...
    /usr/bin/ctest--force-new-ctest-process
    Testproject/home/tsung-wei/Code/taskflow/build
    Start1:passive_vector
    1/254Test#1:passive_vector...................Passed0.04sec
    Start2:function_traits
    2/254Test#2:function_traits..................Passed0.00sec
    Start3:object_pool.sequential
    3/254Test#3:object_pool.sequential...........Passed0.10sec
    ...

    100%testspassed,0testsfailedoutof254

    TotalTesttime(real)=29.67sec

When the building completes, you can find the executables for examples and tests under the two folders, `examples/` and `unittests/`. You can list a set of available options in the cmake.

    {.shell-session}
    ~$cmake-LA
    ...
    TF_BUILD_EXAMPLES:BOOL=ON#bydefault,wecompileexamples
    TF_BUILD_TESTS:BOOL=ON#bydefault,wecompiletests
    TF_BUILD_BENCHMARKS:BOOL=OFF#bydefault,wedon'tcompilebenchmarks
    TF_BUILD_CUDA:BOOL=OFF#bydefault,wedon'tcompileCUDAcode
    ...
    ...moreoptions

Currently, our CMake script supports the following options:

CMake Option | Default | Usage
TF_BUILD_EXAMPLES | ON | enable/disable building examples
TF_BUILD_TESTS | ON | enable/disable building unit tests
TF_BUILD_BENCHMARKS | OFF | enable/disable building benchmarks
TF_BUILD_CUDA | OFF | enable/disable building CUDA code

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

    {.shell-session}
    ~$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.

    {.shell-session}
    ~$cmake../-DTF_BUILD_CUDA=ON
    ~$make

Please visit the page Compile Taskflow with CUDA for details.

# Build Sanitizers

You can build Taskflow with sanitizers to detect a variety of errors, such as data race, memory leak, undefined behavior, and others. To enable a sanitizer, add the sanitizer flag to the CMake variable `CMAKE_CXX_FLAGS`. The following example enables thread sanitizer in building Taskflow code to detect data race:

    {.shell-session}
    #buildTaskflowcodewiththreadsanitizertodetectdatarace
    ~$cmake../-DCMAKE_CXX_FLAGS="-fsanitize=thread-g"

    #buildTaskflowcodewithaddresssanitizertodetectillegalmemoryaccess
    ~$cmake../-DCMAKE_CXX_FLAGS="-fsanitize=address-g"

    #buildTaskflowcodewithubsanitizertodetectundefinedbehavior
    ~$cmake../-DCMAKE_CXX_FLAGS="-fsanitize=undefined-g"

Our continuous integration workflows incorporates thread sanitizer (-fsanitize=thread), address sanitizer (-fsanitize=address), and leak sanitizer (-fsanitize=leak) to detect data race, illegal memory address, and memory leak. To our best knowledge, Taskflow is one of the very few parallel programming libraries that are free from data race.

Some sanitizers are supported by certain computing architectures. You can find the information about architecture support of each sanitizer at Clang Documentation and GCC Instrumentation Options.

# 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:

    {.shell-session}
    ~$cmake../-DTF_BUILD_BENCHMARKS=ON
    ~$make

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, you need to first install doxygen:

    {.shell-session}
    #ubuntuasanexample
    ~$sudoapt-getinstalldoxygengraphviz

Once you have doxygen and dot graph generator installed, clone the m.css project and enter the `m.css/documentation` directory:

    {.shell-session}
    ~$gitclonehttps://github.com/mosra/m.css.git
    ~$cdm.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:

    {.shell-session}
    #Youmayneedsudohere
    #Moredetailsareavailableathttps://mcss.mosra.cz/documentation/doxygen/
    ~$pip3installjinja2Pygments

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

    {.shell-session}
    ~$./doxygen.pypath/to/taskflow/doxygen/conf.py

You can find the documentation output in `taskflow/docs`.