Compiling with CMake
- Minimum system requirements
- Installing required software
- Configuring your computational environment
- Downloading source code
- Downloading data directories
- Creating run directories
- Configuring runs
- Compiling GEOS-Chem
- ... with CMake
- ... with GNU Make
- Output files
- Python tools for use with GEOS-Chem
- Coding and debugging
- Further reading
- 1 Overview
- 2 Before getting started
- 3 Building GEOS-Chem
- 4 Recompiling from scratch
- 5 Further reading
CMake is a platform-independent build system. It creates Makefiles that can be used to compile GEOS-Chem source code into an executable file.
On this page, we will describe the basic steps that you need to compile GEOS-Chem with CMake. For a deeper dive into CMake, we recommend that you visit the CMake Frequently Asked Questions (FAQ) page that has been prepared by GCST member Liam Bindle.
As shown in the previous chapter, GEOS-Chem 12.6.0 and later versions can be compiled with either CMake or GNU Make. GNU Make will be retired in GEOS-Chem 13.0.0. Thus, in 13.0.0 and later versions, compiling GEOS-Chem will require CMake.
Before getting started
Before going through these instructions you should do the following:
Check if CMake is installed on your system
The only new software requirement for building GEOS-Chem with CMake is CMake version 3.13. CMake is popular utility, and it might already be installed on your system. You can check which version of CMake (if any) is installed on your machine by typing:
[~]$ cmake --version cmake version 3.19.0 CMake suite maintained and supported by Kitware (kitware.com/cmake). [~]$
If your computer system uses a software module system (such as Lmod or environment-modules), you can test if there is a pre-installed CMake module on your system with a command such as
[~]$ module avail cmake
and then once you know the module name, you can load it into your Unix environment with a command such as:
[~]$ module load cmake/3.19
Ask your IT staff what the proper module command syntax is for your system.
Even though GEOS-Chem will work with CMake 3.13 or later, we recommend obtaining a recent CMake version (3.17 or later). This will ensure that ensure that you will have a CMake version with recent bug fixes and updates applied.
If CMake is not installed on your system (or its version is less than the required) contact your system administator. The latest CMake code may be obtained here. You can also install CMake with the Spack package manager.
Set the proper environment variables
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-fortran/4.4.4 # only required if nf-config is not available
Don't forget to source ~/.bashrc after you modify it!
Download GEOS-Chem and create a run directory
Once you have CMake installed, then follow the instructions from previous chapters in this Guide to download the GEOS-Chem source code and to create a run directory for the simulation that you wish to perform.
You should think of CMake as an interactive tool for configuring GEOS-Chem'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 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.
Let's assume our run directory is ~/gc_4x5_fullchem, so we'll cd there and get a directory listing:
[~]$ cd ~/gc_4x5_fullchem [gc_4x5_fullchem]$ ls archiveRun.sh* getRunInfo* OutputDir/ build/ HEMCO_Config.rc README cleanRunDir.sh* HEMCO_Diagn.rc rundir.version CodeDir@ HISTORY.rc runScriptSamples/ download_data.py* input.geos species_database.yml GEOSChem.Restart.20190701_0000z.nc4 metrics.py* [gc_4x5_fullchem]$
Note that each GEOS-Chem run directory that you generate has a folder named build/. This is where we will run CMake.
The build directory is where CMake and your compilers are going to put the files they generate. For this example, we will use the build/ folder that was automatically generated in the GEOS-Chem Classic run directory. For GCHP you will need to create one.
[gc_4x5_fullchem]$ cd build [gc_4x5_fullchem/build]$
NOTE: You are free to create a build directory with a different name. Sometimes it is convenient to create multiple build directories for compiling GEOS-Chem with different compilers (e.g. build_gfortran93, build_ifort18), etc.).
3. Initialize your build directory
Next, we need to initialize the build directory. Type:
[gc_fullchem_4x5/build]$ cmake ../CodeDir -DRUNDIR=..
where ../CodeDir is the symbolic link from our run directory (gc_fullchem_4x5/) to the GEOS-Chem source code directory. CMake will generate output similar to this:
================================================================= GCClassic 13.0.0 (top-level wrapper) Current status: 13.0.0-beta.1-16-ged3eabe.dirty ================================================================= -- Useful CMake variables: + CMAKE_PREFIX_PATH: /path/to/libraries/... + CMAKE_BUILD_TYPE: Release -- Run directory setup: + RUNDIR: .. -- Bootstrapping .. -- Threading: * OMP: ON OFF -- General settings: * CUSTOMMECH: ON OFF * BPCH_DIAG: ON OFF * USE_REAL8: 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 ================================================================= HEMCO 3.0.0 Current status: 3.0.0-beta.0-2-g777c2ae.dirty ================================================================= -- Settings: * OMP: ON OFF * USE_REAL8: ON OFF ================================================================= GEOS-Chem 13.0.0 (science codebase) Current status: gcc_13.0.0-alpha.13-93-gdc4999053 ================================================================= Creating /home/gc_4x5_fullchem/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H -- Configuring done -- Generating done -- Build files have been written to: /home/gc_4x5_fullchem/build
Your CMake command's output contains important information about your build's configuration. We will explain this output below.
4. Configure your build
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:
[gc_fullchem_4x5/build]$ cmake . -D<name>="<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.
|Item||Default option||Select another option|
|Run directory path||-DRUNDIR=||-DRUNDIR=..|
(GEOS-Chem 12.6.0 - 12.9.3)
(GEOS-Chem 13.0.0 and later)
|Build GEOS-Chem with OpenMP parallelization||-DOMP=y||-DOMP=n|
|Build GEOS-Chem with binary punch (BPCH) diagnostics||-DBPCH_DIAG=n||-DBPCH_DIAG=y|
|Build GEOS-Chem with 64-byte (REAL*8) precision
NOTE: Not fully implemented!
|Build GEOS-Chem with TOMAS Microphysics||-DTOMAS=n||-DTOMAS=y|
|Build GEOS-Chem with TOMAS Microphysics using 15 or 40 bins||-DTOMAS_BINS=NA||-DTOMAS_BINS=15 or|
|Build GEOS-Chem with APM Microphysics||-DAPM=n||-DAPM=y|
|Build GEOS-Chem with the RRTMG radiative transfer model||-DRRTMG=n||-DRRTMG=y|
|Build GEOS-Chem with the Global Terrestrial Mercury Model
NOTE: Currently disabled
|Build GEOS-Chem with the HEMCO standalone||-DHCOSA=n||-DHCOSA=y|
|Build GEOS-Chem with the Luo et al 2019 wet deposition scheme||-DLUO_WETDEP=n||-DLUO_WETDEP=y|
For example if you wanted to build GEOS-Chem with all debugging flags on, you would type:
[gc_fullchem_4x5/build]$ 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:
[gc_fullchem_4x5/build]$ cmake . -DOMP=n
If you plan to use the make install option (recommended) to copy your executable to your run directory, you must reconfigure CMake with the -DRUNDIR 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:
[gc_fullchem_4x5/build]$ cmake . -DRUNDIR=/path/to/rundir
5. Understanding the output from CMake
As you can see from the example CMake output from Section 3, GEOS-Chem "Classic" 13.0.0 and later versions contain code from 3 independent repositories:
1. GCClassic wrapper (aka "the superproject"), https://github.com/geoschem/geos-chem-classic.git
================================================================= GCClassic 13.0.0 (superproject wrapper) Current status: 13.0.0-alpha.8-27-g1158ac1.dirty =================================================================
2. HEMCO (Harmonized Emissions Component) submodule, https://github.com/geoschem/hemco.git:
================================================================= HEMCO 3.0.0 Current status: gcc_13.0.0-alpha.4-12-g3b0a804 =================================================================
3. GEOS-Chem submodule, https://github.com/geos-chem/geos-chem.git:
================================================================= GEOS-Chem 13.0.0 (science codebase) Current status: gcc_13.0.0-alpha.8-57-gdd726b48 =================================================================
During the build configuration stage, CMake will display the VERSION NUMBER (e.g. 13.0.0) as well as the CURRENT STATUS OF THE GIT REPOSITORY (e.g. 13.0.0-alpha.8-27-g1158ac1.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:
|13.0.0-alpha.8||Indicates the most recent tag in the GCClassic repository.|
|27||Indicates the number of commits that have been made on top of tag 13.0.0-alpha.8.|
|g||Indicates that the version control system is Git.|
|1158ac1||Indicates the Git commit ID (short version) at which the HEAD of the GCClassic repository is located.|
|.dirty||Indicates that there are code updates that have not yet been committed to this repository (if present).|
Under each header are printed the various build options that have been selected, as well as other relevant information:
|CMAKE_PREFIX_PATH||Indicates the path to important libraries such as netCDF and netCDF-Fortran.|
|CMAKE_BUILD_TYPE||Indicates the type of build that was selected.
|* MECH: fullchem custom||Indicates which chemistry mechanism is being used.|
|* X: ON OFF||Indicates whether option X has been turned on or off.|
6. Compile GEOS-Chem
Now that CMake has written build files to your build directory, you can compile GEOS-Chem with the make command:
[gc_fullchem_4x5/build]$ $ make -j
You will see output similar to this:
[ 1%] Built target KPPFirstPass_fullchem [ 3%] Built target HeadersHco [ 4%] Building Fortran object src/GEOS-Chem/ISORROPIA/CMakeFiles/Isorropia.dir/isorropiaII_main_mod.F.o [ 6%] Built target JulDayHco [ 6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_chm_mod.F90.o [ 6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_met_mod.F90.o [ 7%] Building Fortran object src/HEMCO/src/Shared/NcdfUtil/CMakeFiles/NcdfUtilHco.dir/hco_ncdf_mod.F90.o [ 7%] Linking Fortran static library libNcdfUtilHco.a [ 10%] Built target NcdfUtilHco Scanning dependencies of target GeosUtilHco [ 12%] Building Fortran object src/HEMCO/src/Shared/GeosUtil/CMakeFiles/GeosUtilHco.dir/hco_henry_mod.F90.o [ 12%] Building Fortran object src/HEMCO/src/Shared/GeosUtil/CMakeFiles/GeosUtilHco.dir/hco_regrid_a2a_mod.F90.o [ 13%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_diag_mod.F90.o [ 13%] Linking Fortran static library libGeosUtilHco.a [ 13%] Built target GeosUtilHco ... [ 98%] Building Fortran object src/GEOS-Chem/GeosCore/CMakeFiles/GeosCore.dir/gc_environment_mod.F90.o [ 98%] Building Fortran object src/GEOS-Chem/GeosCore/CMakeFiles/GeosCore.dir/chemistry_mod.F90.o [ 98%] Building Fortran object src/GEOS-Chem/GeosCore/CMakeFiles/GeosCore.dir/cleanup.F90.o [ 98%] Linking Fortran static library libGeosCore.a [ 98%] Built target GeosCore Scanning dependencies of target geos [ 98%] Building Fortran object src/CMakeFiles/geos.dir/GEOS-Chem/Interfaces/GCClassic/main.F90.o [100%] Linking Fortran executable ../bin/geos [100%] Built target geos [gc_fullchem_4x5/build]$
Note that the -j argument tells make that it can execute as many jobs as it wants simultaneously. If you want to restrict the number of simultaneous jobs (e.g. you are compiling on a machine with limited memory), you can add a number after -j. For example, to restrict the number of jobs to 4, you would do make -j4. If you don't want make to run simultaneous jobs, don't use the -j argument.
7. Install the geos executable in your run directory
Now that geos is built, install it to your run directory with make install. For this to work properly, you must tell CMake where to find your run directory by configuring CMake with -DRUNDIR as described in step 4. Type the following:
[gc_fullchem_4x5/build]$ make install
and you will see output similar to this:
[ 1%] Built target KPPFirstPass_fullchem [ 10%] Built target Headers [ 10%] Built target JulDay [ 16%] Built target NcdfUtil [ 22%] Built target GeosUtil [ 25%] Built target Transport [ 27%] Built target HeadersHco [ 28%] Built target JulDayHco [ 33%] Built target NcdfUtilHco [ 34%] Built target GeosUtilHco [ 50%] Built target HCO [ 59%] Built target HCOX [ 59%] Built target HCOI_Shared [ 65%] Built target KPP_fullchem [ 68%] Built target History [ 69%] Built target ObsPack [ 71%] Built target Isorropia [ 98%] Built target GeosCore [100%] Built target geos Install the project... -- Install configuration: "Release" -- Installing: /n/home05/msulprizio/RD/gc_4x5_fullchem/build_info/CMakeCache.txt -- Installing: /n/home05/msulprizio/RD/gc_4x5_fullchem/build_info/summarize_build -- Installing: /n/home05/msulprizio/RD/gc_4x5_fullchem/gcclassic [gc_fullchem_4x5/build]$
Let's now navigate back to the run directory and get a directory listing:
[gc_fullchem_4x5/build]$ cd .. [gc_fullchem_4x5]$ ls archiveRun.sh* GEOSChem.Restart.20190701_0000z.nc4 OutputDir/ build/ getRunInfo* README build_info/ HEMCO_Config.rc rundir.version cleanRunDir.sh* HEMCO_Diagn.rc runScriptSamples/ CodeDir@ HISTORY.rc species_database.yml download_data.py* input.geos gcclassic* metrics.py* [gc_fullchem_4x5]$
You should now see the gcclassic executable and a build_info directory there. GEOS-Chem has now been configured, compiled, and installed in your run directory. You are now ready to run a GEOS-Chem simulation! Please skip ahead to our Running GEOS-Chem chapter.
Recompiling from scratch
CMake will generate all the Makefiles and compiled files (e.g. *.o, *.a, *.mod) in sub-folders of the build folder in your run directory. This ensures that the GEOS-Chem source code will be kept free of compiled output.
Unlike older versions of GEOS-Chem that used GNU Make, there is no equivalent make realclean command with CMake. If you wish to recompile GEOS-Chem from scratch you can do one of the following:
- Remove the build/CMakeCache.txt file
- Remove all the files in the build/ folder
- Create a new folder from which to configure and build GEOS-Chem. For example:
# Configure and build GEOS-Chem with all debugging options turned on mkdir build_debug cd build_debug cmake ../CodeDir -DCMAKE_BUILD_TYPE=Debug -DRUNDIR=.. ... include other build options as needed ... make -j make -j install
- CMake FAQ by Liam Bindle
- CMake tutorial (cmake.org)
- Learn X in Y minutes (where X is CMake)
- GEOS-Chem coding and debugging
- Guide to GEOS-Chem error messages