Installation

Here, we discuss how to build and install t8code from the GitHub repository on a Linux machine. The default build system is CMake. The old build system autotools is declared deprecated and will be completely removed with the next breaking release of t8code. Till then the install instructions can be found here.

Build t8code with CMake

Requirements

• libsc (Included in t8code's git repository)
• p4est (Included in t8code's git repository)
• CMake (>v3.16)
• make
• MPI (MPI support for t8code is enabled by default. Disable this option if linking against MPI is not required.)

Installing with CMake

0. Clone the repository and fetch needed submodules:

git clone git@github.com:DLR-AMR/t8code.git
cd t8code
git submodule init
git submodule update

1. 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. 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"

3. Invoke CMake Configure your build of CMake, 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

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_PEDANTIC	Compile t8code with -Wall -pedantic -Werror as done in the Github CI	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 make test)	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

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

---

Build t8code with autotools

Autotools is considered deprecated and will be completely removed with the next breaking release.

Requirements

t8code uses autotools and you will basically need

• libsc (Included in t8code's git repository)
• p4est (Included in t8code's git repository)
• automake
• libtool
• make
• MPI (MPI support for t8code is enabled by default. Disable this option if linking against MPI is not required.)

Optional

• The VTK library for advanced VTK output (basic VTK output is provided without linking against VTK)
• The NetCFD library for NetCFD file output
• The OpenCASCADE library for CAD-based refinement

Installation

Clone the repository or download the latest release

To install t8code from GitHub on a Linux machine, first clone the repository or download the latest release, for example with

git clone git@github.com:DLR-AMR/t8code.git

or

git clone https://github.com/DLR-AMR/t8code

Notes for cloning from a newly created fork

(Release) tags are not automatically copied to a fork. But since the configure script determines the t8code version through the git tags, they have to be present. Otherwise, the configure and make step will fail. Therefore, it may be necessary to set the upsteam remote repository and to update the tags on the fork:

git fetch --tags upstream
git push --tags

By enabling the following option, tags get automatically pushed alongside with commits with git push. This way the tags will always be updated when the main branch of the fork is updated:

git config push.followTags true

To enable the option globally for all git repositories on the computer just add a --global.

git config --global push.followTags true

Initialize the submodules

t8code uses libsc and p4est as submodules. To download and initialize these, use

git submodule init
git submodule update

Bootstrap

Call the bootstrap script:

./bootstrap

Configure t8code

You now created a configure script ./configure in the t8code folder. Executing this script will create the t8code Makefiles.

Create a folder where you wish to build t8code into. Switch to it and execute the configure script. For the sake of this tutorial, we will choose ~/t8code_build and assume that the repository was cloned into ~/t8code.

mkdir t8code_build
cd ~/t8code_build
../t8code/configure [OPTIONS]

You can choose from various options to configure t8code. To see a list of possible configure options, call

 ./configure -h

For a more elaborate overview please see the Configure options wiki page.

The most common options are

Option	Description
--enable-mpi	enable MPI parallel code
--enable-debug	enable debugging mode (Note: This will drastically reduce performance)
--with-LIB/--without-LIB	(enable/disable linking with LIB)
--prefix=PATH	Provide an installation prefix
CFLAGS=	Provide C compiler flags
CXXFLAGS=	Provide C++ compiler flags
CC=	Set the C compiler
CXX=	Set the C++ compiler

For a quick release mode configuration we recommend:

configure CFLAGS="-O3" CXXFLAGS="-O3" --enable-mpi CC=mpicc CXX=mpicxx

For a debugging mode configuration (mostly used by developers), you can use

configure CFLAGS="-Wall -O0 -g" CXXFLAGS="-Wall -O0 -g" --enable-mpi --enable-debug --enable-static --disable-shared CC=mpicc CXX=mpicxx

Note: enable-static and disable-shared allow you to properly use debugging tools such as gdb or valgrind.

Build t8code

The configure script should now have created the t8code Makefiles and you can build t8code.

make -j
make install -j

Checking

After a new installation you should run the t8code test programs. To do so, run

make check

or

make check -j

If any of the tests fail, something in the configuration or on your system does not work properly and you should not use t8code in this configuration.

If you cannot figure out, what causes the problem, feel free to contact the developers.

Linking against t8code

To use t8code as an external library and link against it, first you need to install it according to the above instructions or obtain an installation via another way. Your code must link against t8code, p4est, libsc, libz and libm. Usually p4est and libsc are shipped with t8code. If you did not obtain them with t8code you need to install them separately.

For the sake of the argument let's say the install folder is $HOME/t8code_install.

1. Add the library folder to LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/t8code_install/lib

2. Add these to your compile line

-I$HOME/t8code_install/include
-L$HOME/t8code_install/lib
-lt8 -lp4est -lsc -lm -lz