Building and installing

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. Generate the build configuration in a new directory named build:

   cmake -S <FABMDIR> -B build -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.
2. Build and install:

   cmake --build 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 2.

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 Compiler Classic (ifort)	2021.1 and up; many earlier older versions used to work as well, but are no longer freely available and therefore not tested.
Intel Fortran Compiler (ifx)	2023.2 and up
NVIDIA HPC SDK	20.7 and up (earlier versions were released as PGI Fortran)
AMD Optimizing Compiler Collection (Classic Flang)	3.2 and up; earlier versions may work but have not been tested.
Flang (part of LLVM)	19 and up; earlier versions do not work
Cray Fortran	15.0.0 and up; some earlier versions used to work as well (e.g., 12.0.3 worked if the level of interprocedural optimization was reduced with -h ipa2), but these are no longer available and therefore not tested.
PGI Fortran (replaced by NVIDIA HPC SDK)	18.10 and up; earlier versions may 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

If you do not have a Fortran compiler yet: gfortran is freely available for all 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. Generate the build configuration in anew directory named build:

   cmake -S <FABMDIR> -B build -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.
6. Build and install:

   cmake --build build --target install
   

Whenever you update the FABM source code (for instance, by pulling in the latest version from the git repository), you need to repeat steps 4 and 6 to update your FABM library.

Intel Visual Fortran and Visual Studio

1. Ensure you have:

   • CMake 3.13 or later
   • Microsoft Visual Studio
   • the Intel Fortran Compiler

   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. Generate the build configuration in a new directory named build:

   cmake -S <FABMDIR> -B build -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.
6. Build and install:

   cmake --build build --target install
   

Whenever you update the FABM source code (for instance, by pulling in the latest version from the git repository), you need to repeat steps 4 and 6 to update your FABM library.