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

From Geos-chem
Jump to: navigation, search
(Second big change to CMake instructions)
(Redirected page to Compiling with CMake)
 
(29 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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]] as an option. By default, GNU Make is still used to compile GEOS-Chem but it will be removed eventually.
+
#REDIRECT [[Compiling with CMake]]
 
+
This documentation was written by [https://liambindle.ca/ 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 [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.
+
 
+
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>.
+
 
+
Below is an example <code>~/.bashrc</code> that sets up an environment for building GEOS-Chem with CMake.
+
<span style="color:Gray"># Picking the compiler I want to use</span>
+
<span style="color:MediumPurple">export</span> FC<span style="color:Crimson">=</span>gfortran
+
+
<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>
+
 
+
Don't forget to <code>source ~/.bashrc</code> 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. The CMake command also performs checks on your build environment to make sure the compilation is going to succeed. If it identifies any errors, such as missing dependencies or mismatched run directory and source code version numbers, CMake will tell you about the problem.
+
 
+
If you are new to CMake and would like a rundown of how to use the cmake 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.
+
 
+
Below are the steps for building GEOS-Chem with CMake.
+
 
+
===1. Navigate to your run directory ===
+
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/'''$
+
 
+
===2. Create a build directory and <code>cd</code> into it ===
+
This is where CMake and your compilers are going to put files. I am going to call mine <code>build/</code> but its 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 <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 pass it. Your CMake command's output contains information about how your build is configured. Read 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/'''$
+
 
+
===4. Configure your build (optional)===
+
Now that your build directory is initialized you can modify it with cmake commands of 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>", 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.
+
 
+
For example, to change the build type to "Debug" and disable multithreading you would do
+
cmake . -DOMP=OFF -DCMAKE_BUILD_TYPE=Debug
+
 
+
===5. Compile GEOS-Chem===
+
Now CMake has written build files to your build directory you can compile GEOS-Chem with <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/'''$
+
 
+
===6. Install the <code>geos</code> executable in your run directory===
+
Now that <code>geos</code> is built, install it to your run directory with <code>make install</code>.
+
'''~/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
+
<span style="color:Teal">Install the project...</span>
+
-- Install configuration: "Release"
+
-- Installing: ~/geosfp_2x25_complexSOA_SVPOA/geos
+
'''~/geosfp_2x25_complexSOA_SVPOA/build/'''$
+

Latest revision as of 15:17, 7 October 2020