225 lines
7.4 KiB
Text
225 lines
7.4 KiB
Text
namespace tf {
|
|
|
|
/** @page install 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.
|
|
|
|
@tableofcontents
|
|
|
|
@section BAISupportedCompilers Supported Compilers
|
|
|
|
To use %Taskflow, you only need a compiler that supports C++17:
|
|
|
|
@li GNU C++ Compiler at least v8.4 with -std=c++17
|
|
@li Clang C++ Compiler at least v6.0 with -std=c++17
|
|
@li Microsoft Visual Studio at least v15.7 (MSVC++ 19.14)
|
|
@li AppleClang Xcode Version at least v12.0 with -std=c++17
|
|
@li Nvidia CUDA Toolkit and Compiler (nvcc) at least v11.1 with -std=c++17
|
|
@li Intel C++ Compiler (nvcc) at least v19.0.1 with -std=c++17
|
|
@li Intel DPC++ Clang Compiler at least v13.0.0 with -std=c++17 and SYCL20
|
|
|
|
%Taskflow works on Linux, Windows, and Mac OS X.
|
|
|
|
@section BAIIntegrateTaskflowToYourProject 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 @c taskflow/
|
|
to your project.
|
|
|
|
@code{.shell-session}
|
|
~$ git clone https://github.com/taskflow/taskflow.git
|
|
~$ cd taskflow/
|
|
~$ cp -r taskflow myproject/include/
|
|
@endcode
|
|
|
|
%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 <tt>simple.cpp</tt>, you need to tell the compiler
|
|
where to find the %Taskflow header files and link it through the system thread library
|
|
(usually [POSIX threads](http://man7.org/linux/man-pages/man7/pthreads.7.html) in Linux-like systems).
|
|
Take gcc for an example:
|
|
|
|
@code{.shell-session}
|
|
~$ g++ simple.cpp -std=c++17 -I myproject/include/ -O2 -pthread -o simple
|
|
@endcode
|
|
|
|
|
|
@section BAIBuildExamplesAndUnitTests Build Examples and Unit Tests
|
|
|
|
%Taskflow uses CMake to build examples and unit tests.
|
|
We recommend using out-of-source build.
|
|
|
|
@code{.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
|
|
@endcode
|
|
|
|
When the building completes, you can find the executables for examples and tests
|
|
under the two folders, @c examples/ and @c unittests/.
|
|
You can list a set of available options in the cmake.
|
|
|
|
@code{.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
|
|
@endcode
|
|
|
|
Currently, our CMake script supports the following options:
|
|
|
|
<div align="center">
|
|
| 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 |
|
|
</div>
|
|
|
|
To enable or disable a specific option, use @c -D in the CMake build.
|
|
For example:
|
|
|
|
@code{.shell-session}
|
|
~$ cmake ../ -DTF_BUILD_EXAMPLES=OFF
|
|
@endcode
|
|
|
|
The above command turns off building %Taskflow examples.
|
|
|
|
@section BAIBuildCUDACode Build CUDA Examples and Unit Tests
|
|
|
|
To build CUDA code, including unit tests and examples,
|
|
enable the CMake option @c TF_BUILD_CUDA to @c ON.
|
|
Cmake will automatically detect the existence of @c nvcc
|
|
and use it to compile and link @c .cu code.
|
|
|
|
@code{.shell-session}
|
|
~$ cmake ../ -DTF_BUILD_CUDA=ON
|
|
~$ make
|
|
@endcode
|
|
|
|
Please visit the page @subpage CompileTaskflowWithCUDA for details.
|
|
|
|
|
|
@section BAIBuildSanitizers Build Sanitizers
|
|
|
|
You can build %Taskflow with @em 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:
|
|
|
|
@code{.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"
|
|
@endcode
|
|
|
|
Our @CI incorporates
|
|
thread sanitizer ([-fsanitize=thread](https://clang.llvm.org/docs/ThreadSanitizer.html)),
|
|
address sanitizer ([-fsanitize=address](https://clang.llvm.org/docs/AddressSanitizer.html)), and
|
|
leak sanitizer ([-fsanitize=leak](https://clang.llvm.org/docs/LeakSanitizer.html))
|
|
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.
|
|
|
|
@note
|
|
Some sanitizers are supported by certain computing architectures.
|
|
You can find the information about architecture support of each sanitizer at
|
|
[Clang Documentation](https://clang.llvm.org/docs/index.html) and
|
|
[GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html).
|
|
|
|
@section BAIBuildBenchmarks 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 @c TF_BUILD_BENCHMARKS to @c ON as follows:
|
|
|
|
@code{.shell-session}
|
|
~$ cmake ../ -DTF_BUILD_BENCHMARKS=ON
|
|
~$ make
|
|
@endcode
|
|
|
|
Please visit the page @subpage BenchmarkTaskflow for details.
|
|
|
|
@section BAIBuildDocumentation Build Documentation
|
|
|
|
%Taskflow uses @Doxygen and @MCSS to generate this documentation.
|
|
The source of documentation is located in the folder @c taskflow/doxygen
|
|
and the generated html is output to the folder @c taskflow/docs.
|
|
To generate the documentation, you need to first install doxygen:
|
|
|
|
@code{.shell-session}
|
|
# ubuntu as an example
|
|
~$ sudo apt-get install doxygen graphviz
|
|
@endcode
|
|
|
|
Once you have doxygen and dot graph generator installed, clone the m.css project and enter
|
|
the @c m.css/documentation directory:
|
|
|
|
@code{.shell-session}
|
|
~$ git clone https://github.com/mosra/m.css.git
|
|
~$ cd m.css/documentation
|
|
@endcode
|
|
|
|
The script @c doxygen.py requires Python 3.6, depends on
|
|
<a href="http://jinja.pocoo.org/">Jinja2</a> for templating and
|
|
<a href="http://pygments.org/">Pygments</a> for code block highlighting.
|
|
You can install the dependencies via @c pip or your distribution package manager:
|
|
|
|
@code{.shell-session}
|
|
# You may need sudo here
|
|
# More details are available at https://mcss.mosra.cz/documentation/doxygen/
|
|
~$ pip3 install jinja2 Pygments
|
|
@endcode
|
|
|
|
Next, invoke @c doxygen.py and point it to the @c taskflow/doxygen/conf.py:
|
|
|
|
@code{.shell-session}
|
|
~$ ./doxygen.py path/to/taskflow/doxygen/conf.py
|
|
@endcode
|
|
|
|
You can find the documentation output in @c taskflow/docs.
|
|
|
|
*/
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|