docs/install.html
| | Taskflow: A General-purpose Task-parallel Programming System |
Loading...
Searching...
No Matches
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.
To use Taskflow v4.0.0, you need a compiler that supports C++20:
Taskflow works on Linux, Windows, and Mac OS X.
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++20 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++20 -I myproject/include/ -O2 -pthread -o simple
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/. 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:
| 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:
~$ cmake ../ -DTF_BUILD_EXAMPLES=OFF
The above command turns off building Taskflow examples.
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
Please visit the page Compile Taskflow with CUDA for details.
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:
~$ cmake ../ -DCMAKE_CXX_FLAGS="-fsanitize=thread -g"
~$ cmake ../ -DCMAKE_CXX_FLAGS="-fsanitize=address -g"
~$ 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.
NoteSome 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.
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
Please visit the page Benchmark Taskflow for details.
Taskflow uses Doxygen 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 and Graphviz:
~$ sudo apt-get install doxygen graphviz
~$ brew install doxygen graphviz
Once installed, navigate to the taskflow/doxygen folder and invoke Doxygen with the provided configuration file:
~$ cd taskflow/doxygen
~$ doxygen Doxyfile
You can find the documentation output in taskflow/docs. Open taskflow/docs/index.html in your browser to view it. Or launch a local http server to view the documentation:
cd /path/to/doxygen/html/output
python3 -m http.server 8080