Configuration and Building

This section provides information about configuring and building the Axom software after you have cloned the repository. The main steps for using Axom are:

  1. Configure, build, and install third-party libraries (TPLs) on which Axom depends.

  2. Build and install Axom component libraries that you wish to use.

  3. Build and link your application with the Axom installation.

Depending on how your team uses Axom, some of these steps, such as installing the Axom TPLs and Axom itself, may need to be done only once. These installations can be shared across the team.

Requirements, Dependencies, and Supported Compilers

Basic requirements:

  • C++ compiler with C++14 support at a minimum

  • CMake with a minimum required version of 3.14 for CPU-only and CUDA builds, and a minimum version of 3.21 when building with HIP support

  • Fortran Compiler (optional)

Supported Compilers

Axom supports a wide variety of compilers. Please see the file axom/scripts/spack/configs/<platform>/spack.yaml for the current list of supported and tested compilers for the platforms we test on.

External Dependencies

Axom has two types of dependencies:

  • Libraries. These contain code that Axom must link against.

  • Tools. These are executables that we use during code development; e.g. generate documentation, format code, etc.

Unless noted otherwise in the following discussion, Axom dependencies are optional.

Note

A typical Axom user need only understand how to enable Axom features and provide a valid installation path for each required library dependency for each enabled feature.

Library Dependencies

The following table lists:

  • Axom external library dependencies and links to documentation for each library

  • Which libraries are required or optional dependencies for Axom. While most Axom libraries are not required, they are required to access all capabilities of components listed.

  • The CMake variable that must be set to the path of each library installation when configuring a build with the library

Library

Dependent Components

Build system variable

Adiak

Optional: Core

ADIAK_DIR

Caliper

Optional: Core

CALIPER_DIR

Conduit

Required: Inlet, Klee, Sidre

CONDUIT_DIR

c2c

Optional: Quest

C2C_DIR

HDF5

Optional: Sidre

HDF5_DIR

Lua

Optional: Inlet

LUA_DIR

MFEM

Optional: Primal, Quest, Sidre

MFEM_DIR

OPENCASCADE

Optional: Quest

OPENCASCADE_DIR

RAJA

Optional: Mint, Spin, Quest

RAJA_DIR

SCR

Optional: Sidre

SCR_DIR

Umpire

Optional: Core, Spin, Quest

UMPIRE_DIR

Note that each library dependency has a corresponding build system variable (with the suffix _DIR) to supply the path to the library’s installation directory. For example, hdf5 has a corresponding variable HDF5_DIR.

Note

Optional c2c library is currently only available for configurations on LLNL clusters.

Tool Dependencies

The following table lists:

  • Axom external tool dependencies, with links to documentation for each tool

  • The purpose of each tool; i.e., how it is used in Axom development

  • The CMake variable that must be set to the path of the tool installation to enable its use in Axom

Tool

Purpose

Build System Variable

clangformat

Code Style Checks

CLANGFORMAT_EXECUTABLE

CppCheck

Static C/C++ code analysis

CPPCHECK_EXECUTABLE

Doxygen

Source Code Docs

DOXYGEN_EXECUTABLE

Lcov

Code Coverage Reports

LCOV_EXECUTABLE

Shroud

Multi-language binding generation

SHROUD_EXECUTABLE

Sphinx

User Docs

SPHINX_EXECUTABLE

Each tool has a corresponding build system variable (with the suffix _EXECUTABLE) to supply a path to the tool executable. For example, sphinx has a corresponding build system variable SPHINX_EXECUTABLE.

Building and Installing Third-party Libraries

We use the Spack Package Manager to manage and build TPL dependencies for Axom on Linux and MacOS systems. Similarly, support for managing and building TPLs on Windows is provided through Vcpkg.

To make the TPL management process easier and automatic (you don’t really need to learn much about Spack or Vcpkg), we drive it with a Python script called uberenv.py, which is located in the scripts/uberenv directory. Running this script on Linux or MacOS does several things:

  • It clones the Spack repo from GitHub and checks out a specific version that we have tested.

  • It configures Spack compiler sets, adds custom package build rules, and sets any options specific to Axom.

  • It invokes Spack to build a complete set of TPLs for each configuration and generates a host-config file (i.e., CMake cache file) that includes all details of the configuration and build dependencies.

On Windows, uberenv.py takes analogous steps:

  • It clones the vcpkg repo from GitHub.

  • It specifies configuration details such as the “triplet,” specifying compiler, 64 vs 32-bits, and any other options specific to Axom.

  • It sets up vcpkg and then invokes vcpkg to build a set of TPLs. It also generates a host-config file that includes configuration details and build dependencies.

The figure illustrates what the script does.

../../../_images/Uberenv.jpg

The uberenv script is run from the top-level Axom directory like this:

$ python ./scripts/uberenv/uberenv.py --prefix {install path}  \
                                      --spec spec              \
                                    [ --mirror {mirror path} ]

For more details about uberenv.py and the options it supports, please see the uberenv docs

You can also see examples of how Spack spec names are passed to uberenv.py in the Python scripts we use to build TPLs for Axom development on LC platforms at LLNL. These scripts are located in the directory scripts/llnl_scripts.

Note

To get a full list of all Axom dependencies in an uberenv spack build of our TPLs, please go to the TPL root directory and run the following Spack command: ./spack/bin/spack spec axom. The analogous command for an uberenv vcpkg build is: .\vcpkg depend-info axom.

Building and Installing Axom

This section provides essential instructions for building the Axom code.

Axom uses BLT, a CMake-based system, to configure and build the code. There are two ways to configure Axom:

  • Using the helper Python script config-build.py

  • Directly invoke CMake from the command line

Either way, we typically pass in many of the configuration options and variables using platform-specific host-config files.

Host-config files

Host-config files help make the Axom configuration process more automatic and reproducible. A host-config file captures all build configuration information used for a build, such as compiler version and options, paths to all TPLs, etc. When passed to CMake (via the -C path/to/hostconfig/file/foo.cmake option), the host-config file initializes the CMake cache with the configuration contained in the file.

We noted earlier that the uberenv script generates a host-config file for each item in the Spack spec list given to it. These files are generated by Spack in the directory where the TPLs were installed. The name of each file contains information about the platform and spec.

For more information, see BLT host-config documentation.

Python helper script

The easiest way to configure Axom for compilation is to use the config-build.py Python script located in the Axom top-level directory:

$ ./config-build.py -hc path/to/host-config/file/<host-config file name>

The script runs CMake and passes it the given host-config file. See Host-config files for more information.

Running the script, as above, will create two directories to hold the build and install contents for the platform and compiler with names that match the name of the host-config file.

To build the code and install the header files, libraries, and documentation in the install directory, go into the build directory and run make and make install:

$ cd {build directory}
$ make
$ make install

Caution

When building on LC systems, please don’t compile on login nodes. You will incur the wrath of others and you really don’t want that, do you?

Tip

Most make targets can be run in parallel by supplying the ‘-j’ flag along with the number of threads to use. For example:

$ make -j 8

runs make using 8 threads.

The Python helper script accepts other arguments that allow you to specify explicitly the build and install paths and build type. Following CMake conventions, we support three build types: Release, RelWithDebInfo, and Debug (default). To see the script options, run the script without any arguments:

$ ./config-build.py

You can also pass extra CMake configuration variables to the script. For example:

$ ./config-build.py -hc path/to/host-config/<file name> \
                    -DBUILD_SHARED_LIBS=ON               \
                    -DENABLE_FORTRAN=OFF

This will configure CMake to build shared libraries and disable Fortran for the generated configuration.

Run CMake directly

You can also configure Axom by running CMake directly and passing it the appropriate arguments. For example, to configure, build and install a release build with the gcc compiler, you could pass a host-config file to CMake:

$ mkdir build-gcc-release
$ cd build-gcc-release
$ cmake -C {host config file for gcc compiler}           \
        -DCMAKE_BUILD_TYPE=Release                       \
        -DCMAKE_INSTALL_PREFIX=../install-gcc-release    \
        ../src/
$ make
$ make install

Note

Spack generates a host-config for us with many defaults that can be overridden on the command line. For example, CMAKE_BUILD_TYPE is set to Release. This can be overriden like the above command after the -C option.

Alternatively, you could forego the host-config file entirely and pass all the arguments you need, including paths to third-party libraries, directly to CMake; for example:

$ mkdir build-gcc-release
$ cd build-gcc-release
$ cmake -DCMAKE_C_COMPILER={path to gcc compiler}        \
        -DCMAKE_CXX_COMPILER={path to g++ compiler}      \
        -DCMAKE_BUILD_TYPE=Release                       \
        -DCMAKE_INSTALL_PREFIX=../install-gcc-release    \
        -DCONDUIT_DIR={path/to/conduit/install}          \
        {many other args}                                \
        ../src/
$ make
$ make install

CMake Configuration Options

The tables in this section summarize the main build system options in Axom.

Axom components, tests, examples, etc.

OPTION

Default

Description

AXOM_ENABLE_ALL_COMPONENTS

ON

Enable all components by default

AXOM_ENABLE_<FOO>

ON

Enable the Axom component named ‘Foo’

(e.g. AXOM_ENABLE_SIDRE) for the Sidre component.

Overrides AXOM_ENABLE_ALL_COMPONENTS for the specified component.

AXOM_ENABLE_EXAMPLES

ON

Build Axom examples

AXOM_ENABLE_TESTS

ON

Build Axom unit tests

ENABLE_BENCHMARKS

OFF

Build Axom benchmarks

AXOM_ENABLE_DOCS

ON

Enable Axom documentation to be built as a make target

AXOM_ENABLE_TOOLS

ON

Enable Axom development tools

AXOM_DEPRECATED_TYPES

WARN

WARN, ALLOW or ERROR on using deprecated types

If AXOM_ENABLE_ALL_COMPONENTS is OFF, you must explicitly enable a desired component (other than ‘core’, which is always enabled). Similarly, if AXOM_ENABLE_ALL_COMPONENTS is ON, you can disable individual components by setting AXOM_ENABLE_<FOO> to OFF for the component you want turned off.

See Axom software documentation for a list of Axom components and their dependencies. Note that when enabling an external dependency for an Axom component, the CMake variable BAR_DIR must be set to a valid path to the dependency installation. See External Dependencies for a complete listing of configuration variables to specify paths to Axom external dependencies.

Note

AXOM_ENABLE_EXAMPLES, AXOM_ENABLE_TESTS, and AXOM_ENABLE_DOCS are CMake-dependent options. Thus, if a variable without the AXOM_ prefix is ON, such as ENABLE_TESTS, tests can be enabled in other packages in a project build and turned off in Axom by setting the Axom prefix form AXOM_ENABLE_TESTS to OFF.

Axom build options, compiler support, and parallelism

OPTION

Default

Description

AXOM_DEBUG_DEFINE

DEFAULT

Controls whether the AXOM_DEBUG compiler define is enabled

By DEFAULT, it is enabled for Debug and RelWithDebInfo configs but this can be overridden by setting AXOM_DEBUG_DEFINE to ON or OFF

ENABLE_ALL_WARNINGS

ON

Enable extra compiler warnings in all build targets

ENABLE_WARNINGS_AS_ERRORS

OFF

Compiler warnings treated as errors

BUILD_SHARED_LIBS

OFF

Build shared libraries. Default is Static libraries

ENABLE_FORTRAN

OFF

Enable Fortran compiler support

AXOM_ENABLE_MPI

OFF

Enable MPI

AXOM_ENABLE_OPENMP

OFF

Enable OpenMP

AXOM_ENABLE_CUDA

OFF

Enable CUDA

AXOM_ENABLE_HIP

OFF

Enable HIP

Note that, in most Axom components, node-level parallelism features, enabled with OpenMP, CUDA (NVIDIA GPUs), and HIP (AMD GPUs), are implemented using RAJA. See External Dependencies for instructions to set the directory location of a RAJA installation. In addition, enabling such features may require additional build options to be provided, which are summarized in the following table.

OPTION

Description

RAJA_DIR

RAJA installation directory as described in External Dependencies.

RAJA must be built with support enabled for OpenMP, CUDA, or HIP to use features enabled by those parallel programming models in Axom.

CUDA_TOOLKIT_ROOT_DIR

Path to CUDA software stack installation

CMAKE_CUDA_COMPILER

Path to CUDA compiler (e.g. nvcc)

CMAKE_CUDA_ARCHITECTURES

Target architecture(s) for CUDA

HIP_ROOT_DIR

Path to HIP software stack installation

CMAKE_HIP_ARCHITECTURES

Target architecture(s) for HIP

Note

To configure the version of the C++ standard, you can supply one of the following values for BLT_CXX_STD: ‘c++11’ or ‘c++14’. Axom requires at least ‘c++14’, the default value.

Tools and features primarily intended for developers

OPTION

Default

Description

ENABLE_CODECOV

ON

Enable code coverage via gcov

AXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS

OFF

Enable an expanded set of tests for the Axom Quest component

Axom source code macro constants

Axom developers, please note that Axom provides macro constants to control conditionally-compiled code based on which built-in and third-party libraries are being used and which Axom components are enabled. Please see Conditionally compiled code for more information.

Make targets

Our system provides a variety of make targets to build individual Axom components, documentation, run tests, examples, etc. After running CMake (using either the Python helper script or directly), you can see a listing of all available targets by passing ‘help’ to make; i.e.,:

$ make help

The name of each target should be sufficiently descriptive to indicate what the target does. For example, to run all tests and make sure the Axom components are built properly, execute the following command:

$ make test

Compiling and Linking with an Application

Please see Preparing Windows WSL/Ubuntu for Axom installation for examples of how to use Axom in your project.