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>/compilers.yaml
.
We currently regularly test the following Spack configuration files:
- Linux Ubuntu 20.04 (via Windows WSL 2)
- TOSS 3 (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 compilers.yaml
file
describes the compilers and associated flags required for the platform and the packages.yaml
file
describes 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 thecompiler.yaml
file)--spack-config-dir=<Path to spack configuration directory>
(use specific Spack configuration files)--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-config-dir=scripts/spack/configs/linux_ubuntu_20 --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¶
#------------------------------------------------------------------------------
# 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}
${HIP_PATH}/..
${HIP_ROOT_DIR}/../
${ROCM_ROOT_DIR}
/opt/rocm)
endif()
set(CMAKE_PREFIX_PATH "${CMAKE_PREFIX_PATH};${ROCM_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()
find_package(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
DEPENDS_ON axom fmt)
See: examples/axom/using-with-blt
Makefile-based build system example¶
INC_FLAGS=-I$(AXOM_DIR)/include/
LINK_FLAGS=-L$(AXOM_DIR)/lib/ -laxom
main:
$(CXX) $(INC_FLAGS) example.cpp $(LINK_FLAGS) -o example
See: examples/axom/using-with-make