Difference between revisions of "Building GEOS-Chem with CMake"
(→= How do I build specific targets?) |
|||
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). | + | 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). | ||
== Setting up == | == Setting up == |
Revision as of 13:28, 20 August 2019
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).
Contents
- 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
Setting up
Pick your compilers
The CC
, CXX
, and 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 NetCDF_C_ROOT
, NetCDF_Fortran_ROOT
, ESMF_ROOT
and 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.
NOTE: NetCDF_C_ROOT
and 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
NOTE 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 NetCDF_C_ROOT
, NetCDF_Fortran_ROOT
, ESMF_ROOT
and gFTL_ROOT
Variable | Required for | Search files | Comments |
---|---|---|---|
NetCDF_C_ROOT
|
|
netcdf.h libnetcdf.so
|
|
NetCDF_Fortran_ROOT
|
|
netcdf.inc netcdf.mod libnetcdff.so
|
|
ESMF_ROOT
|
|
ESMF_ErrReturnCodes.inc ESMC.h esmf.mod libesmf.a
|
|
gFTL_ROOT
|
|
types/key_deferredLengthString.inc
|
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
</pre>
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
Rerun with 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
Compile the source code using the command
~/GC/rundirs/geosfp_4x5_standard/build/> make -j
NOTE: The -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 -j
argument.
Install 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
CMake FAQ
General
What is CMake?
When will CMake support be available?
CMake is implemented as an option in GEOS-Chem 12.6.0. It will eventually become the default, replacing 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 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 make clean
?
make clean
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
Advanced topics
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 FC
and ESMF_ROOT
necessary?
No, these are for convenience. You can configure the build with the standard CMAKE_C_COMPILER
, CMAKE_CXX_COMPILER
, CMAKE_Fortran_COMPILER
, and CMAKE_PREFIX_PATH
variables, rather than environment variables, if you'd prefer. This means GEOS-Chem doesn't impose environment variable requirements on superprojects.