Learn » How to Build

Required

• checkpoint, (vt ecosystem)
• MPI (mpich/openmpi/mvapich/IBM Spectrum MPI/Cray MPICH/etc.)

Automatically build dependencies

Assuming MPI is installed and accessible via CC/CXX, the only other dependency that is required is checkpoint. The easiest way to get these built are to clone it inside vt/lib:

$ git clone git@github.com:DARMA-tasking/vt
$ cd vt/lib
$ git clone git@github.com:DARMA-tasking/checkpoint

With these in vt/lib, cmake will automatically build them and stitch them into vt's linking process.

Using cmake directly

One may use cmake as normal on vt, with checkpoint cloned in vt/lib to compile them all together as explained above. The following are some custom configuration build options that can be provided to cmake to change the build configuration:

Using the Build Script

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

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

$ cd /usr/src
$ git clone git@github.com:DARMA-tasking/vt
$ VT_TRACE_ENABLED=1 CMAKE_BUILD_TYPE=Debug /usr/src/vt/ci/build_cpp.sh /usr/src/vt /usr/build/vt

Building with <tt>docker</tt> containerization

The easiest way to build vt 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 vt/.env, which docker compose will read.

# Variables:
#   ARCH={amd64, arm64v8, ...}
#   COMPILER_TYPE={gnu, clang, intel, nvidia}
#   COMPILER={gcc-9, gcc-10,
#             clang-8, clang-9, clang-10,
#             icpc, icpx,
#             nvcc-11, nvcc-11.2}
#   REPO=lifflander1/vt
#   UBUNTU={18.04, 20.04, 22.04}
#   ULIMIT_CORE=0
#
# DARMA/vt Configuration Variables:
#   VT_LB=1                   # Enable load balancing
#   VT_TRACE=0                # Enable tracing
#   VT_MIMALLOC=0             # Enable mimalloc memory allocator
#   VT_DOCS=0                 # Enable doxygen build
#   VT_TRACE_RT=0             # Enable tracing at runtime (for testing)
#   VT_ASAN=0                 # Enable address sanitizer
#   VT_UBSAN=0                # Enable undefined behavior sanitizer
#   VT_WERROR=1               # Treat all warnings as errors
#   VT_EXTENDED_TESTS=1       # Build all the extended testing
#   VT_ZOLTAN=0               # Build with Zoltan enabled
#   VT_UNITY_BUILD=0          # Build with Unity/Jumbo mode enabled
#   VT_FCONTEXT=0             # Force use of fcontext for threading
#   VT_DIAGNOSTICS=1          # Build with diagnostics enabled
#   VT_DIAGNOSTICS_RUNTIME=0  # Enable diagnostics at runtime by default
#   BUILD_TYPE=release        # CMake build type
#   VT_CODE_COVERAGE=0           # Enable generation of code coverage reports
#   VT_DEBUG_VERBOSE          # Enable verbose debug prints at compile-time
#   VT_NO_COLOR_ENABLED=0     # Set --vt_no_color flag to true by default
#   VT_BUILD_SHARED_LIBS=0    # Build VT as shared library

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 vt
$ docker compose run -e BUILD_TYPE=debug -e VT_TRACE=1 ubuntu-cpp

Or, alternatively, run a non-interactive build with alpine:

$ cd vt
$ docker compose run -e BUILD_TYPE=debug -e VT_TRACE=1 alpine-cpp

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

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

The same call applies to alpine distro builds if you swap ubuntu-cpp-interactive for alpine-cpp-interactive.

For more detailed information on configuring the docker build, read the documentation in vt/docker-compose.yml.