Skip to content

Latest commit

 

History

History
332 lines (229 loc) · 11.7 KB

INSTALL.md

File metadata and controls

332 lines (229 loc) · 11.7 KB

Install Instruction

The section 'Dependencies' lists the general requirements for the installation. The section 'System-dependent installation instructions' gives some instructions on how to install these dependencies on Windows, some Linux-distributions and soon MacOS.

The section 'Specific setups' can be skipped in most cases. If you are using a module system or MacOS there are some additional hints for the installation process. It might be helpful to first read the section 'Installation'. The section 'Specific setups' then helps to adjust the commands for a build on the specific system.

The section 'Installation' then is a step-by-step guide to install mHM in the command line.

Dependencies

For Windows, some Linux distributions and soon also MacOS specific installation instructions for the following list can be found below.

  • a fortran compiler
  • make (a tool to compile a program)
  • cmake (version >= 3.5) (a tool to create a system-dependent makefile)
  • fitting netcdf-fortran libraries (libraries for the use of the data format netcdf on which mhm depends)
  • (optional, but makes things much easier) git

Git is a version-control system. If you want to contribute to a project, it is highly recommended to use Git. You can use Git to download (clone) the project to your local pc and have a look at the history or synchronize it without copying the whole repository again. You can also download the project folder without Git, but this would not allow you to pull updates from and push changes to our repository.

System-dependent installation instructions

Windows:

Cygwin is an environment with a terminal that allows to compile and run programs of Unix-like systems. You can find further instructions to install cygwin on the webpage, as well as instructions on how to install further dependencies after the installation.

After the installation of cygwin and its dependencies mHM will be installed using cygwin. All commands and the execution of mHM only run in that environment.

Install cygwin by executing the cygwin setup and choose the following dependencies:

  • gcc-fortran (the fortran compiler)
  • make
  • cmake (version >= 3.5)
  • libnetcdf-fortran-devel
  • Git (optional, Git is also available outside of cygwin, see the Git website)

While installing cygwin you will have to choose a mirror. A mirror is a server on the internet where the files for the installation come from. Choose any server located near your city and when in doubt, choose the first one in the list. In the next step you can find all available packages provided by cygwin, set the view to "full". In the search panel you can filter the packages by the dependencies listed above (e.g. make). When you choose a version, the newest one is usually a good choice if not marked as experimental.

Note for UFZ members: Install cygwin locally (on your own computer), do not choose a location on the network for the installation.

Some cygwin versions create a new home directory for you. You may check e.g. here:

C:\cygwin64\home\$username

As from December 2019, step-by-step guidelines, how to install all netCDF dependencies can be viewed in this youtube video created by Mehmet Cüneyd Demirel (Istanbul Technical University).

To avoid memory issues, allocate stack memory during cmake

cmake -DCMAKE_Fortran_FLAGS="-Wl,--stack,12485760" ..

Memory dump is a common issue for cygwin users when compiling with OpenMP. For memory allocation please use this line below.

....cmake -DCMAKE_Fortran_FLAGS="${CMAKE_Fortran_FLAGS} -Wl,--stack,12485760" -DCMAKE_WITH_OpenMP:STRING=ON -DCMAKE_BUILD_TYPE=Release ..

Ubuntu, Mint and other apt-get based systems with matching repositories

sudo apt-get install git # (optional)
sudo apt-get install gfortran netcdf-bin libnetcdf-dev libnetcdff-dev cmake

Archlinux

sudo pacman -S git # (optional)
sudo pacman -S gcc-libs netcdf-fortran cmake

Module systems

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 moduleLoadScripts, to load all need modules for specifc compilers:

  • GNU 7.3 compiler (foss/2018b Toolchain): 
    source moduleLoadScripts/eve.gcc73
    or (MPI support) 
    source moduleLoadScripts/eve.gcc73MPI
  • GNU 8.3 compiler (foss/2019b Toolchain): 
    source moduleLoadScripts/eve.gcc83
    or (MPI support) 
    source moduleLoadScripts/eve.gcc83MPI
  • Intel 18 compiler (iomkl/2018b Toolchain): 
    source moduleLoadScripts/eve.intel18
    or (MPI support) 
    source moduleLoadScripts/eve.intel18MPI
  • Intel 20 compiler (iomkl/2020a Toolchain): 
    source moduleLoadScripts/eve.intel20
    or (MPI support) 
    source moduleLoadScripts/eve.intel20MPI
  • NAG 6.2 compiler: 
    source moduleLoadScripts/eve.nag62

Then you can compile mHM with cmake. 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 mhm: 
    source CI-scripts/compile
  • Debug version mhm_debug: 
    source CI-scripts/compile_debug
  • Release version with MPI support mhm_mpi: 
    source CI-scripts/compile_MPI
  • Debug version with MPI support mhm_mpi_debug: 
    source CI-scripts/compile_MPI_debug
  • Release version with OpenMP support mhm_openmp: 
    source CI-scripts/compile_OpenMP
  • Debug version with OpenMP support mhm_openmp_debug: 
    source CI-scripts/compile_OpenMP_debug

MacOS

(to be added)

Specific setups

The following hints can replace the step cmake .. in the installation instruction.

You can skip this part and continue with "Installation", if you do not have a module system setup (like on clusters) or if you have not installed all packages with a package manager, such as cygwin or apt-get.

Module systems

If you are okay with loading the needed modules as described in the section 'Module systems' above before executing the program you can skip this step and continue with 'Installation'.

The executable can be built in such a way that it does not require any modules to be loaded. The module system, though, adds system paths in the backround the user should not care about too much, so the setup is a workaround. (This would be the case with any other building tool aswell.) It should be stable, anyway.

In case you want to have a module-independent build, instead of just executing cmake .., either run

cmake -DCMAKE_BUILD_MODULE_SYSTEM_INDEPENDENT:STRING=ON ..

or

cmake -C ../CMakeCacheFiles/eve ..

or change the variable CMAKE_BUILD_MODULE_SYSTEM_INDEPENDENT with ccmake to ON after running cmake ...

Non-standard locations for the netcdf-library (e.g. standard setup Macs in CHS):

Find the location of the nf-config file, for example by using:

find / -iname "*nf-config*" 2>/dev/null

This searches the root directory / for a file with a name containing the string "nf-config" (case-insensitive). It writes error messages like "permission denied" into the void.

Then, instead of running cmake .. if not using the standard compiler, set the fortran compiler variable to the desired compiler, e.g.

export FC=gfortran

then either run

cmake -DCMAKE_NETCDF_DIR:STRING=/path/to/nf-config/of/used/compiler

or copy the file specificSetup to some other place:

cp ../CMakeCacheFiles/specificSetup .

However, in case you want to keep it, you should choose a place outside the build repository. Edit the file as follows: add the path to your nf-config file, and after editing, run:

cmake -C specificSetup ..

or change the variable CMAKE_NETCDF_DIR to the path to the nf-config file with ccmake after running cmake ...

Installation

  1. Change to a directory where you want to store the source code.

  2. Clone the corresponding mHM repository into a folder, either using Git (if installed):

     git clone --recurse-submodules https://git.ufz.de/mhm/mhm.git mhm/

    for cloning it into a folder mhm, or download and unpack it using the download link on https://git.ufz.de/mhm/mhm (the cloud symbol with the arrow on it).

  3. Create and change to a build directory where you want to store the build, e.g. inside the Git source directory

     cd mhm
 mkdir build

    Change into the build directory:

     cd build

  4. Generate a system-dependent makefile

    Execute cmake with the path to the Git source directory as parameter. (If you followed the instructions above, the path is .. )

    cmake ..

    If everything worked well a Makefile was created with the corresponding paths.

    Note: have a look at "Specific setups" above in case you are using module systems, or when the netcdf libraries are not located where the package manager usually installs libraries, or when they are not saved in environment variables (i.e., classical MacOS setups at CHS).

  5. Make the build:

    Execute make:

     make

    If this also worked fine, an executable was created, which has to be moved or copied to the Git source directory.

  6. Execute the file:

     cd ..
 cp build/mhm .

    On Windows the executable is called mhm.exe instead of mhm. In that case instead of cp build/mhm . execute

     cp build/mhm.exe .

    Now you might execute mHM:

     ./mhm

Note concerning the development of the cmake setup: one could automatically link the executable with the cmake code inside the Git source directory which is not done for two reasons:

  • The executable depends on your local system, so it should never be commited and pushed to other users. Nothing should be built inside the source directory automatically.
  • The directory where mHM is executed usually is not the source directory but the directory where you want to run your tests. In case of the test setup it is the same, usually it is not.

Building Realease or Debug versions

If you want to set up specific versions of the build, you can create different folders for that. In case a release and a debug version need to be set up, it makes sense to create two folders named debug and release.

mkdir release

mkdir debug

inside the release folder one would execute

cmake -DCMAKE_BUILD_TYPE=Release ..

and inside the debug folder

cmake -DCMAKE_BUILD_TYPE=Debug ..

Executing

make

in the corresponding folder would then always result in a release build or respectively in a debug build.

Troubleshooting

cmake is far from being my main task, so it will probably take a while until I can track a problem. Nonetheless, I would be happy having bug reports. Feel free to write an email to mailto:[email protected] if there are any bugs, remarks or questions.

MacOS, homebrew

On brew/homebrew setup MacOS systems a working nf-config is not yet available at this time. Execute:

nf-config --all

and if it says something like "is not implemented yet" the issue is not solved yet. But it is on my tracklist.

cygwin

If libraries are not found, the problem can be:

  • you accidentally tried to use commands within the cmd shell and not within the cygwin shell
  • your cygwin setup might be broken. Try deinstalling, following the instructions https://cygwin.com/faq/faq.html#faq.setup.uninstall-service, and reinstalling again. During reinstallation only install the required dependencies.