Zero to Axom: Quick install of Axom and Third Party Dependencies

The easiest path to build Axom’s dependencies is to use Spack. This has been encapsulated using Uberenv. Uberenv helps by doing the following:

  • Pulls a blessed version of Spack locally

  • If you are on a known operating system, such as the clusters on Livermore Computing (LC), or our provided docker images, we have defined Spack configuration files to keep Spack from building the world

  • Installs our Spack packages into the local Spack

  • Simplifies whole dependency build into one command

Uberenv will create a directory containing a Spack instance with the required Axom dependencies installed.

It also generates a host-config file (<config_dependent_name>.cmake) at the root of Axom repository. This host-config defines all the required information for building Axom.

$ python3 scripts/uberenv/uberenv.py

Note

On LC machines, it is good practice to do the build step in parallel on a compute node. Here is an example command: salloc -ppdebug -N1-1 python3 scripts/uberenv/uberenv.py

Unless otherwise specified, Spack will default to a compiler. This is generally not a good idea when developing large codes. To specify which compiler to use, add the compiler specification to the --spec Uberenv command line option. Supported compiler specs can be found in the Spack compiler files in our repository: scripts/spack/configs/<platform>/spack.yaml.

We currently regularly test the following Spack configuration files:

  • Linux Ubuntu 20.04 (via Windows WSL 2)

  • TOSS 4 (On Ruby at LC)

  • BlueOS (On Lassen at LC)

To install Axom on a new platform, it is a good idea to start with a known Spack configuration directory (located in the Axom repo at scripts/spack/configs/<platform>). The spack.yaml file describes the compilers, associated flags required for the platform, and the the low-level libraries on the system to prevent Spack from building the world. Documentation on these configuration files is located in the Spack docs.

Some helpful uberenv options include :

  • --spec=+cuda (build Axom with CUDA support)

  • --spec=+devtools (also build the devtools with one command)

  • --spec=%clang@10.0.0 (build with a specific compiler as defined in the compiler.yaml file)

  • --spack-env-file=<Path to Spack Environment file> (use specific Spack configuration file)

  • --prefix=<Path> (required, build and install the dependencies in a particular location)

There is more thorough uberenv documentation here.

The modifiers to the Spack specification spec can be chained together, e.g. --spec=%clang@10.0.0+debug+devtools.

If you already have a Spack instance from another project that you would like to reuse, you can do so by changing the uberenv command as follows:

$ python3 scripts/uberenv/uberenv.py --upstream=</path/to/my/spack>/opt/spack

Preparing Windows WSL/Ubuntu for Axom installation

For faster installation of the Axom dependencies via Spack on Windows WSL/Ubuntu systems, install CMake, MPICH, openblas, OpenGL, and the various developer tools using the following commands:

Ubuntu 20.04

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install cmake libopenblas-dev libopenblas-base mpich cppcheck doxygen libreadline-dev python3-sphinx python3-pip clang-format-10 m4
$ sudo ln -s /usr/lib/x86_64-linux-gnu/* /usr/lib

Note that the last line is required since Spack expects the system libraries to exist in a directory named lib. During the third party library build phase, the appropriate Spack config directory must be specified using either:

Ubuntu 20.04

python3 scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/linux_ubuntu_20/spack.yaml --prefix=path/to/install/libraries

Using Axom in Your Project

The install includes examples that demonstrate how to use Axom in CMake-based, BLT-based and Makefile-based build systems.

CMake-based build system example

endif()

project(using_with_cmake)

message(STATUS "CMake Version: ${CMAKE_VERSION}")

#------------------------------------------------------------------------------
# Check for AXOM_DIR and use CMake's find_package to import axom's targets
#------------------------------------------------------------------------------
if(NOT DEFINED AXOM_DIR OR NOT EXISTS ${AXOM_DIR}/lib/cmake/axom-config.cmake)
    message(FATAL_ERROR "Missing required 'AXOM_DIR' variable pointing to an installed axom")
endif()

if (ENABLE_CUDA)
    enable_language(CUDA)
endif()

if (ENABLE_HIP)
    if (NOT ROCM_PATH)
        find_path(ROCM_PATH
            hip
            ENV{ROCM_DIR}
            ENV{ROCM_PATH}
            ENV{HIP_PATH}

See: examples/axom/using-with-cmake

BLT-based build system example

#------------------------------------------------------------------------------
# Set up BLT with validity checks
#------------------------------------------------------------------------------

# Check that path to BLT is provided and valid
if(NOT DEFINED BLT_SOURCE_DIR OR NOT EXISTS ${BLT_SOURCE_DIR}/SetupBLT.cmake)
    message(FATAL_ERROR "Missing required 'BLT_SOURCE_DIR' variable pointing to a valid blt")
endif()

include(${BLT_SOURCE_DIR}/SetupBLT.cmake)


#------------------------------------------------------------------------------
# Check for AXOM_DIR and use CMake's find_package to import axom's targets
#------------------------------------------------------------------------------
if(NOT DEFINED AXOM_DIR OR NOT EXISTS ${AXOM_DIR}/lib/cmake/axom-config.cmake)
    message(FATAL_ERROR "Missing required 'AXOM_DIR' variable pointing to an installed axom")
endif()

include(CMakeFindDependencyMacro)

find_dependency(axom REQUIRED
                NO_DEFAULT_PATH 
                PATHS ${AXOM_DIR}/lib/cmake)

#------------------------------------------------------------------------------
# Set up example target that depends on axom
#------------------------------------------------------------------------------

blt_add_executable(NAME       example 
                   SOURCES    example.cpp

See: examples/axom/using-with-blt

Makefile-based build system example

AXOM_DIR ?= ../../..

CXX=@CMAKE_CXX_COMPILER@
CXX_FLAGS=@CMAKE_CXX_FLAGS@ -std=c++@CMAKE_CXX_STANDARD@
INC_FLAGS=-I$(AXOM_DIR)/include/
LINK_FLAGS=-L$(AXOM_DIR)/lib/ @AXOM_ORDERED_LIBS@

main:
	$(CXX) $(INC_FLAGS) example.cpp $(LINK_FLAGS) -o example

clean:
	rm -f example

See: examples/axom/using-with-make