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 v4.0.0, you need a compiler that supports C++20:

@li GNU C++ Compiler at least v11.0 with -std=c++20
@li Clang C++ Compiler at least v12.0 with -std=c++20
@li Microsoft Visual Studio at least v19.29 (VS 2019) with /std:c++20
@li Apple Clang (Xcode) at least v13.0 with -std=c++20
@li NVIDIA CUDA Toolkit and Compiler (nvcc) at least v12.0 with host compiler supporting C++20
@li Intel oneAPI DPC++/C++ Compiler at least v2022.0 with -std=c++20


%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{.bash}
~$ git clone https://github.com/taskflow/taskflow.git
~$ cd taskflow/
~$ cp -r taskflow myproject/include/
@endcode

%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 <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{.bash}
~$ g++ simple.cpp -std=c++20 -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{.bash}
~$ 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{.bash}
~$ 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{.bash}
~$ 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{.bash}
~$ 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{.bash}
# 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.

@attention
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{.bash}
~$ cmake ../ -DTF_BUILD_BENCHMARKS=ON
~$ make
@endcode

Please visit the page @subpage BenchmarkTaskflow for details.

@section BAIBuildDocumentation Build Documentation

%Taskflow uses @Doxygen 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 and Graphviz:

@code{.bash}
# Ubuntu
~$ sudo apt-get install doxygen graphviz

# macOS
~$ brew install doxygen graphviz
@endcode

Once installed, navigate to the @c taskflow/doxygen folder and invoke Doxygen
with the provided configuration file:

@code{.bash}
~$ cd taskflow/doxygen
~$ doxygen Doxyfile
@endcode

You can find the documentation output in @c taskflow/docs.
Open @c taskflow/docs/index.html in your browser to view it.

*/

}








