Installation

Here we discuss how to build and install t8code from the GitHub repository on a Linux machine. The build system t8code uses is CMake.

Build t8code

Requirements

• libsc (Automatically downloaded via CMake FetchContent)
• p4est (Automatically downloaded via CMake FetchContent)
• CMake (>v3.19)
• make
• A CPP Compiler supporting C++20
• MPI (>=v3.0) (MPI support for t8code is enabled by default. Disable this option if linking against MPI is not required.)

Installing

1. Clone the repository and fetch required submodules:

git clone [email protected]:DLR-AMR/t8code.git

2. Create a build directory CMake builds are done out-of-tree in a dedicated build directory. This is traditionally achieved by creating a build directory at the root of the repository:

mkdir build
cd build

2.5. Optional: specify the C and C++ compilers This step is not mandatory as CMake is usually able to infer this on its own, but we recommend exporting these variables prior to invoking CMake:

export CC="your favorite C compiler"
export CXX="your favorite C++ compiler"

If you are compiling with MPI it can also be helpful to directly set them to the MPI compilers:

export CC=mpicc
export CXX=mpic++

3. Invoke CMake Configure your build, and generate the corresponding Makefile:

cmake .. "append your build options here, see dedicated section"

A standard production build:

cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="path/to/your/favorite/folder" -DT8CODE_BUILD_TUTORIALS=OFF -DT8CODE_BUILD_EXAMPLES=OFF

4. Build and install t8code

make install

Known issues

• t8code uses the C++20 standard and older compiler versions might not support this. For example, g++ supports it fully since version 10.

Build options

You can use the standard CMake options, including CMAKE_CXX_FLAGS=FLAGS and CMAKE_C_FLAGS=FLAGS to set compiler flags.

On top of the standard CMake options, we provide the following build options:

CMake option	Description	Default value
T8CODE_ENABLE_MPI	Enable / disable MPI support	ON
T8CODE_ENABLE_VTK	Enable / disable VTK support	OFF
T8CODE_ENABLE_OCC	Enable / disable OpenCASCADE support	OFF
T8CODE_BUILD_AS_SHARED_LIBRARY	Install as a dynamic library (.so) / as a static library (.a)	ON
T8CODE_BUILD_WALL	Compile t8code with -Wall as done in the GitHub CI	OFF
T8CODE_BUILD_PEDANTIC	Compile t8code with -pedantic as done in the GitHub CI	OFF
T8CODE_BUILD_WERROR	Compile t8code with -Werror as done in the GitHub CI	OFF
T8CODE_BUILD_WEXTRA	Compile t8code with -Wextra	OFF
T8CODE_USE_SYSTEM_SC	Use system-installed sc library	OFF
T8CODE_USE_SYSTEM_P4EST	Use system-installed p4est library	OFF
T8CODE_BUILD_TESTS	Build the automated test suite (required for ctest)	ON
T8CODE_BUILD_TUTORIALS	Build the tutorials	ON
T8CODE_BUILD_EXAMPLES	Build the examples	ON
T8CODE_BUILD_BENCHMARKS	Build the benchmarks	ON
T8CODE_BUILD_FORTRAN_INTERFACE	Build t8code's Fortran interface	OFF
T8CODE_BUILD_DOCUMENTATION	Build the documentation	OFF
T8CODE_BUILD_SPHINX_DOCUMENTATION	Build documentation using sphinx	OFF
T8CODE_BUILD_TPL_EXAMPLES	Build the examples from the third party libraries sc and p4est	OFF
T8CODE_BUILD_TPL_TESTS	Build the test suites from the third party libraries sc and p4est	OFF
T8CODE_EXPORT_COMPILE_COMMANDS	Export the compile commands as .json (used by some IDEs)	OFF
T8CODE_TEST_LEVEL	How thoroughly/fast the test suite runs	T8_TEST_LEVEL_FULL
T8CODE_CUSTOM_PARALLEL_TEST_COMMAND	Pass a custom test command to the parallel tests	mpirun -np 4
T8CODE_CUSTOM_SERIAL_TEST_COMMAND	Build the test suites from the third party libraries sc and p4est	none

Using System SC and P4est

If you link with an installation of SC and P4est that did not come with t8code the download of the repositories can be disabled. If the CMake Options T8CODE_USE_SYSTEM_SC and/or T8CODE_USE_SYSTEM_P4EST are set to ON t8code will not download the repositories again.

Linking against t8code in your own CMake-based project

1. Insert an add_subdirectory( path/to/t8code/sources ) instruction in your top level CMakeLists.txt file
2. Add a target_link_libraries( your_target PRIVATE T8CODE::T8 ) instruction for each target depending on t8code

If you have installed t8code with the CMake build system, you can alternatively add to your CMakeLists.txt:

find_package( T8CODE REQUIRED )
target_link_libraries( your_target PRIVATE T8CODE::T8 )

When launching CMake, you may have to provide the root directory of t8code's installation:

cmake /path/to/project -DT8CODE_ROOT=/path/to/t8code/install/dir