Configure with CMake

You should think of CMake as an interactive tool for configuring GEOS-Chem Classic’s build. For example, compile-time options like disabling multithreading and turning on components (e.g. APM, RRTMG) are all configured with CMake commands.

Besides configuring GEOS-Chem’s build, CMake also performs checks on your build environment to detect problems that would cause the build to fail. If it identifies a problem, like a missing dependency or mismatched run directory and source code version numbers, CMake will print an error message that describes the problem.

If you are new to CMake and would like a rundown of how to use the cmake command, check out Liam Bindle’s Cmake 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.

Initialize the build directory

Next, we need to initialize the build directory. Type:

$ cmake ../CodeDir -DRUNDIR=..

where ../CodeDir is the symbolic link from our run directory to the GEOS-Chem source code directory. CMake will generate output similar to this:

-- The Fortran compiler identification is GNU 11.2.0
-- Detecting Fortran compiler ABI info
-- Detecting Fortran compiler ABI info - done
-- Check for working Fortran compiler: /n/home09/ryantosca/spack/var/spack/environments/gc-classic/.spack-env/view/bin/gfortran - skipped
-- Checking whether /n/home09/ryantosca/spack/var/spack/environments/gc-classic/.spack-env/view/bin/gfortran supports Fortran 90
-- Checking whether /n/home09/ryantosca/spack/var/spack/environments/gc-classic/.spack-env/view/bin/gfortran supports Fortran 90 - yes
GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z
-- Found NetCDF: /n/home09/ryantosca/spack/opt/spack/linux-centos7-x86_64/gcc-8.3.0/netcdf-fortran-4.5.3-tb3oqspkitgcbkcyp623tdq2al6gxmom/lib/
-- Useful CMake variables:
  + CMAKE_PREFIX_PATH:    /path/to/netcdf-c /path/to/netcdf-fortran
  + CMAKE_BUILD_TYPE:     Release
-- Run directory setup:
  + RUNDIR:       /n/holyscratch01/jacob_lab/ryantosca/tests/test/test_cc
-- Threading:
  * OMP:          **ON**  OFF
-- Found OpenMP_Fortran: -fopenmp (found version "4.5")
-- Found OpenMP: TRUE (found version "4.5")
-- General settings:
  * MECH:         **fullchem**  carbon  Hg  custom
  * BPCH_DIAG:    **ON**  OFF
  * USE_REAL8:    **ON**  OFF
  * SANITIZE:     ON  **OFF**
-- Components:
  * TOMAS:        ON  **OFF**
  * TOMAS_BINS:   **NA**  15  40
  * APM:          ON  **OFF**
  * RRTMG:        ON  **OFF**
  * GTMM:         ON  **OFF**
  * HCOSA:        ON  **OFF**
  * LUO_WETDEP:   ON  **OFF**
Current status: A.B.C
GEOS-Chem T.U.V (science codebase)
Current status: T.U.V
Creating /n/holyscratch01/jacob_lab/ryantosca/tests/test/test_cc/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H
-- Configuring done
-- Generating done
-- Build files have been written to: /n/holyscratch01/jacob_lab/ryantosca/tests/test/test_cc/build

Your CMake command’s output contains important information about your build’s configuration.


The text X.Y.Z, A.B.C, and T.U.V refer to the version numbers (in semantic versioning style) of the GCClassic, HEMCO, and GEOS-Chem “science codebase” repositories.

Configure your build with extra options

Your build directory is now configured to compile GEOS-Chem using all default options. If you do not wish to change anything further, you may skip ahead to the next section.

However, if you wish to modify your build’s configuration, simply invoke CMake once more with optional parameters. Use this format:

$ cmake . -DOPTION=value

Note that the . argument is necessary. It tells CMake that your current working directory (i.e. .) is your build directory. The output of cmake tells you about your build’s configuration. Options are prefixed by a + or \* in the output, and their values are displayed or highlighted.


If you are colorblind or if you are using a terminal that does not support colors, refer to the CMake FAQ for instructions on disabling colorized output. For a detailed explanation of CMake output, see the next section.

The table below contains the list of GEOS-Chem build options that you can pass to CMake. GEOS-Chem will be compiled with the default build options, unless you explicitly specify otherwise.


Defines the path to the run directory.

In this example, our build directory is a subfolder of the run directory, so we can use -DRUNDIR=... If your build directory is somewhere else, then specify the path to the run directory as an absolute path.


Specifies the type of build. Accepted values are:


Tells CMake to configure GEOS-Chem in Release mode. This means that all optimizations will be applied and all debugging options will be disabled. (Default option).


Turns on several runtime error checks. This will make it easier to find errors but will adversely impact performance. Only use this option if you are actively debugging.


Specifies the chemical mechanism that you wish to use:


Activates the fullchem mechanism. The source code files that define this mechanism are stored in KPP/fullchem. (Default option)


Activates the Hg mechanism. The source code files that define this mechanism are stored in KPP/Hg.


Activates the carbon mechanism (CH4-CO-CO2-OCS). The source code files that define this mechanism are stored in KPP/carbon.


Activates a custom mechanism defined by the user. The source code files that define this mechanism are stored in KPP/custom.


Determines if GEOS-Chem Classic will activate OpenMP parallelization. Accepted values are:


Activates OpenMP parallelization. (Default option)

GEOS-Chem Classic will execute on as many computational cores as is specified with OMP_NUM_THREADS.


Deactivates OpenMP parallelization. GEOS-Chem Classic will execute on a single computational core. Useful for debugging.


Configure GEOS-Chem with the TOMAS aerosol microphysics package. Accepted values are:


Activate TOMAS microphysics.


Deactivate TOMAS microphysics (Default option)


Specifies the number of size-resolved bins for TOMAS. Accepted values are:


Use 15 size-resolved bins with TOMAS simulations.


Use 40 size-resolved bins with TOMAS simulations.


Toggles the legacy binary punch diagnostics on.


This option is deprecated and will be removed soon. Most binary-punch format diagnostics have been replaced by netCDF-based History diagnostics.

Accepted values are:


Activate legacy binary-punch diagnostics.


Deactivate legacy binary-punch diagnostics. (Default option)


Configures GEOS-Chem to use the APM microphysics package. Accepted values are:


Activate APM microphysics.


Deactivate APM microphysics. (Default option)


Configures GEOS-Chem to use the RRTMG radiative transfer model. Accepted values are:


Activates the RRTMG radiative transfer model.


Deactivates the RRTMG radiative transfer model. (Default option)


Configures GEOS-Chem to use the Luo et al., 2020 wet deposition scheme.


The Luo et al 2020 wet deposition scheme will eventually become the default wet deposition schem in GEOS-Chem. We have made it an option for the time being while further evaluation is being done.

Accepted values are:


Activates the Luo et al., 2020 wet deposition scheme.


Deactivates the Luo et al., 2020 wet deposition scheme. (Default option)


Activates the AddressSanitizer/LeakSanitizer functionality in GNU Fortran to identify memory leaks. Accepted values are:


Activates AddressSanitizer/LeakSanitizer


Deactivates AddressSanitizer/LeakSanitizer (Default option).

If you plan to use the make -j install option (recommended) to copy your executable to your run directory, you must reconfigure CMake with the RUNDIR=/path/to/run/dir option. Multiple run directories can be specified by a semicolon separated list. A warning is issues if one of these directories does not look like a run directory. These paths can be relative paths or absolute paths. Relative paths are interpreted as relative to your build directory. For example:

$ cmake . -DRUNDIR=/path/to/run/dir

For example if you wanted to build GEOS-Chem with all debugging flags on, you would type:

$ cmake . -DCMAKE_BUILD_TYPE=Debug

or if you wanted to turn off OpenMP parallelization (so that GEOS-Chem executes only on one computational core), you would type:

$ cmake . -DOMP=n


Understand CMake output

As you can see from the example CMake output listed above, GEOS-Chem Classic contains code from 3 independent repositories:

  1. GCClassic wrapper (aka “the superproject”):

GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z

where X.Y.Z specifies the GEOS-Chem Classic “major”, “minor”, and “patch” version numbers.


If you are cloning GEOS-Chem Classic between official releases, you may the see Current status reported like this:

X.Y.Z-alpha.n-C-gabcd1234.dirty  or


We will explain these formats below.

  1. HEMCO (Harmonized Emissions Component) submodule:

Current status: A.B.C

where A.B.C specifies the HEMCO “major”, “minor”, and “patch” version numbers. The HEMCO version number differs from GEOS-Chem because it is kept in a separate repository, and is considered a separate package.

  1. GEOS-Chem submodule:

GEOS-Chem X.Y.Z (science codebase)
Current status: X.Y.Z

The GEOS-Chem science codebase and GEOS-Chem Classic wrapper will always share the same version number.

During the build configuration stage, CMake will display the version number (e.g. X.Y.Z) as well as the current status of the Git repository (e.g. TAG-C-gabcd1234.dirty) for GCClassic, GEOS-Chem, and HEMCO.

Let’s take the Git repository status of GCClassic as our example. The status string uses the same format as the git describe --tags command, namely:




Indicates the most recent tag in the GCClassic superproject repository.

Tags may use the following notations:

  • X.Y.Z: Denotes an official release

  • X.Y.Z-rc.n: Denotes a release candidate

  • X.Y.Z-alpha.n: Denotes an internal “alpha” benchmark

where n is the number of the release candidate or alpha benchmark (starting from 0).


Indicates the number of commits that were made on top of the commit that is referred to by TAG.


Indicates that the version control system is Git.


Indicates the Git commit hash. This is an alphanumeric string that denotes the commit at the HEAD of the GCClassic repository.


If present, indicates that there are uncommitted updates atop the abcd1234 commit in the GCClassic repository.

Under each header are printed the various options that have been selected.