Difference between revisions of "Building GEOS-Chem with CMake"

From Geos-chem
Jump to: navigation, search
(Created page with "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, Co...")
 
(35 intermediate revisions by 2 users not shown)
Line 1: Line 1:
On this page we provide instructions for building GEOS-Chem with CMake. This feature has been added to [[GEOS-Chem 12#12.6.0|GEOS-Chem 12.6.0]] as an option. By default, [[Compiling_GEOS-Chem|GNU Make]] is still used to compile GEOS-Chem but will be removed in eventually. This documentation was written by [https://liambindle.ca/ Liam Bindle] (Dalhousie).
+
This page provides instructions for building GEOS-Chem with CMake. This feature was added in [[GEOS-Chem 12#12.6.0|GEOS-Chem 12.6.0]] (released 18 Oct 2019) 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 [http://fizz.phys.dal.ca/~atmos/wiki/index.php/Verification_of_the_CMake-based_build_system#dev.2F12.4.0 identical compiler commands] and [http://fizz.phys.dal.ca/~atmos/wiki/index.php/Verification_of_the_CMake-based_build_system#Quick_1-day_benchmark_comparison produce identical output].
  
== Setting up ==
+
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 [http://fizz.phys.dal.ca/~atmos/wiki/index.php/Building_GCHP_with_CMake_(draft) this].
  
=== Pick your compilers ===
+
This documentation was written by [https://liambindle.ca/ Liam Bindle] (Dalhousie).
  
The <code>CC</code>, <code>CXX</code>, and <code>FC</code> environment variables define the programs that compile C, C++, and Fortran code. Set these to your preferred compilers in <code>~/.bashrc</code> (or similar).  
+
== Before getting started ==
# Environment's compilers
+
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.
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.
+
== 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).
 +
'''~/'''$
  
=== Make sure your environment satisfies GEOS-Chem's requirements ===
+
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 [https://cmake.org/download/ 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 <code>FC</code>, <code>CC</code>, and <code>CXX</code> for Fortran, C, and C++ respectively. For GEOS-Chem Classic, only <code>FC</code> is required.
  
The following are GC-Classics's requirements. Make sure the following libraries and software are available in your environment.
+
Optionally, if the <code>nc-config</code> or <code>nf-config</code> executables are not available on your machine, you can set <code>NETCDF_ROOT</code>, <code>NETCDF_C_ROOT</code>, or <code>NETCDF_Fortran_ROOT</code> 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 <code>nc-config</code> and <code>nf-config</code>.
* [https://cmake.org/download/ CMake] (version 3.5 or greater)
+
* [https://www.unidata.ucar.edu/downloads/netcdf/index.jsp NetCDF-C] (version 4.0 or greater)
+
* [https://www.unidata.ucar.edu/downloads/netcdf/index.jsp NetCDF-Fortran] (version 4.0 or greater)
+
  
The following are the additional requirements of GCHP.
+
Below is an example <code>~/.bashrc</code> that sets up an environment for building GEOS-Chem with CMake.
* An MPI library ([https://www.open-mpi.org/software/ OpenMPI], [http://mvapich.cse.ohio-state.edu/downloads/ MVAPICH2], [https://www.mpich.org/downloads/ MPICH], and [https://downloads.linux.hpe.com/SDR/project/mpi/ SGI MPT]).
+
<span style="color:Gray"># Picking the compiler I want to use</span>
* [https://github.com/nasa/gFTL/releases gFTL] (version 1.0 or greater)
+
<span style="color:MediumPurple">export</span> FC<span style="color:Crimson">=</span>gfortran
* [https://www.earthsystemcog.org/projects/esmf/download/ 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.
+
<span style="color:Gray"># Misc environment variables</span>
 +
<span style="color:MediumPurple">export</span> NETCDF_C_ROOT<span style="color:Crimson">=</span>/usr/local/netcdf/4.6.1                    <span style="color:Gray"># only required if nc-config is not available</span>
 +
<span style="color:MediumPurple">export</span> NETCDF_Fortran_ROOT<span style="color:Crimson">=</span>/usr/local/netcdf-fortran/4.4.4      <span style="color:Gray"># only required if nf-config is not available</span>
  
=== Specify where GEOS-Chem's dependencies are installed ===
+
Don't forget to <code>source ~/.bashrc</code> after you modify it!
  
The easiest way to tell CMake where GEOS-Chem's dependencies are found is with the <code>NetCDF_C_ROOT</code>, <code>NetCDF_Fortran_ROOT</code>, <code>ESMF_ROOT</code> and <code>gFTL_ROOT</code> 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.
+
== Building GEOS-Chem ==
 +
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.
  
'''NOTE:''' <code>NetCDF_C_ROOT</code> and <code>NetCDF_Fortran_ROOT</code> are not required if <code>nc-config --prefix</code> and <code>nf-config --prefix</code> are available.
+
If you are new to CMake and would like a rundown of how to use the <code>cmake</code> command, check out [https://github.com/LiamBindle/An-Introduction-to-Using-CMake/wiki 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.
  
Set these variables in <code>~/.bashrc</code> (or similar).
+
Below are the steps for building GEOS-Chem with CMake.
# 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
+
  
'''NOTE''' <code>ESMF_ROOT</code> should be set to ESMF's install prefix ''and'' the path to the ESMF source code (which is <code>$ESMF_DIR</code> in some environments).
+
===1. Navigate to your run directory ===
In the snippet above, <code>/software/ESMF/8.0.0</code> is ESMF's install prefix and <code>/home/liam/ESMF/src</code> is the path to the ESMF source code.
+
My run directory is <code>~/geosfp_2x25_complexSOA_SVPOA</code> so I will <code>cd</code> there.
 +
'''~/'''$ cd ~/geosfp_2x25_complexSOA_SVPOA
 +
'''~/geosfp_2x25_complexSOA_SVPOA/'''$
  
<div class="toccolours mw-collapsible mw-collapsed">
+
===2. Create a build directory and <code>cd</code> into it ===
''Expand this box'' for more info on <code>NetCDF_C_ROOT</code>, <code>NetCDF_Fortran_ROOT</code>, <code>ESMF_ROOT</code> and <code>gFTL_ROOT</code>
+
Your build directory is where CMake and your compilers are going to put the files they generate. I am going to call mine <code>build/</code> but the name does not matter.
<div class="mw-collapsible-content">
+
'''~/geosfp_2x25_complexSOA_SVPOA/'''$ mkdir build
{| class="wikitable"
+
'''~/geosfp_2x25_complexSOA_SVPOA/'''$ cd build
|-
+
'''~/geosfp_2x25_complexSOA_SVPOA/build/'''$
! Variable
+
! Required for
+
! Search files
+
! Comments
+
|-
+
| <code>NetCDF_C_ROOT</code>
+
|
+
*GC&#8209;Classic
+
*GCHP
+
| <code>netcdf.h</code> <br> <code>libnetcdf.so</code>
+
|
+
*Not required if <code>nc-config --prefix</code> is available
+
|-
+
| <code>NetCDF_Fortran_ROOT</code>
+
|
+
*GC&#8209;Classic
+
*GCHP
+
| <code>netcdf.inc</code> <br> <code>netcdf.mod</code> <br> <code>libnetcdff.so</code>
+
|
+
*Not required if <code>nf-config --prefix</code> is available
+
|-
+
| <code>ESMF_ROOT</code>
+
|
+
*GCHP
+
| <code>ESMF_ErrReturnCodes.inc</code> <br> <code>ESMC.h</code> <br> <code>esmf.mod</code> <br> <code>libesmf.a</code>
+
|
+
*ESMF's <code>.inc</code> files don't get installed when you install ESMF. To remedy this, you have to set <code>ESMF_ROOT</code> to ESMF's install prefix AND the path to ESMF's source code. Separate the two paths with a semicolon (;).
+
*If you're using ESMF binaries from a different GCHP build, set <code>ESMF_ROOT</code> to the <code>ESMF/</code> subdirectory of the other GCHP's source code (you should see a subdirectory of <code>ESMF/</code> called <code>DEFAULTINSTALLDIR</code>). Only the one path is needed.
+
|-
+
| <code>gFTL_ROOT</code>
+
|
+
*GCHP
+
| <code>types/key_deferredLengthString.inc</code>
+
|
+
|}
+
</div>
+
</div>
+
  
=== Reload your environment ===
+
===3. Initialize your build directory===
~/> source ~/.bashrc
+
Run <code>cmake</code> and pass it the path to GEOS-Chem's source code. This initializes your build directory. My source code is in <code>~/geos-chem/12.6.0/</code> 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:          <span style="color:Green">ON</span>  OFF
 +
-- Found OpenMP_Fortran: -fopenmp (found version "4.5")
 +
-- Found OpenMP: TRUE (found version "4.5") 
 +
-- General settings:
 +
  * MECH:        Standard  Tropchem  <span style="color:Green">SOA_SVPOA</span>
 +
  * BPCH:        <span style="color:Green">DIAG  TIMESER  TPBC</span>
 +
  * TIMERS:      ON  <span style="color:Green">OFF</span>
 +
-- Components:
 +
  * APM:          ON  <span style="color:Green">OFF</span>
 +
  * RRTMG:        ON  <span style="color:Green">OFF</span>
 +
  * GTMM:        ON  <span style="color:Green">OFF</span>
 +
  * HCOSA:        ON  <span style="color:Green">OFF</span>
 +
-- 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!
  
== Building GCHP or GC-Classic ==
+
===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 "<code>.</code>" argument is necessary. It tells CMake that your current working directory (i.e. <code>.</code>) is your build directory. The output of <code>cmake</code> tells you about your build's configuration. Options are prefixed by a "<code>+</code>" or "<code>*</code>" in the output, 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.
  
If you're new to CMake and would like a rundown of how to use the <code>cmake</code> command, check out '''[https://github.com/LiamBindle/An-Introduction-to-Using-CMake/wiki my tutorial]'''.
+
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
  
=== Create a build directory in your run directory ===
+
===5. Compile GEOS-Chem===
 +
Now that CMake has written build files to your build directory you can compile GEOS-Chem with the command <code>make</code>.
 +
'''~/geosfp_2x25_complexSOA_SVPOA/build/'''$ make -j
 +
<b style="color:MediumSlateBlue">Scanning dependencies of target Isorropia</b>
 +
<b style="color:MediumSlateBlue">Scanning dependencies of target KPPFirstPass_SOA_SVPOA</b>
 +
[  1%] <span style="color:Green">Building Fortran object KPP/SOA_SVPOA/CMakeFiles/KPPFirstPass_SOA_SVPOA.dir/gckpp_Precision.F90.o</span>
 +
[  3%] <span style="color:Green">Building Fortran object ISORROPIA/CMakeFiles/Isorropia.dir/isorropiaII_main_mod.F.o</span>
 +
[  3%] <span style="color:Green">Building Fortran object KPP/SOA_SVPOA/CMakeFiles/KPPFirstPass_SOA_SVPOA.dir/gckpp_Parameters.F90.o</span>
 +
[  3%] <span style="color:Green">Building Fortran object KPP/SOA_SVPOA/CMakeFiles/KPPFirstPass_SOA_SVPOA.dir/gckpp_Monitor.F90.o</span>
 +
[  5%] <b style="color:LimeGreen">Linking Fortran static library libKPPFirstPass_SOA_SVPOA.a</b>
 +
[  5%] Built target KPPFirstPass_SOA_SVPOA
 +
<b style="color:MediumSlateBlue">Scanning dependencies of target Headers</b>
 +
[  6%] <span style="color:Green">Building Fortran object Headers/CMakeFiles/Headers.dir/inquireMod.F90.o</span>
 +
.
 +
.
 +
.
 +
[ 98%] <span style="color:Green">Building Fortran object GeosCore/CMakeFiles/geos.dir/main.F.o</span>
 +
[100%] <b style="color:LimeGreen">Linking Fortran executable geos</b>
 +
[100%] Built target geos
 +
'''~/geosfp_2x25_complexSOA_SVPOA/build/'''$
  
In your GEOS-Chem run directory create a directory called <code>build</code> and navigate to it.
+
Note that the <code>-j</code> argument tells <code>make</code> 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 <code>-j</code>. For example, to restrict the number of jobs to 4, you would do <code>make -j4</code>. If you don't want <code>make</code> to run simultaneous jobs, don't use the <code>-j</code> argument.
  
~> cd ~/GC/rundirs/geosfp_4x5_standard
+
===6. Install the <code>geos</code> executable in your run directory===
  ~/GC/rundirs/geosfp_4x5_standard/> mkdir build
+
Now that <code>geos</code> is built, install it to your run directory with <code>make install</code>.
  ~/GC/rundirs/geosfp_4x5_standard/> cd build
+
  '''~/geosfp_2x25_complexSOA_SVPOA/build/'''$ make install
</pre>
+
[  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
 +
<span style="color:Teal">Install the project...</span>
 +
  -- Install configuration: "Release"
 +
-- Installing: ~/geosfp_2x25_complexSOA_SVPOA/geos
 +
'''~/geosfp_2x25_complexSOA_SVPOA/build/'''$
  
=== Initialize your build directory ===
+
==Some final notes==
 +
Please refer to the [[CMake FAQ]] for more information on configuring and building GEOS-Chem with CMake.
  
In the build subdirectory, type the <code>cmake</code> command and pass it the path to your GEOS-Chem source code.
+
If you run into problems building GEOS-Chem with CMake or if you have any feedback, questions, or concerns, please [https://github.com/geoschem/geos-chem/issues/new/choose submit an issue on GitHub]! For bug reports, please be sure to include the <code>CMakeCache.txt</code> file in your build directory.
 
+
~/GC/rundirs/geosfp_4x5_standard/build/> cmake ~/GC/Code.12.6.0
+
 
+
Rerun with <code>cmake .</code> 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.
+
<pre>~/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/
+
</pre>
+
 
+
=== Compile ===
+
 
+
Compile the source code using the command
+
 
+
~/GC/rundirs/geosfp_4x5_standard/build/> make -j
+
 
+
'''NOTE:''' The <code>-j</code> argument tells <code>make</code> 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 <code>make -j4</code>. If you don't want <code>make</code> to run simultaneous jobs, don't use the <code>-j</code> argument.
+
 
+
=== Install the <code>geos</code> executable to your run directory ===
+
 
+
The final step is to copy the <code>geos</code> executable in your run directory using:
+
 
+
~/GC/rundirs/geosfp_4x5_standard/build/> make install
+
 
+
== CMake FAQ ==
+
 
+
=== General ===
+
 
+
==== What is CMake? ====
+
 
+
==== When will CMake support be available? ====
+
 
+
CMake is implemented as an option in [[GEOS-Chem 12#12.6.0|GEOS-Chem 12.6.0]]. It will eventually become the default, replacing [[Compiling_GEOS-Chem|GNU Make]].
+
 
+
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#CMake|''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? ====
+
 
+
=== Building GEOS-Chem ===
+
 
+
==== Can I build GEOS-Chem Classic and GCHP in the same environment? ====
+
Yes.
+
 
+
==== How do I build specific targets? ===
+
make <target name>
+
 
+
==== How do continue a build that was terminated before it finished? ====
+
make
+
 
+
==== How do I recompile after I make modifications to the source code? ====
+
make
+
 
+
==== How do I <code>make clean</code>? ====
+
make clean
+
This cleans ''everything''. Normally you don't need to do this. Rerunning <code>make</code> 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
+
 
+
=== Advanced topics ===
+
 
+
==== Can I use Ninja rather than GNU Make? ====
+
Yes. You'll need CMake version 3.7 or greater and [https://github.com/Kitware/ninja/releases Kitware's Ninja distribution] (for Fortran futures). To use the Ninja generator rather than the Makefile generator, initialize your build directory with <code>cmake -GNinja <path to source code></code>.
+
 
+
==== Are the environment variables like <code>FC</code> and <code>ESMF_ROOT</code> necessary? ====
+
No, these are for convenience. You can configure the build with the standard <code>CMAKE_C_COMPILER</code>, <code>CMAKE_CXX_COMPILER</code>, <code>CMAKE_Fortran_COMPILER</code>, and <code>CMAKE_PREFIX_PATH</code> variables, rather than environment variables, if you'd prefer. This means GEOS-Chem doesn't impose environment variable requirements on superprojects.
+
 
+
==== How do I build GEOS-Chem as a part of an other project? ====
+

Revision as of 15:00, 18 October 2019

This page provides instructions for building GEOS-Chem with CMake. This feature was added in GEOS-Chem 12.6.0 (released 18 Oct 2019) 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).

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 FC, CC, and CXX for Fortran, C, and C++ respectively. For GEOS-Chem Classic, only FC is required.

Optionally, if the nc-config or nf-config executables are not available on your machine, you can set NETCDF_ROOT, NETCDF_C_ROOT, or 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 nc-config and nf-config.

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!

Building GEOS-Chem

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.

1. Navigate to your run directory

My run directory is ~/geosfp_2x25_complexSOA_SVPOA so I will cd there.

~/$ 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

Run 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 "*" in the output, 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 make.

~/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 -j argument.

6. Install the geos executable in your run directory

Now that geos is built, install it to your run directory with make install.

~/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.