Compiling with CMake
- Minimum system requirements
- 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
- Visualizing and processing output
- Coding and debugging
- Further reading
- 1 Overview
- 2 Obtaining CMake
- 3 Compiling GEOS-Chem "Classic" with CMake
- 4 Compiling GCHP with CMake
- 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.
GEOS-Chem requires CMake version 3.5 or later. But we recommend version 3.15 or later if possible. Check with your IT staff if you have a version of CMake already installed on your system.
On some systems, CMake can be loaded with the Lmod module system (similar to how compilers and libraries can be loaded). If your system has CMake installed as a software module, then you can use a command such as
module load cmake/3.15
to load CMake into your computational environment. Check with your IT staff as to what the proper command would be on your system.
If your system doesn't already have Cmake installed, you can install it with Spack. See the Spack "Getting Started" guide to learn how to download and install Spack. Once you have Spack installed, you can issue a command such as
spack install email@example.com
where the %firstname.lastname@example.org indicates the compiler that you want to build CMake with.
Compiling GEOS-Chem "Classic" with CMake
Run directory contents
Each run directory that you create will contain these files and folders. (Some run directories for specialty simulations will contain additional files, which we will not describe here). This example is for the geosfp_4x5_standard simulation.
CodeDir@ getRunInfo* HISTORY.rc OutputDir/ download_data.py* HEMCO_Config.rc input.geos README GEOSChem.Restart.YYYYMMDD_hhmmz.nc4@ HEMCO_Diagn.rc Makefile* validate.pl*
- CodeDir is a symbolic link to the code directory that you specified when you created the run directory.
- Makefile is the run-directory Makefile. This controls the build sequence. The Makefile relies on the getRunInfo script to obtain necessary information.
- OutputDir is where diagnostic files will be placed.
- input.geos and the *.rc files are configuration files that allow you to specify settings for the GEOS-Chem simulation.
- download_data.py is the data download script for the GEOS-Chem dry-run simulation (available in 12.7.0 and later versions).
- validate.pl is only used for GEOS-Chem unit tests and difference tests. You can usually ignore this.
Earlier versions of GEOS-Chem might not have all of these files in the run directory. For example, the CodeDir symbolic link was only added in GEOS-Chem 12.3.0.
Create a build subfolder in your run directory
Once you have created a GEOS-Chem run directory, the next step is to create a CMake "build" directory in the run directory. The build directory is where CMake will create Makefiles that will be used to compile GEOS-Chem. You can name the build directory anything you want (we happen to like "gcbuild").
For our geosfp_4x5_standard example, type the following commands
cd geosfp_4x5_standard mkdir gcbuild ls
You should see a directory listing similar to:
CodeDir@ getRunInfo* input.geos validate.pl* download_data.py* HEMCO_Config.rc Makefile* gcbuild/ HEMCO_Diagn.rc OutputDir/ GEOSChem.Restart.YYYYMMDD_hhmmz.nc4@ HISTORY.rc README
Then switch to the gcbuild folder:
This is where you will configure and build GEOS-Chem.
Configure the build
Now that you are in the gcbuild folder, our first step in the GEOS-Chem compilation process is to configure the build. At this stage, CMake will determine if all necessary dependencies—such as a working compiler, necessary libraries, and other source code folders— are present. If CMake determines that one or more dependencies are missing, it will halt the build process. This has the advantage that the build will halt almost immediately upon error, instead of after several minutes.
Configuring with default options
If you wish to build GEOS-Chem for the geosfp_4x5_standard simulation with all default options on (aka "out-of-the-box"), type:
You will see the following output (assuming GEOS-Chem 12.7.0):
-- The Fortran compiler identification is GNU 9.2.0 -- Check for working Fortran compiler: /net/seasfs01/srv/export/jacob_lab/share_root/Lab/spack/opt/spack/.../bin/gfortran -- Check for working Fortran compiler: /net/seasfs01/srv/export/jacob_lab/share_root/Lab/spack/opt/spack/.../bin/gfortran -- works -- Detecting Fortran compiler ABI info -- Detecting Fortran compiler ABI info - done -- Checking whether /net/seasfs01/srv/export/jacob_lab/share_root/Lab/spack/opt/spack/.../bin/gfortran supports Fortran 90 -- Checking whether /net/seasfs01/srv/export/jacob_lab/share_root/Lab/spack/opt/spack/.../bin/gfortran supports Fortran 90 -- yes -- Found NetCDF: /net/seasfs01/srv/export/jacob_lab/share_root/Lab/spack/opt/spack/.../lib/libnetcdff.so -- GEOS-Chem @ 12.6.3-202-gd587905c -- Useful CMake variables: + CMAKE_PREFIX_PATH: /net/seasfs01/srv/export/jacob_lab/share_root/Lab/spack/opt/spack/... + CMAKE_BUILD_TYPE: Release -- Run directory setup: + RUNDIR: .. -- Bootstrapping .. -- Threading: * OMP: ON OFF -- Found OpenMP_Fortran: -fopenmp (found version "4.5") -- Found OpenMP: TRUE (found version "4.5") -- General settings: * MECH: Standard Tropchem SOA_SVPOA * BPCH_DIAG: ON OFF * TIMERS: ON OFF -- Components: * APM: ON OFF * RRTMG: ON OFF * GTMM: ON OFF * HCOSA: ON OFF * LUO_WETDEP: ON OFF -- Configuring done -- Generating done -- Build files have been written to: /path/to/geosfp_4x5_benchmark/gcbuild
NOTE: Some output has been truncated to fit in the wiki display window.
The output shows which options have been turned on and which have been turned off. Also you will note that the gcbuild folder now contains several subfolders, each of which contains Makefiles for the specific folders of the GEOS-Chem source code:
[gcbuild]$ ls APM/ cmake_install.cmake GTMM/ ISORROPIA/ NcdfUtil/ BaseTarget.txt GeosCore/ Headers/ KPP/ ObsPack/ CMakeCache.txt GeosRad/ HEMCO/ Makefile try_compile/ CMakeFiles/ GeosUtil/ History/ mod/
CMake will genearate the default compilation options for each run directory. For example, if we were in a geosfp_4x5_tropchem run directory, then the appropriate settings for this simulation would be selected. So you usually will not have to manually override any of the default options. But if you need to override any defaults, follow the commands in the next section.
Configuring with non-default options
If you wish to specify optional compile-time flags, they can be passed to CMake with the syntax -DOPTION=y, OPTION is the name of the option that you wish to activate. For example, if you wish to turn on the LUO_WETDEP option (in 12.7.0 and later), type:
cmake ../CodeDir -DLUO_WETDEP=y
and in the configuration output you will see that the LUO_WETDEP option has been changed from OFF to ON:
... above this line is all the same as the prior example... -- Components: * APM: ON OFF * RRTMG: ON OFF * GTMM: ON OFF * HCOSA: ON OFF * LUO_WETDEP: ON OFF
Configuring with debug options
If you wish to turn on all of the debugging options (BOUNDS=y, DEBUG=y FPEX=y) then you can call CMake with this option:
cmake ../CodeDir -DCMAKE_BUILD_TYPE=Debug
You will get similar output as above, but the configuration output will now show
+ CMAKE_BUILD_TYPE: Debug
Compiling the code
After the configuration step has been successfully completed, and while still in the gcbuild folder, type:
make -j4 install
to compile the code and copy the executable to the top-level run directory. CMake uses the Makefiles that were just created in the gcbuild folder by in the configuration stage.
NOTE: the -jN option will compile N files at a time. If you have 8 cores available to you, you can type make -j8 ..., etc.
During compilation, you will get output similar to this:
Scanning dependencies of target KPPFirstPass_Standard [ 1%] Building Fortran object KPP/Standard/CMakeFiles/KPPFirstPass_Standard.dir/gckpp_Monitor.F90.o [ 1%] Building Fortran object KPP/Standard/CMakeFiles/KPPFirstPass_Standard.dir/gckpp_Precision.F90.o Scanning dependencies of target Isorropia [ 1%] Building Fortran object ISORROPIA/CMakeFiles/Isorropia.dir/isorropiaII_main_mod.F.o [ 1%] Building Fortran object KPP/Standard/CMakeFiles/KPPFirstPass_Standard.dir/gckpp_Parameters.F90.o [ 1%] Linking Fortran static library libKPPFirstPass_Standard.a [ 1%] Built target KPPFirstPass_Standard Scanning dependencies of target Headers [ 1%] Building Fortran object Headers/CMakeFiles/Headers.dir/precision_mod.F.o [ 1%] Building Fortran object Headers/CMakeFiles/Headers.dir/charpak_mod.F90.o [ 3%] Building Fortran object Headers/CMakeFiles/Headers.dir/inquireMod.F90.o [ 3%] Building Fortran object Headers/CMakeFiles/Headers.dir/dictionary_m.F90.o [ 5%] Building Fortran object Headers/CMakeFiles/Headers.dir/CMN_O3_mod.F.o [ 5%] Building Fortran object Headers/CMakeFiles/Headers.dir/physconstants.F.o [ 7%] Building Fortran object Headers/CMakeFiles/Headers.dir/registry_params_mod.F90.o ... etc for all other subfolders of CodeDir... [ 98%] Building Fortran object GeosCore/CMakeFiles/GeosCore.dir/cleanup.F.o [ 98%] Linking Fortran static library libGeosCore.a [ 98%] Built target GeosCore Scanning dependencies of target geos [ 98%] Building Fortran object GeosCore/CMakeFiles/geos.dir/main.F.o [100%] Linking Fortran executable geos [100%] Built target geos Install the project... -- Install configuration: "Release" -- Installing: /path/to/geosfp_4x5_standard/geos
A progress bar at left shows you how far the build has progressed.
If the build halts with an error, you can simply type the same command, i.e.
make -j4 install
again after you have debugged and corrected the issue. The build process will pick up precisely where it left off when the error occurred.
Special arguments for newer CMake versions
If you are using a recent version (e.g. CMake 3.15) or later, then you do not necessarily need to change into the gcbuild folder before issuing the cmake and make commands. You call cmake and make with the following arguments:
cd geosfp_4x5_standard # Change to top-level run directory cmake -S CodeDir -B gcbuild # Configure make -C build -j4 install # Build the executable
- -S CodeDir points the cmake command to the source code directory
- -B gcbuild points the cmake command to the gcbuild folder (where makefiles were created)
- -C gcbuild points the make command to the gcbuild folder (where makefiles now reside)
If you are not sure if your version of CMake supports the -S and -B arguments, you can switch into the gcbuild folder before issuing the cmake and make commands. That will always work.
Compiling GCHP with CMake
GCHP 13.0.0 will be compatible with CMake. This version is slated to be released by May 2020 (or possibly sooner). We will update the documentation in the near future.
- 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