|
|
(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‑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‑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? ====
| + | |