Building GEOS-Chem with CMake
On this page we provide instructions for building GEOS-Chem with CMake. This feature has been added to GEOS-Chem 12.6.0 as an option. By default, GNU Make is still used to compile GEOS-Chem but will be removed in eventually. This documentation was written by Liam Bindle (Dalhousie).
- 1 Setting up
- 2 Building GCHP or GC-Classic
- 3 CMake FAQ
- 3.1 General
- 3.2 Building GEOS-Chem
- 3.2.1 Can I build GEOS-Chem Classic and GCHP in the same environment?
- 3.2.2 How do I build specific targets?
- 3.2.3 How do continue a build that was terminated before it finished?
- 3.2.4 How do I recompile after I make modifications to the source code?
- 3.2.5 How do I make clean?
- 3.2.6 How do I disable multithreading (i.e. OpenMP)?
- 3.2.7 How do I disable colorized output?
- 3.2.8 How do I increase the build's verbosity?
- 3.2.9 How do I build for debugging?
- 3.2.10 How do I clean my build's configuration (i.e. CMake's files)?
- 3.3 Advanced topics
Pick your compilers
FC environment variables define the programs that compile C, C++, and Fortran code. Set these to your preferred compilers in
~/.bashrc (or similar).
# Environment's compilers export FC=ifort export CC=icc # only required for GCHP export CXX=icpc # only required for GCHP
Note: For those that are familiar with MPI, these don't have to be your MPI's compiler wrappers.
Make sure your environment satisfies GEOS-Chem's requirements
The following are GC-Classics's requirements. Make sure the following libraries and software are available in your environment.
- CMake (version 3.5 or greater)
- NetCDF-C (version 4.0 or greater)
- NetCDF-Fortran (version 4.0 or greater)
The following are the additional requirements of GCHP.
- An MPI library (OpenMPI, MVAPICH2, MPICH, and SGI MPT).
- gFTL (version 1.0 or greater)
- ESMF (version 8.0 or greater)
- You can use the binaries from a previous GCHP build for this as long as that build's ESMF version is 8.0 or greater. Otherwise you'll have to install ESMF separately using their instructions.
Specify where GEOS-Chem's dependencies are installed
The easiest way to tell CMake where GEOS-Chem's dependencies are found is with the
gFTL_ROOT environment variables. Later, when you configure the build, CMake is going to search the paths you specify in these variables to find GEOS-Chem's dependencies' files. Multiple paths can be specified with a semicolon-separated list.
NetCDF_Fortran_ROOT are not required if
nc-config --prefix and
nf-config --prefix are available.
Set these variables in
~/.bashrc (or similar).
# Paths to dependencies export NetCDF_C_ROOT=/software/netcdf/4.6.1 # only required if nc-config is not available export NetCDF_Fortran_ROOT=/software/netcdf-fortran/4.4.4 # only required if nf-config is not available export ESMF_ROOT="/software/ESMF/8.0.0;/home/liam/ESMF/src" # only required for GCHP export gFTL_ROOT=/software/gFTL # only required for GCHP
ESMF_ROOT should be set to ESMF's install prefix and the path to the ESMF source code (which is
$ESMF_DIR in some environments).
In the snippet above,
/software/ESMF/8.0.0 is ESMF's install prefix and
/home/liam/ESMF/src is the path to the ESMF source code.
Expand this box for more info on
|Variable||Required for||Search files||Comments|
Reload your environment
~/> source ~/.bashrc
Building GCHP or GC-Classic
If you're new to CMake and would like a rundown of how to use the
cmake command, check out my tutorial.
Create a build directory in your run directory
In your GEOS-Chem run directory create a directory called
build and navigate to it.
~> cd ~/GC/rundirs/geosfp_4x5_standard ~/GC/rundirs/geosfp_4x5_standard/> mkdir build ~/GC/rundirs/geosfp_4x5_standard/> cd build
Initialize your build directory
In the build subdirectory, type the
cmake command and pass it the path to your GEOS-Chem source code.
~/GC/rundirs/geosfp_4x5_standard/build/> cmake ~/GC/Code.12.6.0
cmake . and review the status of your configuration. Read the output and check that the configuration finished (i.e. succeeded).
If you're building GC-Classic, your output should look similar to the following.
~/GC/rundirs/geosfp_4x5_standard/build/> cmake . -- GEOS-Chem version: 12.6.0 -- Useful CMake variables: + CMAKE_PREFIX_PATH: * CMAKE_BUILD_TYPE: [Release] Debug -- Run directory setup: + RUNDIR: .. -- Bootstrapping ~/rundirs/geosfp_4x5_standard/build/.. -- Threading: * OMP: [TRUE] FALSE -- General settings: * MECH: [Standard] Tropchem SOA_SVPOA * BPCH: [DIAG] [TIMESER] [TPBC] * PREC: REAL4 [REAL8] * TIMERS: TRUE [FALSE] -- Other components: * APM: TRUE [FALSE] * RRTMG: TRUE [FALSE] * GTMM: TRUE [FALSE] * HCOSA: TRUE [FALSE] -- Configuring done -- Generating done -- Build files have been written to: ~/GC/rundirs/geosfp_4x5_standard/build/
Compile the source code using the command
~/GC/rundirs/geosfp_4x5_standard/build/> make -j
-j argument tells
make that it can execute as many jobs as it wants simultaneously. This can eat up a lot of memory, so if you're running out of memory, you can restrict the number of simultaneous jobs by adding a number. 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
geos executable to your run directory
The final step is to copy the
geos executable in your run directory using:
~/GC/rundirs/geosfp_4x5_standard/build/> make install
What is CMake?
When will CMake support be available?
A GCHP version compatible with CMake should be available by the end of 2019. At that time, support for GNU Make will be retired. See the Compiling GCHP wiki page for more information.
What are the benefits of CMake?
- You environment is verified before you compile.
- Incremental compiling and a simpler build procedure.
- Fewer wasted HPC jobs due to failed builds.
What is incremental compiling?
What is an "out of source" build?
Can I build GEOS-Chem Classic and GCHP in the same environment?
How do I build specific targets?
make <target name>
How do continue a build that was terminated before it finished?
How do I recompile after I make modifications to the source code?
How do I
This cleans everything. Normally you don't need to do this. Rerunning
make with no arguments is usually what you want to do instead. See What is incremental compiling?
How do I disable multithreading (i.e. OpenMP)?
cmake -DOMP=FALSE .
How do I disable colorized output?
cmake -DCMAKE_COLOR_MAKEFILE=FALSE .
This disables colored output from CMake and the generated Makefiles.
How do I increase the build's verbosity?
cmake -DCMAKE_VERBOSE_MAKEFILE=TRUE .
This causes the generated Makefiles to print the compiler commands that get executed.
How do I build for debugging?
cmake -DCMAKE_BUILD_TYPE=Debug .
This causes the
How do I clean my build's configuration (i.e. CMake's files)?
rm -rf build mkdir build cd build
Can I use Ninja rather than GNU Make?
Yes. You'll need CMake version 3.7 or greater and Kitware's Ninja distribution (for Fortran futures). To use the Ninja generator rather than the Makefile generator, initialize your build directory with
cmake -GNinja <path to source code>.
Are the environment variables like
No, these are for convenience. You can configure the build with the standard
CMAKE_PREFIX_PATH variables, rather than environment variables, if you'd prefer. This means GEOS-Chem doesn't impose environment variable requirements on superprojects.