Skip to content

Building and installing

Jorn Bruggeman edited this page Jan 11, 2024 · 96 revisions

Quick start

Prerequisites

FABM is written in Fortran and uses CMake to generate platform-specific build configurations. Therefore, you will need:

  1. The FABM source code
  2. CMake 3.13 or later
  3. A supported Fortran compiler

If you are starting on a system without cmake and/or a Fortran compiler, take a look at the step-by-step instructions for Linux and Mac or for Windows.

If you are embedding FABM in a hydrodynamic model, that may have additional requirements of its own. Discussing these is beyond the scope of this guide. However, it is worth noting that all Fortran codes that are used in your application - the hydrodynamic model, FABM itself, and any dependencies with a Fortran component - typically need to be built with the same compiler. This is a particular concern for prebuilt dependencies that are distributed as binary. This often includes the NetCDF library used by numerous hydrodynamic models. It can be particularly difficult to source suitable NetCDF libraries on Windows. For Intel Visual Fortran on Windows, we therefore provide pre-compiled NetCDF 3 libraries.

Building and installing

Before you begin: if your target host is listed in the right-hand panel under "User guide", "Specific hosts", then start there as custom installation instructions are usually available. The following instructions show how to build FABM as a library, which can then be linked against when building the host itself.

Command line (Linux, Mac, Windows)

  1. Create an empty directory to build in and enter it:
    mkdir build
    cd build
  2. Generate the build configuration:
    cmake <FABMDIR> -DFABM_HOST=<HOSTNAME>
    
    <FABMDIR> is the path to the directory with FABM source code. <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. CMake will try to auto-detect your Fortran compiler and tell you which one it has selected. If this is not the right one, override it by adding -DCMAKE_Fortran_COMPILER=<COMPILER_EXECUTABLE> in the call to cmake.
  3. Build and install:
    cmake --build . --target install
    
    This will create the FABM library and necessary include files at ~/local/fabm/<HOSTNAME> on Linux and Mac, and at %LOCALAPPDATA%\fabm\<HOSTNAME> on Windows.

If you subsequently update the FABM source code, you only need to repeat step 3.

CMake GUI (typically used on Windows)

  1. open "CMake (cmake-gui)" from the start menu (Windows) or by typing cmake-gui in a terminal.
  2. set "Where is the source code" to the directory with FABM source code and pick an empty directory for "Where to build the binaries"
  3. Click "Configure" and select a Fortran compiler
  4. Set FABM_HOST to the name of the host (hydrodynamic model) you want to build FABM for. It must match the name of one of the subdirectories under <FABMDIR>/src/drivers.
  5. Click "Generate"
  6. Build:
    • If using Visual Studio on Windows, click "Open Project" to open the generated solution. Then right-click INSTALL and choose "Build all"
    • Otherwise, close CMake GUI and run cmake --build <BUILDIR> --target install, with <BUILDIR> being the directory you selected for "Where to build the binaries" (step 2 above)

Supported compilers

FABM needs a compiler that supports at least the Fortran 2003 standard. The following have been found to work:

Compiler Notes
gfortran (part of GCC) 5 and up. For 8.x you need to run cmake with -DFABM_USE_CONTIGUOUS=OFF.
Intel Fortran 12.1 and up
Cray Fortran 8.3.4 and up; earlier versions might work but have not been tested
PGI Fortran 18.10 and up; earlier versions might work but have not been tested. For some versions (at least 18.10) you may need to set -DFABM_USE_DO_CONCURRENT=OFF
NAG Fortran 7.0 (build 7019) and up
AMD Optimizing Compiler Collection (flang) 2.2 and up; earlier 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. You could also consider installing the free Intel Fortran compiler instead of gfortran.

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

Compilation settings

FABM's default compilation settings are fine for most applications. The following settings can be useful under specific circumstances. They are typically used to accommodate specific Fortran compilers or host models. You use these settings by providing them to cmake, either on the command line with, for instance, -DFABM_REAL_KIND="selected_real_kind(6)" or -DFABM_USE_DO_CONCURRENT=OFF, or by configuring them in cmake-gui or ccmake.

Setting Usage
FABM_REAL_KIND Set the kind (precision) of real variables. This is selected_real_kind(13) by default, which equates to 64-bit real variables (double precision). By setting it to selected_real_kind(6) you can switch to 32-bit real variables (single precision). This setting affects the host API, i.e., the kind of real arguments accepted by the FABM procedures called by hydrodynamic models. It must therefore match the real kind used by the host. By default it also sets the precision of all biogeochemical variables and calculations (the rk parameter), but that can separately be controlled by FABM_REAL_KIND_INTERNAL (see below).
FABM_REAL_KIND_INTERNAL Set the kind (precision) of real variables in biogeochemical models (the rk parameter). By default this is equal to the value of FABM_REAL_KIND (see above). This setting can be used to reduce precision for biogeochemistry (by assigning it selected_real_kind(6)), which can lead to modest performance improvements.
FABM_USE_IEEE_ARITHMETIC Use the Fortran 2003 ieee_arithmetic module, which enables additional checks (NaN detection) in debug builds. This is ON by default; set it to OFF for compilers that do not support this module (e.g., gfortran 4.x)
FABM_USE_DO_CONCURRENT Use the Fortran 2008 do concurrent construct, which benefits performance. This is ON by default; set it to OFF for compilers that do not support it (e.g., older versions of the PGI Fortran compiler)
FABM_USE_CONTIGUOUS Use the Fortran 2008 contiguous attribute if the host model supports it. This benefits performance. This is ON by default; set it to OFF for compilers that do not support it (e.g., gfortran 8.x)

Step by step: Windows

We regularly test two methods of compiling FABM on Windows. One is based on the GNU Fortran compiler available through Anaconda. The other uses Intel Visual Fortran in combination with Visual Studio.

GNU Fortran

Here we install all build tools, including a Fortran compiler, from scratch. For this purpose we use Anaconda. It is also possible to install the compiler (MinGW-w64) and other tools (CMake) manually, but that its beyond the scope of this guide.

  1. Ensure you have Anaconda: look for "Anaconda prompt" in the start menu. If this does not exist, you can install Miniconda (no administrator permissions required).
  2. Open a command line terminal by clicking "Anaconda prompt" in the start menu.
  3. Create an isolated environment with all necessary build tools by executing
    conda create -n fabm -c conda-forge cmake m2w64-gcc-fortran m2w64-make
    
  4. Activate the new environment:
    conda activate fabm
    
  5. Create a new, empty directory to build FABM in, and enter it. For instance:
    mkdir build
    cd build
    
  6. Generate the build configuration:
    cmake <FABMDIR> -DFABM_HOST=<HOSTNAME> -G "MinGW Makefiles" -DCMAKE_Fortran_COMPILER=gfortran
    
    Here, <FABMDIR> is the directory with the FABM source code and <HOSTNAME> is the name of the host you want to build FABM for.
  7. Build and install:
    cmake --build . --target install
    

Whenever you update the FABM source code (for instance, by pulling in the latest version from the git repository), you can go back to your original build directory and repeat step 7 to update your FABM library.

Intel Visual Fortran and Visual Studio

  1. Ensure you have:

    These are all freely available.

  2. Start "CMake (cmake-gui)" from the start menu.

  3. Set "Where is the source code" to the directory with the FABM source code.

  4. Set "Where to build the binaries" to an empty directory where FABM is to be built.

  5. 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.

  6. 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.

  7. If all configuration variables are set correctly and you have clicked the "Configure" button until no new (red-colored) configuration variables appear, click the "Generate" button. This creates the Visual Studio solution.

  8. Click the "Open Project" button to open the generated solution in Visual Studio.

  9. 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 (for instance, by pulling in the latest version from the git repository), re-open CMake, select the original build directory and continue from step 5 above.

Step by step: Linux and Mac OS

Here we install all build tools, including a Fortran compiler, from scratch.

  1. Open a command line terminal
  2. Ensure you have Anaconda: execute conda --version. If this fails, you can install Miniconda (no root privileges required)
  3. Create an isolated environment with all necessary build tools by executing
    conda create -n fabm -c conda-forge cmake fortran-compiler
    
  4. Activate the new environment:
    conda activate fabm
    
  5. Create a new, empty directory to build FABM in, and enter it. For instance:
    mkdir build
    cd build
    
  6. Generate the build configuration:
    cmake <FABMDIR> -DFABM_HOST=<HOSTNAME>
    
    Here, <FABMDIR> is the directory with the FABM source code and <HOSTNAME> is the name of the host you want to build FABM for.
  7. Build and install:
    cmake --build . --target install
    

Whenever you update the FABM source code (for instance, by pulling in the latest version from the git repository), you can go back to your original build directory and repeat step 7 to update your FABM library.