Learn » How to Build

magistrate can be built with cmake.

Building

To build magistrate, one must obtain the following dependencies:

Optional

gtest, (if testing magistrate is enabled)
MPI, (if MPI tests are enabled)
Kokkos, (if Kokkos views need to be serialized)
KokkosKernels, (if Kokkos kernel data structures need to be serialized)

Using cmake directly

One may use cmake to build magistrate once the dependencies are installed. The following are some options that can be provided to cmake to change the build configuration:

CMake Variable	Default Value	Description
`gtest_DIR`		Install directory for googletest
`Kokkos_DIR`		Install directory for kokkos
`KokkosKernels_DIR`		Install directory for kokkoskernels
`magistrate_tests_enabled`	0	Build magistrate tests
`magistrate_mpi_enabled`	0	Build magistrate with MPI for tests
`magistrate_examples_enabled`	0	Build magistrate examples
`magistrate_warnings_as_errors`	0	Make all warnings errors during build
`magistrate_doxygen_enabled`	0	Enable doxygen generation
`magistrate_asan_enabled`	0	Enable address sanitizer
`magistrate_ubsan_enabled`	0	Enable undefined behavior sanitizer
`magistrate_serialization_error_checking_enabled(*)`	0	Enable extensive serialization error checking
`CODE_COVERAGE`	0	Generate code coverage report

note that if magistrate_serialization_error_checking_enabled is not explicitly enabled or disabled, it will be enabled for Debug and RelWithDebInfo builds and disabled for others.

Using the Build Script

Instead of running cmake, one may invoke the magistrate/ci/build_cpp.sh script which will run cmake for magistrate with environment variables for most configuration parameters.

Build Script Environment Variables

Variable	Default Value	Description
`CMAKE_BUILD_TYPE`	Release	The `cmake` build type
`CODE_COVERAGE`	0	Enable code coverage reporting
`GTEST_ROOT`	<empty>	Install directory for googletest
`KOKKOS_ROOT`	<empty>	Install directory for kokkos
`KOKKOS_KERNELS_ROOT`	<empty>	Install directory for kokkos-kernels
`MAGISTRATE_DOXYGEN_ENABLED`	0	Enable doxygen generation
`MAGISTRATE_ASAN_ENABLED`	0	Enable building with address sanitizer
`MAGISTRATE_UBSAN_ENABLED`	0	Enable building with undefined behavior sanitizer
`MAGISTRATE_TESTS_ENABLED`	1	Enable magistrate tests
`MAGISTRATE_EXAMPLES_ENABLED`	1	Enable magistrate examples
`MAGISTRATE_WARNINGS_AS_ERRORS`	0	Make all warnings errors during build
`MAGISTRATE_SERIALIZATION_ERROR_CHECKING_ENABLED`	0	Enable extensive error checking of serialization
`MAGISTRATE_MPI_ENABLED`	1	Enable magistrate MPI for testing

note that if MAGISTRATE_SERIALIZATION_ERROR_CHECKING_ENABLED is not explicitly enabled or disabled, it will be enabled for Debug and RelWithDebInfo builds and disabled for others.

With these set, invoke the script with two arguments: the path to the magistrate root directory and the build path. Here's an example assuming that magistrate is cloned into /usr/src/magistrate with trace enabled in debug mode.

Usage for building:

$ magistrate/ci/build_cpp.sh <full-path-to-magistrate-source> <full-path-to-build-dir>

Building with docker containerization

The easiest way to build magistrate is by using docker with the available containers that contain the proper compilers, MPI, and all other dependencies. First, install docker on the system. On some systems, docker-compose might also need to be installed.

The docker builds are configured through docker-compose to use a shared, cached filesystem mount with the host for ccache to enable fast re-builds.

For docker-compose, the following variables can be set to configure the build. One may configure the architecture, compiler type (GNU, Clang, Intel, Nvidia) and compiler version, Linux distro (ubuntu or alpine), and distro version.

The default set of the docker configuration options is located in magistrate/.env, which docker-compose will read.

# Variables:
#   ARCH={amd64, arm64v8, ...}
#   COMPILER_TYPE={gnu, clang, intel, nvidia}
#   COMPILER={gcc-8, gcc-9, gcc-10,
#             clang-5.0, clang-6.0, clang-7, clang-8,
#             clang-9, clang-10,
#             icc-18, icc-19,
#             nvcc-10, nvcc-11}
#   REPO=lifflander1/checkpoint
#   UBUNTU={18.04, 20.04}
#   ULIMIT_CORE=0
#
# DARMA/magistrate Configuration Variables:
#   MAGISTRATE_TESTS=1                        # Enable magistrate tests
#   MAGISTRATE_EXAMPLES=1                     # Enable magistrate examples
#   MAGISTRATE_MPI=1                          # Enable magistrate MPI tests
#   MAGISTRATE_WARNINGS_AS_ERRORS=0           # Treat warnings as errors in compilation
#   MAGISTRATE_ASAN=0                         # Enable address sanitizer in build
#   MAGISTRATE_UBSAN=0                        # Enable undefined behavior sanitizer in build
#   MAGISTRATE_SERIALIZATION_ERROR_CHECKING=0 # Enable extensive serialization error checking
#   MAGISTRATE_DOCS=0                         # Enable doxygen build
#   BUILD_TYPE=release                        # CMake build type
#   CODE_COVERAGE=0                           # Enable generation of code coverage reports

With these set, one may run the following for a non-interactive build with ubuntu. Or, to speed up the build process, the base container can be pulled for many of the common configurations: docker-compose pull ubuntu-cpp.

$ cd magistrate
$ docker-compose run -e BUILD_TYPE=debug ubuntu-cpp

For an interactive build with ubuntu, where one can build, debug, and run valgrind, etc:

$ cd magistrate
$ docker-compose run -e BUILD_TYPE=debug ubuntu-cpp-interactive
# /magistrate/ci/build_cpp.sh /magistrate /build
# /magistrate/ci/test_cpp.sh /magistrate /build