Appendecies
Linux Ubuntu Notes
When building on any system a few basic utilities are assumed to be installed. It’s impossible to cover all the possible build environments, but a common case is a Linux Ubuntu install. In our experience we need at least the following packages beyond the base system default, which can be easily accomplished using apt install
):
sudo apt install git autotools-dev autoconf pkg-config uuid gettext libgdbm-dev libexpat-dev cmake g++ gfortran zlib1g-dev libssl-dev libbz2-dev libreadline-dev build-essential libncurses5-dev libgdbm-dev libnss3-dev libffi-dev wget tk tk-dev libsqlite3-dev texlive-latex-recommended texlive-latex-extra dvipng
Most of these requirements are for building a full-featured Python installation. If you also want to build the MPI parallel enabled version of Spheral you need an MPI implementation such as OpenMPI or MPICH – OpenMPI for instance can be installed by adding the Ubuntu package mpich
or openmpi-bin
to the above list.
Checking/updating CMake Version
Unfortunately most recent versions of Ubuntu Linux (and derivatives such as Mint) come with an older version of CMake by default (typically something like CMake v3.10). This is too out of date for a Spheral build, and therefore needs to be updated before configuring and building Spheral. First, just to make sure you have this issue you should check the version of cmake that comes with your distribution:
cmake --version
If the result is something less than version 3.18, it’s worth updating before starting to configure Spheral. How to accomplish this varies by platform, but for the common case of Ubuntu (and similar apt
based distributions) something like the following should suffice.
First, remove any existing cmake installation using apt:
sudo apt remove --purge cmake
Follow the directions on the Kitware site at this link to add their repository for installing packages.
Install a current version of cmake with:
sudo apt install cmake
Check the final version again to make sure you have what you expect:
cmake --version
WSL2 Notes
The Windows Subsystem for Linux (WSL) is a useful method of development on Windows 10 based systems. If going this route we recommend having at least WSL2 for best results – the original version of WSL (WSL1) also functioned, but is significantly slower for jobs such as compilation.
For the most part using an Ubuntu based WSL environment works just using the Ubuntu notes above. However, one aspect of WSL2 needs to be adjusted. The build process requires a fair amount of memory (in particular for a few of the Python binding modules), so we recommend having at least 32GB of swap space available. On WSL2 this is accomplished by creating a .wslconfig
file in your Windows home directory containing at least the following lines:
[wsl2]
swap=32GB
Custom Spack Installation
Building Spheral TPLs with your own Spack installation will require deeper knowledge of how Spack works. All of the steps to set up Spheral with your own spack installation are not detailed here, however you will want to at least:
Point your spack instances repo at the
scripts/spack/packages/
dir. This contains all of our changes to spack packages that have not yet made it to upstream Spack.You will want to model your
compiler.yaml
andpackages.yaml
files off of those found inscripts/spack/configs/
(Spack Configuration Files).
Further notes on setting up Spack and how it is used with the Spheral dev-tools scripts can be found in Development Documentation: Spheral Spack / Uberenv.
CMake Configurations
This section outlines the common CMake options Spheral provides for configuring how to build Spheral.
C++ Only Build
If you do not need to build the Python interface you can build the compiled C++ libraries alone with -DENABLE_CXXONLY=On
. This will skip the Python wrapping stage of the build.
By default Spheral builds the libraries as shared objects. If instead you would like to build the C++ libraries as static libs use -DENABLE_STATIC_CXXONLY=On
.
Third party libraries and Spheral
For just the C++ compiled Spheral a number of TPLs are required:
Zlib
Boost
Python
Eigen
Polytope
HDF5
Silo
Qhull
M-ANEOS
Opensubdiv
Polyclipper
Conduit
Axom
There are also a number of libraries / python packages that are required for compiling the python bindings and executing Spheral at runtime:
Python
pip
setuptools
pybind11
pyb11generator
sphinx
sphinx_rtd_theme
Scipy
Sobol
Cython
Twine
h5py
decorator
Matplotlib
mpi4py
Numpy-stl
Custom TPL Installation
You can build the Spheral TPLs manually or even with your own spack installation to bypass the use of tpl-manager.py
. Custom built TPL installations can be passed to Spheral’s CMake with -D<tpl-name>_DIR=<tpl-install-prefix>
.
cmake -DBOOST_DIR=$HOME/my_boost_build_dir ...
OpenMP/MPI
OpenMP and MPI support is handled through BLT. Use the option flags -DENABLE_OPENMP
and -DENABLE_MPI
respectively, choosing ON
or OFF
as appropriate.
CMake variables
In this section we list the CMake variables that can be tweaked for a Spheral build. Where appropriate the options are listed, with the default value in italics.
CMAKE_BUILD_TYPE
(Debug, Release, RelWithDebInfo, MinSizeRel)Choose the type of build – for more information see the CMake documentation.
CMAKE_INSTALL_PREFIX
The top-level path for installing Spheral include files, libraries, and any Python modules or documentation.
ENABLE_CXXONLY
(On, Off)Do not build python wrappers for Spheral.
ENABLE_STATIC_CXXONLY
(On, Off)Do not build python wrappers for Spheral. Build and export static library files for Spheral.
ENABLE_SHARED
(On, Off)Build Spheral C++ libraries as shared libraries.
ENABLE_DEV_BUILD
(On, Off)Builds separate internal C++ libraries for faster code development.
<TPL-Name-Here>_DIR
Directory of previously built TPL.
ENABLE_STATIC_TPL
(On, Off)Link static libraries instead of shared for HDF5 and Conduit.
ENABLE_OPENMP
(On, Off)Support for OpenMP.
ENABLE_MPI
(On, Off)Support for MPI.
ENABLE_1D
(On, Off)Build Spheral with 1D support.
ENABLE_2D
(On, Off)Build Spheral with 2D support.
ENABLE_3D
(On, Off)Build Spheral with 3D support.
ENABLE_ANEOS
(On, Off)Install the ANEOS (Analytics Equation of State) package along with the Spheral interface to it. This is a legacy equation of state frequently used for geophysical materials. See descriptions in the iSALE documentation.
ENABLE_HELMHOLTZ
(On, Off)Compile the included Helmholtz equation of state, typically used in astrophysical calculations. See a discussion here.
ENABLE_OPENSUBDIV
(On, Off)Install the Opensubdiv library along with the Spheral interface to it. Opensubdiv is a Pixar provided library, which Spheral uses to implement refinement of polyhedra for some specialized problem generation capabilities.
ENABLE_TIMER
(On, Off)Enable timer information from Spheral.
DBC_MODE
(None, All, Pre)Set the compile time design by contract (DBC) mode for Spheral. Design by contract statements are very useful developer tools, whereby the developer can insert tests in the code as they write it. These statements are both useful for tracking down bugs with fine-grained testing throughout the code, as well as useful documentation in the code about what sort of conditions are expected to hold.
None
Design by contract not enforced
All
All design by contract (
REQUIRE
,ENSURE
,CHECK
) statements activePre
Only prerequisites (
REQUIRE
) statements activeNote the default depends on the
CMAKE_BUILD_TYPE
:CMAKE_BUILD_TYPE=Debug
defaultDBC_MODE
isAll
In all other cases the default is
None
.It is worth noting
DBC_MODE=All
is quite expensive at run time (of order 4x more), so this is not intended to be active for a release/production compilation of Spheral.ENABLE_WARNINGS
(On, Off)Enable compiler warnings.
ENABLE_BOUNDCHECKING
(On, Off)If building with the Gnu compilers enable STL bound checking by passing -D_GLIBCXX_DEBUG=1 to the compiler. Note, this is a very expensive option at runtime!
ENABLE_NAN_EXCEPTIONS
(On, Off)Raise exceptions in the C++ code when floating-point exceptions occur. Gnu compilers only.
ENABLE_DOCS
(On, Off)Choose whether or not to build this documentation.
SPHINX_EXECUTABLE
Specify where the Sphinx executable is that should be used to build documentation. If not given, assumes the Spheral built Sphinx will be used.
SPHINX_THEME
(sphinx_rtd_theme)Give the Sphinx theme to use when generating documentation. Default based on read the docs theme.
SPHINX_THEME_DIR
Where to look for Sphinx themes.