Building and Installing Amanzi Using CMake

Building Amanzi

Amanzi depends on several external software packages or third party libraries (TPL) to build. Before building Amanzi a user must either build each of these TPLs, provide an installation path for each TPL or define the include directories and libraries needed for each TPL. We recommend that users build Amanzi and all the TPLs using the boostrap.sh shell script found in the config directory. The script can be run from the source directory. On most UNIX flavored systems, this script will build and install Amanzi and all the required TPLs with little information from the user. The script has prerequisites for compilers, LAPACK/BLAS and MPI. Please read Amanzi Third Party Library (TPL) Build System section for more information and Quickstart Using Bootstrap for installing using the bootstrap.sh.

We recommended that users install the TPLs in separate directory, since a full TPL build should be an infrequent task. This is the default behavior of the bootstrap.sh script. See bootstrap.sh --help for more information on how to control the installation paths. The TPL build will generate a CMake configuration file that defines all the required TPL directories and CMake variables to build Amanzi. Once the user has installed all the required TPLs, the process to build Amanzi from the command line is:

  1. Generate build files (Makefile, XCode project files, etc.) using CMake

    cmake -C <TPL install prefix>/share/cmake/amanzi-tpl-config.cmake \
      -D CMAKE_C_COMPILER=/full/path/mpicc \
      -D CMAKE_CXX_COMPILER=/full/path/mpicxx \
      -D CMAKE_Fortran_COMPILER=/full/path/mpif90 \
      [Addtional CMake variable definitions]
      <Amanzi source directory>

  2. Use the build files to build Amanzi, i.e. make,

    make [-j n]

or the user can run bootstrap.sh defining a previously built TPL configuration with

bootstrap.sh --tpl-config-file=<TPL install prefix>/share/cmake/amanzi-tpl-config.cmake

Amanzi TPL Configuration Settings

We recommend that users build all the TPLs using the Amanzi SuperBuild project. This will create a CMake file that will initialize the cache settings for all the TPLs. Instructions in this section are designed for advanced users.

The Amanzi CMake files search for each TPL through the CMake find_package function. Each TPL has a search path defined by the variable <TPL_Name>_DIR where TPL_Name is the name of the package. The Amanzi CMake files search for the appropriate include directories and libraries for this package. The search also includes searching for dependent packages. For example, searching for ASCEM-IO also triggers a search for HDF5 since ASCEM-IO depends on HDF5. The exceptions to this variable naming convention are Boost and HDF5. For these packages, Amanzi uses the CMake FindBoost module found in the CMake installation and the FindHDF5 module found in the tools/cmake/Modules directory.

Users can bypass the package search by defining the <TPL_Name>_INCLUDE_DIRS and <TPL_Name>_LIBRARIES variables. These variables should contain the full path name of the include directories and libraries for that TPL and ANY dependent package the TPL requires to build and link against. For example, if you want to bypass the ExodusII search logic, then define ExodusII_INCLUDE_DIRS and ExodusII_LIBRARIES and these variables must also contain the NetCDF include directories and libraries. These variables are CMake list types. Each directory or filename should be separated with a semicolon.

Amanzi Build Configuration Settings

The naming convention for Amanzi build options is ENABLE_<Feature_Name> and is a boolean type (ON,OFF). The current build options with the default values are documented here.

ENABLE_Structured:

  • Default: OFF

  • Description: Build structured mesh capability.

  • Dependencies: CCSE

ENABLE_Unstructured:

  • Default: OFF

  • Description: Build unstructured mesh capability.

  • Dependencies: At leat one of the mesh frame works, STK, MSTK or MOAB.

ENABLE_DBC:

  • Default: ON

  • Description: Enable design by contract build.

  • Dependencies:

ENABLE_Config_Report:

  • Default: ON

  • Description: Print out configuration report to the terminal.

  • Dependencies:

ENABLE_MESH_MSTK:

  • Default: OFF

  • Description: Build the MSTK mesh frame work.

  • Dependencies: MSTK

ENABLE_MESH_MOAB:

  • Default: OFF

  • Description: Build the MOAB mesh frame work.

  • Dependencies: MOAB, requires a specific version. See Software Requires for more information.

ENABLE_CCSE_TOOLS:

  • Default: OFF

  • Description: Build structured AMR post processing tools

  • Dependencies: python, f2py, gfortran compatible with mpif90

ENABLE_UnitTest:

  • Default: ON

  • Description: Build the unit test test suite.

  • Dependencies: UnitTest++

ENABLE_OpenMP:

  • Default: OFF

  • Description: Build Amanzi executables with OpenMP support.

  • Dependencies: OpenMP

Installing Amanzi

CMake will generate an install target in build files. For Makefiles, make install will install Amanzi under the directory defined by CMAKE_INSTALL_PREFIX. The default install location is /usr/local.

Once installed, other CMake software projects can build and link against Amanzi as a library. See https://software.lanl.gov/ascem/trac/wiki/Amanzi/BuildSystemIntegration for a simple example.