Building GEOS-Chem with CMake

This page provides instructions for building GEOS-Chem with CMake. This feature was added in GEOS-Chem 12.6.0 as an option. By default, GNU Make is still used to compile GEOS-Chem but it will be removed eventually.

This documentation was written by Liam Bindle (Dalhousie).

Before getting started

Before going through these instructions you should (1) have a run directory and (2) download the GEOS-Chem source code. You can use an existing run directory, provided its version matches your source code's version. Refer to Getting Started with GEOS-Chem for instructions on creating a run directory and downloading the GEOS-Chem source code.

Check if CMake is installed on your machine

The only new software requirement for building GEOS-Chem with CMake is CMake version 3.5 or greater. CMake is popular utility, and it might already be installed on your system. You can check what version of CMake (if any) is installed on your machine with

~/>  cmake --version
cmake version 3.10.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).

If CMake is not installed on your system or its version is less than 3.5, contact your system administator or download the latest version here.

Set up the new GEOS-Chem build environment

An objective of the transition to CMake has been simplifying the build environment. The only required environment variables are those that select your compilers. These are FC, CC, and CXX for Fortran, C, and C++ respectively. For GEOS-Chem Classic, only FC is required.

Optionally, if the nc-config or nf-config executables are not available on your machine, you can set NETCDF_ROOT, NETCDF_C_ROOT, or NETCDF_Fortran_ROOT environment variables to the directories where NetCDF's C and Fortran libraries are installed. Note that these variables have higher precidence than the install prefixes returned by nc-config and nf-config.

Below is an example ~/.bashrc that sets up an environment for building GEOS-Chem with CMake.

# Picking the compiler I want to use
export FC=gfortran

# Misc environment variables
export NETCDF_C_ROOT=/usr/local/netcdf/4.6.1                    # only required if nc-config is not available
export NETCDF_Fortran_ROOT=/usr/local/netcdf/4.6.1              # only required if nf-config is not available

Don't forget to source ~/.bashrc after you modify it!

Building GEOS-Chem

You should think of CMake as an interactive tool for configuring GEOS-Chem's build. For example, compile-time options like enabling timers, disabling multithreading, and turning on components like RRTMG are all configured with CMake commands. The CMake command also performs checks on your build environment to make sure the compilation is going to succeed. If it identifies any errors, such as missing dependencies or mismatched run directory and source code version numbers, CMake will tell you about the problem.

If you are new to CMake and would like a rundown of how to use the cmake command, check out my tutorial. This tutorial is not necessary, but it will make you more familiar with using CMake and help you better understand what is going on.

Below are the steps for building GEOS-Chem with CMake.

1. Navigate to your run directory

My run directory is ~/geosfp_2x25_complexSOA_SVPOA so I will cd there.