The section ‘Dependencies’ lists the general requirements for the compilation. The section ‘System-dependent dependency installation’ gives some instructions on how to install these dependencies on Windows, some Linux-distributions and MacOS. Conda based dependency installation is described in the section ‘Conda dependent installation’.
To clone and compile mHM you need at least the following:
- Fortran compiler: We support gfortran, nagfor and ifort
- Build system: We support make and ninja
- cmake: Software for build automation
- NetCDF-Fortran: NetCDF I/O for Fortran
- git: version control system
- (optional) fypp: Fortran pre-processor written in Python
System-dependent dependency installation
After you installed all dependencies on your system you can proceed with cloning and compiling.
Unix (Linux / MacOS)
- MacOS with homebrew available:
brew install git gcc netcdf cmake
- Ubuntu, Mint and other apt-get based systems with matching repositories:
sudo apt-get install git gfortran netcdf-bin libnetcdf-dev libnetcdff-dev cmake
sudo pacman -S git gcc-libs netcdf-fortran cmake
- yum based systems (CentOS, OpenSuse):
sudo yum -y install git gcc-gfortran netcdf-fortran cmake
Easiest way to do so is:
- install the Windows Terminal
- open the Windows Terminal and type:
wsl --install -d ubuntu
- Open Ubuntu from the new entry in the start menu
Then you can follow the install instructions for Ubuntu from above.
If you rather want to use Cygwin (tool providing Linux functionality on Windows), step-by-step guidelines on how to install all Cygwin libraries can be viewed in this youtube video created by Mehmet Cüneyd Demirel (Istanbul Technical University).
If you are on a module system, load the modules gcc or intel depending on your favorite compiler. Then, load the modules netcdf-fortran and cmake.
These modules will have system specific names, environments, etc.
You may use
module spider to find the right packages and the
right dependencies, potentially use corresponding wiki pages.
On EVE (the cluster at the UFZ)
A set of load-scripts is provided in
hpc-module-loads (see the repository for more details), to load all needed modules for specific compilers:
- Example: GNU 7.3 compiler (
or (MPI support)
Conda dependent installation
The simplest way to compile this project on your local computer is to use a conda environment (on Linux (including WSL) or MacOS) provided by Miniforge to install NetCDF, a Fortran compiler, make, cmake.
On Windows we recommend to use Windows Subsystem for Linux (WSL) to be able to use Linux (see above) and set up conda there.
You can get the latest version of Miniforge with (for Linux/MacOS/WSL):
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh bash Miniforge3-$(uname)-$(uname -m).sh
To create a (local) conda environment with all dependencies type the following:
conda create -y --prefix ./fortran_env conda activate ./fortran_env conda install -y git cmake make fortran-compiler netcdf-fortran
Then you can proceed with cloning and compiling.
Cloning the repository
First you need to clone the repository (if you already have
git, otherwise see below):
git clone https://git.ufz.de/mhm/mhm.git
This will give you a new folder
mhm/ containing the whole repository. You can go into it by:
If you then want to compile a specific version (different from the latest development version), you can check that out with e.g.:
git checkout v5.11.2
Afterwards you can continue with the compilation.
It could be necessary to set your desired fortran compiler with an environment variable, e.g.:
We prepared a set of scripts to automatize the build and compilation process to generate an executable in the root directory with the following naming scheme:
- Release version
- Debug version
- Release version with MPI support
- Debug version with MPI support
- Release version with OpenMP support
- Debug version with OpenMP support
Then you can find an executable
mhm[_mpi|_openmp][_debug]) in the current folder.
You can execute it with:
To install mhm after compilation, i.e. make it available as a command
mhm, you can do the following (assuming you used the release compile script, otherwise replace
release with the respective build folder):
cmake --install release
If you need to provide a prefix, where to install it, you can just pass one. For example, if you used a conda environment for compilation, you can also install mhm there with:
cmake --install release --prefix $CONDA_PREFIX
Compilation without Internet
If you don’t want to download it indirectly, know you wont have internet during your development or you want to work on routines provided by FORCES, you can place a copy of the FORCES repository in the root of your cloned mHM repository by e.g.:
git clone https://git.ufz.de/chs/forces.git
The new folder
forces/ will be automatically recognized during compilation as described above and nothing will be downloaded.
If you just want a specific version (see
src/CMakeLists.txt for the currently used one), do this:
git clone --branch v0.3.2 --depth 1 https://git.ufz.de/chs/forces.git
If you have already cloned FORCES somewhere else, you can also provide a path to this repository. You can do this with all mentioned compile scripts, e.g.:
source CI-scripts/compile -DCPM_forces_SOURCE=<path/to/your/forces/repo>
For example, if you have cloned FORCES next to mhm, this could look like this:
source CI-scripts/compile -DCPM_forces_SOURCE=../forces
Additional CMake infos
The presented compile scripts all just execute two cmake commands with a specific set of configuration flags.
The basic cmake workflow, to configure and compile in a
build/ folder, is:
cmake -B build cmake --build build
You can control all
cmake options by passing them as directives staring with
-D to the cmake configuration.
For example for debug configuration, you can do the following:
cmake -B build -DCMAKE_BUILD_TYPE=Debug
To configure the build interactively, you can also use ccmake (command line tool) or the CMake GUI (graphical user interface).
Check their respective documentation for further information.
ccmake you can do the following:
cmake -B build ccmake build
Then set your desired options and re-configure your build (by pressing
Afterwards build you project as always by executing:
cmake --build build --parallel