Compiling GCHP

Note

This user guide assumes you have loaded a computing environment that satisfies GCHP’s software requirements.

Note

Another useful resource for GCHP build instructions is our YouTube tutorial.

There are two steps to build GCHP. The first step is configuring your build. To configure your build you use cmake to configure build settings. Build settings cover options like enabling or disabling components like RRTMG, specifying run directories to install GCHP to, or whether GCHP should be compiled in Debug mode.

The second step is compiling. To compile GCHP you use make. This compiles GCHP according to your configuration from the first step.

Create a build directory

Create a build directory. This directory is going to be the working directory for your build. The configuration and compile steps generate a bunch of build files, and this directory is going to store those. You can think of a build directory as representing a GCHP build. It stores configuration settings, information about your system, and intermediate files from the compiler.

A build directory is self contained, so you can delete it at any point to erase the build and its configuration. You can have as many build directories as you would like. Most users only need one build directory, since they only build GCHP once; but, for example, if you were building GCHP with Intel and GNU compilers to compare performance, you would have two build directories: one for the Intel build, and one for the GNU build. You can name your build directories whatever you want, but a good choice is build/. There is one rule for build directories: a build directory should be a new directory.

Create a build directory and initialize it. You initialize a build directory by running cmake with the path to the GCHP source code. Here is an example of creating a build directory in the top-level of the GCHP source code:

gcuser:~$ cd ~/GCHP.Code
gcuser:~/GCHP.Code$ mkdir build                # create the build dir
gcuser:~/Code.GCHP$ cd build
gcuser:~/Code.GCHP/build$ cmake ~/Code.GCHP    # initialize the build
-- The Fortran compiler identification is GNU 9.2.1
-- The CXX compiler identification is GNU 9.2.1
-- The C compiler identification is GNU 9.2.1
-- Check for working Fortran compiler: /usr/bin/f95
-- Check for working Fortran compiler: /usr/bin/f95  -- works
...
-- Configuring done
-- Generating done
-- Build files have been written to: /src/build
gcuser:~/Code.GCHP/build$

Note

If you get a CMake error saying “Could not find XXXX” (where XXXX is a dependency like ESMF, NetCDF, HDF5, etc.), the problem is that CMake can’t automatically find where that library is installed on your system. You can add custom paths to CMake’s default list of search paths with the CMAKE_PREFIX_PATH variable.

For example, if you got an error saying “Could not find ESMF”, and ESMF were installed at /software/ESMF, you would do

gcuser:~/Code.GCHP/build$ cmake . -DCMAKE_PREFIX_PATH=/software/ESMF

See the next section for details on setting build variables like CMAKE_PREFIX_PATH.

Configure your build

Build settings are controlled by cmake commands with the following form:

$ cmake . -D<NAME>="<VALUE>"

where <NAME> is the name of the setting, and <VALUE> is the value that you are assigning it. These settings are persistent and saved in your build directory. You can set multiple variables in a single command, and you can run cmake as many times as you need to configure your desired settings.

Note

The . argument is important. It is the path to your build directory which is . here.

GCHP has no required build settings. You can find the complete list of GCHP’s build settings here. The most frequently used build setting is RUNDIR which lets you specify one or more run directories to install GCHP to. Here, “install” refers to copying the compiled executable, and some supplemental files with build settings, to your run directories.

Note

You can even update build settings after you compile GCHP. Simply rerun make and (optionally) make install, and the build system will automatically figure out what needs to be recompiled.

Since there are no required build settings, for this tutorial we will stick with the default settings.

You should notice that when you run cmake it ends with:

...
-- Configuring done
-- Generating done
-- Build files have been written to: /src/build

This tells you the configuration was successful, and that you are ready to compile.

Compile GCHP

You compile GCHP with:

gcuser:~/Code.GCHP/build$ make -j   # -j enables compiling in parallel

Optionally, you can use the VERBOSE=1 argument to see the compiler commands.

This step creates ./bin/gchp which is the compiled executable. You can copy this executable to your run directory manually, or you can do

gcuser:~/Code.GCHP/build$ make install

which copies ./bin/gchp (and some supplemental files) to the run directories specified in RUNDIR.

Now you have compiled GCHP, and you are ready to move on to creating a run directory!

---

Recompiling

You need to recompile GCHP if you update a build setting or make a modification to the source code. However, with CMake, you don’t need to clean before recompiling. The build system automatically figure out which files need to be recompiled based on your modification. This is known as incremental compiling.

To recompile GCHP, simply do

gcuser:~/Code.GCHP/build$ make -j   # -j enables compiling in parallel

and optionally, do make install.

---

GCHP build options

These are persistent build setting that are set with cmake commands with the following form

$ cmake . -D<NAME>="<VALUE>"

where <NAME> is the name of the build setting, and <VALUE> is the value you are assigning it. Below is the list of build settings for GCHP.

RUNDIR

Paths to run directories where make install installs GCHP. 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.

CMAKE_BUILD_TYPE

The build type. Valid values are Release, Debug, and RelWithDebInfo. Set this to Debug if you want to build in debug mode.

CMAKE_PREFIX_PATH

One or more directories that are searched for external libraries like NetCDF or MPI. You can specify multiple paths with a semicolon separated list.

GEOSChem_Fortran_FLAGS_<COMPILER_ID>

Compiler options for GEOS-Chem for all build types. Valid values for <COMPILER_ID> are GNU and Intel.

GEOSChem_Fortran_FLAGS_<BUILD_TYPE>_<COMPILER_ID>

Additional compiler options for GEOS-Chem for build type <BUILD_TYPE>.

HEMCO_Fortran_FLAGS_<COMPILER_ID>

Same as GEOSChem_Fortran_FLAGS_<COMPILER_ID>, but for HEMCO.

HEMCO_Fortran_FLAGS_<BUILD_TYPE>_<COMPILER_ID>

Same as GEOSChem_Fortran_FLAGS_<BUILD_TYPE>_<COMPILER_ID>, but for HEMCO.

RRTMG

Switch to enable/disable the RRTMG component.

OMP

Switch to enable/disable OpenMP multithreading. As is standard in CMake (see if documentation) valid values are ON, YES, Y, TRUE, or 1 (case-insensitive) and valid false values are their opposites.

INSTALLCOPY

Similar to RUNDIR, except the directories do not need to be run directories.