Building GEOS-Chem with CMake
This page provides instructions for building GEOS-Chem with CMake. This feature was added in GEOS-Chem 12.6.0 as an option. The old GNU Makefiles are still the default approach for building GEOS-Chem, but eventually they will be retired in favor of CMake. Both build systems build GEOS-Chem with identical compiler commands and produce identical output.
GCHP's CMake support is in the final stages of testing. This is expected to be completed by the end of 2019. Building GCHP with CMake is very similar to building GEOS-Chem Classic with CMake. The only difference is that there are a few more software requirements. For a sneek peak, see this.
This documentation was written by Liam Bindle (Dalhousie).
- 1 Before getting started
- 2 Check if CMake is installed on your machine
- 3 Set up the new GEOS-Chem build environment
- 4 Building GEOS-Chem
- 5 Some final notes
Before getting started
Before going through these instructions you should (1) have a run directory and (2) download the GEOS-Chem source code. You can use an existing run directory, provided its version matches your source code's version. Refer to Getting Started with GEOS-Chem for instructions on creating a run directory and downloading the GEOS-Chem source code.
Check if CMake is installed on your machine
The only new software requirement for building GEOS-Chem with CMake is CMake version 3.5 or greater. CMake is popular utility, and it might already be installed on your system. You can check what version of CMake (if any) is installed on your machine with
~/$ cmake --version cmake version 3.10.2 CMake suite maintained and supported by Kitware (kitware.com/cmake). ~/$
If CMake is not installed on your system or its version is less than 3.5, contact your system administator or download the latest version here.
Set up the new GEOS-Chem build environment
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
CXX for Fortran, C, and C++ respectively. For GEOS-Chem Classic, only
FC is required.
Optionally, if the
nf-config executables are not available on your machine, you can set
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
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!
You should think of CMake as an interactive tool for configuring GEOS-Chem's build. For example, compile-time options like enabling timers, disabling multithreading, and turning on components like 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.
My run directory is
~/geosfp_2x25_complexSOA_SVPOA so I will
~/$ cd ~/geosfp_2x25_complexSOA_SVPOA ~/geosfp_2x25_complexSOA_SVPOA/$
2. Create a build directory and
cd into it
Your build directory is where CMake and your compilers are going to put the files they generate. I am going to call mine
build/ but the name does not matter.
~/geosfp_2x25_complexSOA_SVPOA/$ mkdir build ~/geosfp_2x25_complexSOA_SVPOA/$ cd build ~/geosfp_2x25_complexSOA_SVPOA/build/$
3. Initialize your build directory
cmake and pass it the path to GEOS-Chem's source code. This initializes your build directory. My source code is in
~/geos-chem/12.6.0/ so that is what I will pass it.
~/geosfp_2x25_complexSOA_SVPOA/build/$ cmake ~/geos-chem/12.6.0 -- The Fortran compiler identification is GNU 7.4.0 -- Check for working Fortran compiler: /usr/bin/gfortran -- Check for working Fortran compiler: /usr/bin/gfortran -- works -- Detecting Fortran compiler ABI info -- Detecting Fortran compiler ABI info - done -- Checking whether /usr/bin/gfortran supports Fortran 90 -- Checking whether /usr/bin/gfortran supports Fortran 90 -- yes -- Found NetCDF: /usr/local/netcdf-fortran/4.4.4/lib/libnetcdff.so -- GEOS-Chem @ 12.6.0 -- Useful CMake variables: + CMAKE_PREFIX_PATH: + 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 TIMESER TPBC * TIMERS: ON OFF -- Components: * APM: ON OFF * RRTMG: ON OFF * GTMM: ON OFF * HCOSA: ON OFF -- Configuring done -- Generating done -- Build files have been written to: ~/geosfp_2x25_complexSOA_SVPOA/build ~/geosfp_2x25_complexSOA_SVPOA/build/$
Your CMake command's output contains important information about your build's configuration. Make sure to read it!
4. Configure your build (optional)
Now that your build directory is initialized, you can modify your build's configuration with CMake commands with the form
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 "
*" 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.
As an example, if you wanted to build GEOS-Chem for debugging with multithreading disabled, you would do
cmake . -DOMP=OFF -DCMAKE_BUILD_TYPE=Debug
5. Compile GEOS-Chem
Now that CMake has written build files to your build directory you can compile GEOS-Chem with the command
~/geosfp_2x25_complexSOA_SVPOA/build/$ make -j Scanning dependencies of target Isorropia Scanning dependencies of target KPPFirstPass_SOA_SVPOA [ 1%] Building Fortran object KPP/SOA_SVPOA/CMakeFiles/KPPFirstPass_SOA_SVPOA.dir/gckpp_Precision.F90.o [ 3%] Building Fortran object ISORROPIA/CMakeFiles/Isorropia.dir/isorropiaII_main_mod.F.o [ 3%] Building Fortran object KPP/SOA_SVPOA/CMakeFiles/KPPFirstPass_SOA_SVPOA.dir/gckpp_Parameters.F90.o [ 3%] Building Fortran object KPP/SOA_SVPOA/CMakeFiles/KPPFirstPass_SOA_SVPOA.dir/gckpp_Monitor.F90.o [ 5%] Linking Fortran static library libKPPFirstPass_SOA_SVPOA.a [ 5%] Built target KPPFirstPass_SOA_SVPOA Scanning dependencies of target Headers [ 6%] Building Fortran object Headers/CMakeFiles/Headers.dir/inquireMod.F90.o . . . [ 98%] Building Fortran object GeosCore/CMakeFiles/geos.dir/main.F.o [100%] Linking Fortran executable geos [100%] Built target geos ~/geosfp_2x25_complexSOA_SVPOA/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
6. Install the
geos executable in your run directory
geos is built, install it to your run directory with
~/geosfp_2x25_complexSOA_SVPOA/build/$ make install [ 3%] Built target KPPFirstPass_SOA_SVPOA [ 11%] Built target Headers [ 11%] Built target JulDay [ 16%] Built target NcdfUtil [ 23%] Built target GeosUtil [ 27%] Built target Transport [ 32%] Built target KPP_SOA_SVPOA [ 35%] Built target History [ 37%] Built target ObsPack [ 52%] Built target HCO [ 61%] Built target HCOX [ 62%] Built target HCOI [ 64%] Built target Isorropia [ 98%] Built target GeosCore [100%] Built target geos Install the project... -- Install configuration: "Release" -- Installing: ~/geosfp_2x25_complexSOA_SVPOA/geos ~/geosfp_2x25_complexSOA_SVPOA/build/$
Some final notes
Please refer to the CMake FAQ for more information on configuring and building GEOS-Chem with CMake.
If you run into problems building GEOS-Chem with CMake or if you have any feedback, questions, or concerns, please submit an issue on GitHub! For bug reports, please be sure to include the
CMakeCache.txt file in your build directory.