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.


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


Dependent Components

Build system variable


Required: Inlet, Sidre



Optional: Quest



Optional: Sidre



Optional: Inlet



Optional: Primal, Quest, Sidre



Optional: Mint, Spin, Quest



Optional: Sidre



Optional: Core, Spin, Quest


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.


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



Build System Variable


Code Style Checks



Static C/C++ code analysis



Source Code Docs



Code Coverage Reports



Multi-language binding generation



User Docs


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, 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, 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.


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

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

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

You can also see examples of how Spack spec names are passed to 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.


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

  • 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 Python script located in the Axom top-level directory:

$ ./ -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


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?


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:

$ ./

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

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

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    \
$ make
$ make install


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}                                \
$ make
$ make install

CMake Configuration Options

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

Axom components, tests, examples, etc.






Enable all components by default



Enable the Axom component named ‘Foo’

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

Overrides AXOM_ENABLE_ALL_COMPONENTS for the specified component.



Build Axom examples



Build Axom unit tests



Build Axom benchmarks



Enable Axom documentation to be built as a make target



Enable Axom development tools



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.


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






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 extra compiler warnings in all build targets



Compiler warnings treated as errors



Build shared libraries. Default is Static libraries



Enable Fortran compiler support



Enable MPI



Enable OpenMP



Enable CUDA



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.




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.


Path to CUDA software stack installation


Path to CUDA compiler (e.g. nvcc)


Target architecture(s) for CUDA


Path to HIP software stack installation


Target architecture(s) for HIP


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






Enable code coverage via gcov



Enable source code annotations to facilitate performance evaluation



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.