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

From Geos-chem
Jump to: navigation, search
(How do I make clean?)
(Redirected page to Compiling with CMake)
 
(32 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.
+
#REDIRECT [[Compiling with CMake]]
 
+
This documentation was written by [https://liambindle.ca/ Liam Bindle] (Dalhousie).
+
 
+
== Setting up ==
+
 
+
=== Pick your compilers ===
+
 
+
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).
+
# 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.
+
* [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.
+
* 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]).
+
* [https://github.com/nasa/gFTL/releases gFTL] (version 1.0 or greater)
+
* [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.
+
 
+
=== Specify where GEOS-Chem's dependencies are installed ===
+
 
+
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.
+
 
+
'''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.
+
 
+
Set these variables in <code>~/.bashrc</code> (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
+
 
+
'''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).
+
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.
+
 
+
<div class="toccolours mw-collapsible mw-collapsed">
+
''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>
+
<div class="mw-collapsible-content">
+
{| class="wikitable"
+
|-
+
! 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 ===
+
~/> source ~/.bashrc
+
 
+
 
+
== Building GCHP or GC-Classic ==
+
 
+
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]'''.
+
 
+
=== Create a build directory in your run directory ===
+
 
+
In your GEOS-Chem run directory create a directory called <code>build</code> 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 <code>cmake</code> command and pass it the path to your GEOS-Chem source code.
+
 
+
~/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 [[Building_GEOS-Chem_with_CMake#What_is_incremental_compiling.3F|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? ====
+

Latest revision as of 15:17, 7 October 2020