# 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 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}
    ~$ 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:

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

    {.shell-session}
    ~$ 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/`. You can list a set of available options in the cmake.

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

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}
    # build Taskflow code with thread sanitizer to detect data race
    ~$ cmake ../ -DCMAKE_CXX_FLAGS="-fsanitize=thread -g"

    # build Taskflow code with address sanitizer to detect illegal memory access
    ~$ cmake ../ -DCMAKE_CXX_FLAGS="-fsanitize=address -g"

    # build Taskflow code with ub sanitizer to detect undefined behavior
    ~$ 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.

#### Attention

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}
    # ubuntu as an example
    ~$ sudo apt-get install doxygen graphviz

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

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

    {.shell-session}
    # 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`:

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

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

Tab / T to search, Esc to close
…

Search for symbols, directories, files, pages or modules. You can omit any prefix from the symbol or file path; adding a `:` or `/` suffix lists all members of given symbol or directory.

Use ↓ / ↑ to navigate through the list, Enter to go. Tab autocompletes common prefix, you can copy a link to the result using ⌘ L while ⌘ M produces a Markdown link.

Sorry, nothing was found.