Building and installing

jornbr edited this page Apr 20, 2017 · 24 revisions

Prerequisites

In order to be able to build FABM, the following three conditions must be met:

  1. CMake 2.8.8 or later must be installed.
  2. A supported Fortran 2003 compiler must be installed, working and in the user's PATH.
  3. If you aim to use FABM with a host that uses NetCDF (most hosts, but not needed for the Python host, and optional for the 0d driver), you need a version of the NetCDF library that was compiled with the same Fortran compiler you will use to compile FABM. For Intel Visual Fortran on Windows, pre-compiled NetCDF libraries are provided.

Make sure these conditions are met before continuing. Questions related to getting the prerequisites in place do NOT belong on the FABM mailing lists.

Supported compilers

FABM has been compiled with the following compilers:

Compiler Supported versions
gfortran (part of GCC) 4.7 and up
Intel Fortran Compiler 12.1 and up
Cray Fortran Compiler 8.3.14 and up; lower versions might work but have not been tested

If you do not have a Fortran compiler yet: gfortran is freely available for most platforms. On Windows, it can be installed as part of MinGW-w64. On Linux, it can typically be installed from the package manager, often as part of GCC. On Mac OS, it may be easiest to install it through a separate package management system such as MacPorts.

If you experience problems with any of the above compilers, or have found that FABM also compiles successfully with another compiler, please report this on the FABM mailing list.

Building and installing

FABM uses a build system based on CMake. CMake in turn generates platform-specific build systems, for instance make files on Linux, and Visual Studio solutions on Windows.

Quick start

Foremost, if the host you aim to use FABM with is listed in the right-hand panel under "User guide", "Specific hosts", then start there as custom installation instructions are usually available.

The FABM library

For host that do not use CMake, FABM must be built as a library. This library can then be linked against when building the host itself.

CMake setting value
Source directory <FABMDIR>/src
Additional required arguments FABM_HOST=<HOSTNAME>

Here, <HOSTNAME> is the name of the host that FABM is built for; it must match the name of one of the subdirectories under <FABMDIR>/src/drivers.

For instance, on Linux:

mkdir ~/build/fabm && cd ~/build/fabm
cmake <FABMDIR>/src -DFABM_HOST=<HOSTNAME>
make install

Step by step: Windows

We regularly test two methods of compiling FABM on Windows. One is based on the GNU Fortran compiler through the freely available MinGW-w64 compiler suite. The other uses Intel Visual Fortran in combination with Visual Studio (both commercial software).

MinGW-w64: GNU Fortran on Windows

A step by step procedure for downloading, installing and configuring MinGW-w64 to compile FABM on Windows:

  1. To install MinGW-w64, download and run the installer.
    • Note: in some cases, you may already have MinGW or MinGW-w64 on your system. For instance, the Enthought Python Distribution and Enthought Canopy already come with MinGW (in their "Scripts" directory). These can be used as is. They may also be in your path (test by executing "mingw32-make"). If so, the next step may be skipped.
  2. Add the MinGW install directory to the PATH.
    • To do so on Windows Vista/7: click Start, left-click your user picture in the top right-hand corner of the start menu, click "Change my environment variables". Then, if PATH is not listed among user variables, click the "New..." button, enter "PATH" for "Variable name", and "%PATH%;<mingw_install_dir>\bin" for the variable value. If the PATH variable exists already, select it, click the "Edit..." button, and add ";<mingw_install_dir>\bin" to the end of the variable value. Replace <mingw_install_dir> with the directory where you installed MinGW-w64.
  3. Start "CMake (cmake-gui)" (make sure you have CMake 2.8.8 or later installed first).
  4. Browse the 'Where is the source code' to the desired source directory (see e.g. the above quick start instructions)
  5. Browse the 'Where to build the binaries' - e.g. C:\Users<user name>\build\fabm-0d (replace "fabm-0d" with a name that is appropriate for the driver you want to build FABM for). WARNING: some versions of CMake (e.g., 3.0.2) generate invalid makefiles for MinGW if the build directory is on a remote server (i.e., a path starting with \\); to avoid problems, place it on a local or mounted network drive instead.
  6. Click the "Configure" button. This first time you do this, CMake asks you to select a build system generator; choose "MinGW Makefiles" and press the "Finish" button.
  7. Now all configuration variables for the build system are listed. You can change these according to your preferences. After changing any variable, press the "Configure" button again - additional settings may appear.
  8. If all configuration variables are set correctly, and you have clicked the "Configure" button until no new (red-coloured) configuration variables appear, press the 'Generate' button. This creates the MinGW make files.
  9. Open a command prompt (run "cmd") and cd to the build directory (not the src directory!) defined above.
  10. Type and run "mingw32-make install". Notes:
    • This install files in the directory indicated by the CMake variable CMAKE_INSTALL_PREFIX, shown in CMake-Gui.
    • To speed up the build process, you can do a parallel build by providing the argument -j N to mingw32-make, with N being the number of parallel jobs. This number is typically set equal to the number of cores of the machine you build on.
    • The installed files are specific to the currently selected source directory and CMake settings. If you want to build and install again with other settings, you have to go through steps 5-10 again. Typically, you would want to do so in a new, separate build directory.

Whenever you update the FABM source code by pulling in the latest version from the git repository, you have to rerun "mingw32-make install" in all build directories. It is not needed to rerun CMake itself.

Intel Visual Fortran and Visual Studio

If you have Intel Visual Fortran with Visual Studio integration, you can use this to build FABM. Step by step:

  1. Start "CMake (cmake-gui)" (make sure you have CMake 2.8.8 or later installed first).
  2. Browse the 'Where is the source code' to the desired source directory (see e.g. the above quick start instructions)
  3. Browse the 'Where to build the binaries' - e.g. C:\Users<user name>\build\fabm-0d (replace "fabm-0d" with a name that is appropriate for the driver you want to build FABM for).
  4. Click the "Configure" button. This first time you do this, CMake asks you to select a build system generator; select your version of Visual Studio and press OK. Note that Visual Studio build system are generated either for 32-bit builds or for 64-bit architectures (the latter have Win64 appended to the generator name). You can choose either, with the following constraints:
    • If you want to build FABM's python driver, it must be built for the same architecture used by your Python installation. If your python is 32-bit, select generator "Visual Studio <some number and year>". If your python is 64-bit, select "Visual Studio <some number and year> Win64".
    • If you want to build GOTM or FABM's 0d driver with NetCDF support, it is easiest to use the NetCDF libraries that come with GOTM (that's the default). These are 32-bit, so you then need to select a 32-bit generator.
  5. Now all configuration variables for the build system are listed and you can change them according to your preferences. After changing any variable, press the "Configure" button again - additional settings may appear.
  6. If all configuration variables are set correctly, and you have clicked the "Configure" button until no new (red-coloured) configuration variables appear, press the 'Generate' button. This creates the Visual Studio solution and projects.
  7. Open Visual Studio, and open the solution (.sln) that CMake has created in the build directory chosen in CMake.
  8. To build and install the FABM libraries, right-click the "INSTALL" project in the solution explorer, and choose "Build" (if you only want to build, choose "Build", "Build Solution" in the top menu).

Whenever you update the FABM source code by pulling in the latest version from the git repository, we advise that you re-open CMake, select the original build directory, and click Configure, followed by Generate. After that, you can choose "Build" in Visual Studio, which should then recompile any updated files.

Step by step: Linux and Mac OS

To check whether you have CMake installed, try executing cmake --version. If cmake is available, this command will also show its version number. Check this; you need 2.8.8 or higher. If cmake returns "command not found", cmake will need to be installed first - this is generally easy, as CMake has no external dependencies.

When using cmake, building happens in three phases: First you create a build configuration, then you build the source code, and finally you install it.

Creating a build configuration

A build configuration is placed in a separate directory. The location of this directory is not relevant to either FABM or any host models that depend on FABM - it is your choice only. Whatever you choose, make sure that you create this configuration in a new, empty directory!

CMake advocates for 'out of source' builds. Here we create a FABM specific build directory in $HOME:

cd
mkdir -p build/fabm
cd build/fabm

When you are in the directory where you want FABM to build, you run cmake with two arguments:

  • The path to the FABM source code. This is the "src" directory in the root of the FABM repository.
  • The host to compile FABM for. This is specified by adding argument -DFABM_HOST=<HOSTNAME>, where <HOSTNAME> must match the name of one of the directories in src/drivers, e.g., mom5, fvcom, roms.

Thus, if you have created the build directory as above, you can do:

# In the build directory:
cmake $FAMBDIR/src -DFABM_HOST=mom5

This creates a set of make files that can be used to build FABM.

The build configuration can be customized by providing additional arguments to cmake:

  • CMake will do its best to detect a suitable Fortran compiler. If this fails, or if you want to manually specify another compiler, you can do so by adding -DCMAKE_Fortran_COMPILER=<COMPILER> in the call to cmake. Here, <COMPILER> is the Fortran compiler executable. We have found this to be necessary on Cray systems that use the ftn compiler wrapper scripts; specifying -DCMAKE_Fortran_COMPILER=ftn then assures the compiler is found.
  • By default, FABM is compiled as "release" version. That is, compiled code will be optimized to maximize performance and it will not contain debug information. If you instead want to compile a "debug" version, add argument -DCMAKE_BUILD_TYPE=Debug.
  • The build configuration defines where the compiled FABM files will be installed. By default, this is ~/local/fabm/<HOSTNAME>, under which lib and include subdirectories will be created. If you want to change the installation directory, you can do so by adding -DCMAKE_INSTALL_PREFIX=<PATH> in the call to cmake. Here, <PATH> is the directory where the FABM files (include files, libraries) for the currently selected host should be installed.

Building

After cmake has created your build configuration, building the code is usually easy:

make

This builds the FABM libraries (and for some hosts, executables). These are placed in the build configuration directory.

Installing

Installation copies all files associated with FABM (libraries, Fortran module files) to their appropriate locations. This is done by executing:

make install

Building FABM with multiple compilers

The default installation directory of FABM (e.g., ~/local/fabm/<HOSTNAME>) does not reference the name of the Fortran compiler used. Therefore, builds with different compilers will install in the same directory. If you consecutively build and install FABM with different Fortran compilers, only the final build/install will be left in the installation directory.

If you want to provide simultaneous access to FABM versions built with different compilers (e.g., an ifort version and gfortran version), this can be achieved by explicitly specifying the installation path by adding -DCMAKE_INSTALL_PREFIX=<PATH> in the call to cmake. Here, <PATH> is the directory where FABM should be installed. For instance, you could create separate build directories for ifort and gfortran builds, and run cmake with -DCMAKE_INSTALL_PREFIX=~/local/fabm-gfortran/<HOSTNAME> in the former, and cmake with -DCMAKE_INSTALL_PREFIX=~/local/fabm-ifort/<HOSTNAME> in the latter.

A similar strategy can be used to provide simultaneous access to FABM versions with different build types, e.g., Release, Debug. In that case you would specify DCMAKE_INSTALL_PREFIX and CMAKE_BUILD_TYPE.

Tips

Below are two scripts that will configure and keep hosts 0d, gotm and python up to date for ifort and gfortran compilers. The script can very easy be modified according to other needs. Providing the command line argument 'clean' will not build but clean all targets. Putting the script in e.g. ~/build/fabm a simple '. ./build_all' will keep FABM updated. Note that NetCDF specific settings are obtained through nf-config - which most be in the path and properly invoked according to the chosen Fortran compiler. These scripts are only provided as inspiration.

configure_all

#!/bin/sh

compilers="gfortran ifort"

# 0d
host=0d
cd $host
for compiler in $compilers; do
   cd $compiler
   cmake $FABMDIR/src -DCMAKE_Fortran_COMPILER=$compiler -DFABM_HOST=$host -DGOTM_BASE=$GOTMDIR
   cd ..
done
cd ..

# gotm
host=gotm
cd $host
for compiler in $compilers; do 
   cd $compiler
   cmake $FABMDIR/src -DCMAKE_Fortran_COMPILER=$compiler -DFABM_HOST=$host
   cd .. 
done
cd .. 

# python
host=python
cd $host
cmake $FABMDIR/src -DCMAKE_Fortran_COMPILER=$compiler -DFABM_HOST=$host
cd ..

build_all

#!/bin/sh

old=`pwd`
cd ~/FABM/fabm-git
git pull
cd $old

if [ "$1" != "" ]; then
   action=$1
   echo "doing a "$action 
else
   action=install
fi

np=-j8

compilers="gfortran ifort"
hosts="0d gotm"

for host in $hosts; do
  cd $host
   for compiler in $compilers; do
      cd $compiler
      make $np $action
      cd ..
   done
   cd ..
done

cd python
make $np $action
cd ..
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.