Compiling with CMake

From Geos-chem
Jump to: navigation, search

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Configuring your computational environment
  3. Downloading source code
  4. Downloading data directories
  5. Creating run directories
  6. Configuring runs
  7. Compiling GEOS-Chem
  8. Running
  9. Output files
  10. Visualizing and processing output
  11. Coding and debugging
  12. Further reading


Overview

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.

Obtaining 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 cmake%gcc@9.2.0

where the %gcc@9.2.0 indicates the compiler that you want to build CMake with.

--Bob Yantosca (talk) 19:58, 20 December 2019 (UTC)

Compiling GEOS-Chem "Classic" with CMake

In this section, we list the steps that are needed to compile GEOS-Chem 12.6.0 and later versions with CMake. If you are using an older GEOS-Chem version, please see our Compiling with GNU Make page.

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*
  1. CodeDir is a symbolic link to the code directory that you specified when you created the run directory.
  2. Makefile is the run-directory Makefile. This controls the build sequence. The Makefile relies on the getRunInfo script to obtain necessary information.
  3. OutputDir is where diagnostic files will be placed.
  4. input.geos and the *.rc files are configuration files that allow you to specify settings for the GEOS-Chem simulation.
  5. download_data.py is the data download script for the GEOS-Chem dry-run simulation (available in 12.7.0 and later versions).
  6. 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:

cd gcbuild

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:

cmake ../CodeDir

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

--Bob Yantosca (talk) 15:56, 3 January 2020 (UTC)

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.

--Bob Yantosca (talk) 16:25, 2 January 2020 (UTC)

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

where

  1. -S CodeDir points the cmake command to the source code directory
  2. -B gcbuild points the cmake command to the gcbuild folder (where makefiles were created)
  3. -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.

--Bob Yantosca (talk) 21:19, 20 December 2019 (UTC)

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.

--Bob Yantosca (talk) 20:59, 20 December 2019 (UTC)

Further reading

  1. CMake FAQ by Liam Bindle
  2. CMake tutorial (cmake.org)
  3. Learn X in Y minutes (where X is CMake)
  4. GEOS-Chem coding and debugging
  5. Guide to GEOS-Chem error messages



Previous | Next | Getting Started with GEOS-Chem