Compilation
Warning
Conan is no longer used to build CHM. Spack is now used
CHM uses spack to manage and build all dependencies. Because of the various requirements on build configuration, versions, and inter-dependencies, using system libraries it not supported.
Build requirements
Linux (x86_64) and Macos (arm64) are the only supported environments.
The following have been tested
- Build env requirements:
cmake >=3.21 (via apt-get/brew)
C++14 compiler (gcc 9.3.0+) (via apt-get/brew)
Fortran 90+ compiler (gfortran) (via apt-get/brew)
Warning
Unfortunately the Intel compiler doesn’t currently work with applications that also link against GSL. This is being investigated. For now, please do no build CHM with Intel Compilers.
Build dependencies
OpenMP
On Macos, the openmp
library should be installed via homebrew:
brew install libomp
OpenMPI
Note
Building CHM without MPI support is now deprecated. MPI is now required.
- Other MPI versions probably work, but only OpenMPI has been tested.
Ensure MPI is installed on linux:
libopenmpi-dev
andopenmpi-bin
Install spack
Install spack.
Clone the CHM spac-repo
git clone https://github.com/Chrismarsh/spack-repo.git /some/path/here/
then create repos.yml
in ~/.spack
and add the path to the above cloned spack-repo
.
It will look like this
$ cat ~/.spack/repos.yaml
repos:
- /some/path/here/spack-repo
- $spack/var/spack/repos/builtin
Setup CHM source folders
An out of source build should be used. That is, build in a separate folder removed from the CHM source. This makes it easier to clean up and start from scratch. An example is given below:
cd ~/
git clone --recurse-submodules https://github.com/Chrismarsh/CHM
mkdir ~/build-CHM
Build dependencies
This step will build and install the dependencies via spack.
spack env create chm path/to/CHM/spack.yml
spack concretize
spack install -j 8 # number of parallel builds, adjust accordingly
Build CHM
Note
The follow instructions assume that they are invoked from within ~/build-CHM
(or your equivalent).
You can set the install prefix to be anywhere, such as shown in the example below
cmake ~/CHM -DCMAKE_INSTALL_PREFIX=/opt/chm-install
Both ninja
and make
(this is the default) are supported. To use ninja
, add
cmake ~/CHM -DCMAKE_INSTALL_PREFIX=/opt/chm-install -G "Ninja"
Ninja speeds up compilation of CHM by ~6%.
The default build option creates an optimizted “release” build. To build
a debug build, use -DCMAKE_BUILD_TYPE=Debug
.
Intel compiler
If the Intel compiler is used, add the following cmake flags:
-DCMAKE_CXX_COMPILER=icpc -DCMAKE_C_COMPILER=icc -DCMAKE_FORTRAN_COMPILER=ifort
High performance allocators
By default jemalloc is used.
-DUSE_TCMALLOC=FALSE -DUSE_JECMALLOC=TRUE
.
Building
Using make
make -jN CHM
where N is the number of parallel jobs (e.g., total core count).
Using Ninja
ninja -C .
Run tests
Tests can be enabled with -DBUILD_TESTS=TRUE
and run with
make check
/ ninja check
Install
make install
/ninja install
Build docs
To build the documentation requires Doxygen and Sphinx+Breathe+Exhale.
pip install sphinx
pip install sphinx-rtd-theme
pip install breathe
pip install exhale@git+https://github.com/svenevs/exhale.git@refs/pull/205/merge
The exhale version requirement: see issue#200.
The documentation can be built with:
cd CHM/docs
READTHEDOCS="True" make html
The env var is required to ensure the correct directories are searched for in-source builds.
Troubleshooting
The high performance allocators may need to be disabled and can be done via
-DUSE_TCMALLOC=FALSE -DUSE_JEMALLOC=FALSE
Building on Compute Canada (WestGrid)
To build on Compute Canada stack machines, such as Graham, all dependencies must be built from source to ensure the correct optimizations are used. This should be done with the Compute Canada easybuild system.
Only the gcc/9.3.0
environment is supported. This can be enabled with
module load gcc/9.3.0
Build all dependencies that are not available from compute canada stack
git clone https://github.com/Chrismarsh/easy_build.git
cd easy_build
chmod +x install-all.sh
./install-all.sh
Ensure the environment is correctly setup
module load armadillo/10.4.1
module load cgal/5.2.1
module load hdf5/1.10.6
module load meteoio
module load func
module load netcdf/4.7.4
module load gdal/3.2.3
module load boost-mpi/1.72.0
module load openblas/0.3.9
module load gsl/2.6
module load eigen/3.3.7
module load sparsehash
module load tbb/2020.2
module load trilinos/13.3.0
module load netcdf-c++4/4.3.1
module load vtk/9.0.1
module load proj/9.0.1
module load jemalloc/5.3.0
module load cmake
Optionally you can save this with module save chm
.
Then build CHM
git clone https://github.com/Chrismarsh/CHM # get CHM source code
mkdir ~/chm-build && cd ~/chm-build # make build directory
cmake ../CHM -DENABLE_SAFE_CHECKS=ON -DBoost_NO_BOOST_CMAKE=ON -DUSE_TCMALLOC=FALSE -DUSE_JEMALLOC=TRUE -DCMAKE_BUILD_TYPE=Release
make -j10