Difference between revisions of "Compiling GCHP"

From Geos-chem
Jump to: navigation, search
(Compilation Basics)
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''''[[Setting Up the GCHP Environment|Previous]] | [[Running_GCHP:_Basics|Next]] | [[Getting Started With GCHP]] | [[GCHP Main Page]]'''''
+
'''''[[Downloading_GCHP|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''
 
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
 
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
 +
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 
#[[Downloading_GCHP|Downloading Source Code and Data Directories]]
 
#[[Downloading_GCHP|Downloading Source Code and Data Directories]]
 +
#<span style="color:blue">'''Compiling'''</span>
 
#[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]]
 
#[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]]
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 
#<span style="color:blue">'''Compiling'''</span>
 
 
#[[Running_GCHP:_Basics|Running GCHP: Basics]]
 
#[[Running_GCHP:_Basics|Running GCHP: Basics]]
 
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
 
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
Line 12: Line 12:
 
<br>
 
<br>
  
== Overview ==
+
Compiling GCHP is the same procedure as compiling GEOS-Chem Classic. Please see [http://wiki.seas.harvard.edu/geos-chem/index.php/Compiling_with_CMake Compiling with CMake] for instructions.
 
+
First time compilation can take 30 minutes or more because it requires building large modules from scratch, including [https://www.earthsystemcog.org/projects/esmf/ ESMF], [https://geos5.org/wiki/index.php?title=MAPL_software MAPL], [https://www.gfdl.noaa.gov/fv3/ FV3 dycore advection], and GEOS-Chem. ESMF (Earth System Modeling Framework) provides core infrastructure to GCHP while MAPL (Modeling, Analysis and Prediction Layer) serves as a layer between GEOS-Chem and ESMF. Both ESMF and MAPL have significant compilation times but generally do not need to be recompiled unless parts of their code have been modified which is usually not necessary. Subsequent compile times will therefore be significantly shorter if you skip recompiling them, on the same order of magnitude as compiling GEOS-Chem Classic. Even if you do need to recompile them, you can greatly speed up recompilation by not cleaning first.
+
 
+
This page provides instructions on how to clean and compile GCHP. There are several options for cleaning and compiling which allow selectively cleaning and compiling modules within GCHP, thereby minimizing recompilation time. This is a very big time-saver so please pay attention to the information presented on this page. You can also always see all build options from the command line, along with tips on which option is most appropriate for your use case, by typing <code>make</code> or <code>make help</code> within your run directory.
+
 
+
If you run into problems compiling GCHP and cannot figure out why, please create an issue on the GCHP issue tracker located at [https://github.com/geoschem/gchp/issues https://github.com/geoschem/gchp/issues].
+
 
+
== Compilation Basics ==
+
 
+
The GCHP run directory <tt>Makefile</tt> contains several options for cleaning and compiling source code, as well as utility options you might find useful. Options are printed out by typing the following at the command line:
+
 
+
make help
+
 
+
It is important that you do this and browse the options available. Knowing which build options to use based on what you changed in the model or your libraries is important for saving yourself time. In addition, several make options extend beyond cleaning and compiling, such as cleaning up files in your run directory and displaying the status of your source code. If you have already created a run directory, try typing <code>make help</code> on the command line from within the run directory and scan through the output. Do this often until you feel confident in your recall of the make options available.
+
 
+
=== Initial Compile ===
+
 
+
To compile GCHP from scratch, including ESMF, MAPL, FV3 advection, and GEOS-Chem core files, navigate to your run directory. Then type the followng:
+
 
+
make clean_all
+
make build_all
+
 
+
When you first download source code the directories will already be clean, so doing <code>make clean_all</code> technically is not necessary. However, it is recommended to be in the habit of including clean for fresh builds. It will also be necessary if you change compiler or other libraries and want to rebuild GCHP source code.
+
 
+
All build information is sent to both the terminal window and to a log file called <code>compile.log</code>. Git information for source code at compile time are recorded at the end of the compilation log file.
+
 
+
Upon successful compilation, the following empty files are created in your GCHP source code directories:
+
* <tt>GCHP/ESMF/esmf.install</tt>
+
* <tt>GCHP/Shared/mapl.install</tt>
+
* <tt>GCHP/FVdycoreCubed_GridComp/fvdycore.install</tt>
+
 
+
These files indicate successful compilation per module. If you are ever uncertain on whether your ESMF, MAPL, and FV3 dycore were previously built, check if these files exist.
+
 
+
=== Recompile ===
+
 
+
For subsequent GCHP compilations you have several options. Choosing the most appropriate option based on what you changed can save you a lot of time. You can remind yourself of all options by typing <code>make</code> or <code>make help</code> at the command prompt. Here is a brief summary of the primary build options. Please note that none of these commands clean the source code prior to compiling, meaning none of the previously generated binaries are deleted. This makes recompile time much faster since only the Fortran files that changed are recompiled and and have new binaries created.
+
 
+
make build_all  # Compile all source code (slow)
+
make build_mapl # Compile MAPL, FV3, and GEOS-Chem/GCHP core files (skips ESMF)
+
make build_core # Compile GEOS-Chem/GCHP core files only (fast)
+
 
+
You can also do any of the above with GEOS-Chem debug flags turned on. Note that this will come with a performance penalty during your runs so you should only do this for debugging. The make command to do this is the same as above but with '_debug' appended to the target. For example:
+
 
+
make build_core_debug
+
 
+
=== Examples ===
+
 
+
Example workflows for GEOS-Chem development that makes use of several build options are listed below.
+
 
+
'''''Create a run directory and compile from scratch'''''
+
#make clean_all; make build_all (compile from scratch)
+
#Verify successful compilation based on compilation message at end
+
 
+
'''''Edit .F or .F90 file in GEOS-Chem GeosCore'''''
+
#make build_core_debug (recompile without cleaning, skip ESMF, MAPL, and FV3, and turn GEOS-Chem debug flags on)
+
#Verify successful compilation based on compilation message at end
+
 
+
'''''Edit high-level GCHP .F90 file in the GCHP run directory, e.g. gigc_chunk_mod.F90'''''
+
#make build_core_debug (recompile without cleaning, and skip ESMF, MAPL, and FV3, and turn GEOS-Chem debug flags on)
+
#Verify successful compilation based on compilation message at end
+
 
+
'''''Edit a high-level GCHP header file, e.g. Includes_Before_Run.H'''''
+
#make clean_core; make build_core (clean and recompile GEOS-Chem/GCHP core files; cleaning is required so that the Fortran file that includes the header file is recompiled even though it did not change)
+
#Verify successful compilation based on compilation message at end
+
 
+
'''''Edit a MAPL file such as GCHP/Shared/MAPL_Base/MAPL_ExtDataGridCompMod.F90'''''
+
#make build_mapl (recompile MAPL without cleaning)
+
#Verify successful build by opening <code>compile.log</code>, searching for string 'making install', and inspecting text above all instances of it.
+
 
+
If you find yourself editing files in the <code>GCHP/Shared</code>, <code>GCHP/Registry</code>, or <code>FVdycoreCubed_GridComp</code> folders then you will need to recompile with option <code>make build_mapl</code>. Editing these files is advanced. If you are attempting to fix a MAPL error that appears during run-time you may be headed in the wrong direction since most MAPL errors are caused by bad configuration in the run directory. If you are unsure of what you are doing please create a [https://github.com/geoschem/gchp/issues GitHub GCHP issue] and we will respond. Even if your question is not a true issue, having it on the GitHub issue tracker allows sharing the question and answer with the wider GCHP community, something we strongly encourage.
+
 
+
== Compilation Tips ==
+
 
+
=== First-time compilation ===
+
 
+
If a GCHP executable exists in the GEOS-Chem bin/ folder then you will see the following message at the end of compilation:
+
 
+
###################################
+
### GCHP compiled successfully! ###
+
###################################
+
 
+
If you did a clean compile of your code and you see this message then you know that GCHP compiled without error. Compiler output, including warnings and error messages, will be stored in a log file called <tt>compile.log</tt>. If you inspect your log file or watch the compile output real-time, you will notice that there are many warnings and some error messages. These errors are due to leftover components in MAPL which are no longer used but which still try to compile. As long as the compilation continues and shows the successful completion message at the end then these errors can be ignored.
+
 
+
If your first compilation results in an error then you will see a message that the executable does not exist. If this happens then open your <tt>compile.log</tt> text file and search for the first encountered error which may be much earlier in the file. The easiest way to do this is to search for string "making install" and looking over the lines directly above it. This checks the end of the compile log for each of the MAPL sub-components. An error in any one of the sub-components will result in proceeding to the next sub-component rather than stopping compilation. The build will not crash until later when a built file is not found, often during compilation of FV3 advection.
+
 
+
=== Recompilation ===
+
 
+
If you are recompiling MAPL, meaning you did not clean the source code before compiling, then the successful compilation message does not necessarily mean your changes successfully compiled. This is because failure during compilation of different MAPL sub-components does not trigger the entire build to fail. It will continue and the old binary files for whatever component failed will be used instead. Only if you cleaned first and those files were deleted would the end result be a build failure.
+
 
+
The general rule-of-thumb is if you clean and then compile, or if you rebuild only GEOS-Chem core (<tt>make build_core</tt>), then you can trust the "GCHP compiled successfully!" message. However, if you recompile using <tt>make build_mapl</tt> without cleaning first, then you will need to dig a little deeper to ensure a successful rebuild. The best way to do this is to do keyword search for "making install" in <tt>compile.log</tt> and scan the few lines directly above all instances of it. If there was a problem with MAPL compilation you will spot it immediately in one of these areas, and that is where you should look for clues on how to fix it.
+
 
+
If you plan on developing within MAPL please make sure you fully understand this approach to debugging since it will save you a lot of time and frustration. Repeat: if you are developing MAPL and recompiling be aware you need to check your <tt>compile.log</tt> for keyword "making install" to ensure success. This can be avoided by cleaning MAPL before recompiling with <tt>make clean_mapl</tt>. However, recompiling without cleaning will make your workflow much faster so it is worth doing this is possible.
+
 
+
=== General tips ===
+
 
+
Here are strategies that typically hone in immediately on the original MAPL compilation error:
+
 
+
# Search for string "making install" in <tt>compile.log</tt>, and look at the lines immediately above all results of your keyword search.
+
# A second and more tedious option is to search for string "error". Ignore results where error is in a filename or in a source code string that triggered a warning.
+
# If in doubt, check the source code directory to see the file times. If the binary for the file you updated is older than the other binaries then it encountered a compile error in your update.
+
 
+
Why is this necessary? It is because MAPL will continue to compile even if a compile error occurs. MAPL compilation involves compiling a series of components, many of them dependent on components that came before, and compilation rules are relaxed to allow minor problems. One component may fail compilation but the compilation will not crash until the built file is needed later on in the build sequence. It is therefore necessary to search your log file for errors high above the final error in the event of compile failure. The log file will be long so this should be done by keyword search.
+
 
+
== Advanced Topics ==
+
 
+
=== GNU Makefiles ===
+
 
+
The <tt>Makefile</tt> in the run directory invokes a bash shell script called <tt>build.sh</tt> that includes changing into the source code directory and invoking source code GNU Makefiles. At its core, building GCHP simply requires the inclusion of additional make target <tt>HPC=yes</tt> if cleaning and <tt>hpc</tt> if compiling when invoking make in the GEOS-Chem repository. Cleaning GCHP also requires changing into the GCHP directory explicitly to clean ESMF, MAPL, and FV3 dycore.
+
 
+
If you are interested in seeing the core <tt>make</tt> commands used for all options provided in the run directory <tt>Makefile</tt>, see the commands defined in <tt>build.sh</tt>. You can then trace the build sequence by looking at the Makefiles in the GEOS-Chem and GCHP repositories. Note that calling <tt>make</tt> always invokes the <tt>Makefile</tt> in the directory you are in and changing into the GEOS-Chem and GCHP source code directories occurs within <tt>build.sh</tt>.
+
 
+
If you are interested in the build sequence and settings for MAPL, look at *.mk files in <tt>GCHP/Shared/Config</tt>, particularly <tt>ESMA_base.mk</tt>, <tt>ESMA_arch.mk</tt>, and <tt>GMAO_base.mk</tt>, as well as <tt>GNUMakefile</tt> within <tt>GCHP/Shared</tt> and all its subdirectories. Also see <tt>GIGC.mk</tt> in the highest level of the GCHP repository for the include dependencies between GCHP modules.
+
 
+
=== CMake ===
+
 
+
Currently GCHP cannot be built with CMake. However, we anticipate release of a GCHP version compatible with CMake by the end of 2019. Support for GNU Make will eventually be retired.
+
  
 
--------------------------------------
 
--------------------------------------
  
'''''[[Setting Up the GCHP Environment|Previous]] | [[Running_GCHP:_Basics|Next]] | [[Getting Started With GCHP]] | [[GCHP Main Page]]'''''
+
'''''[[Downloading_GCHP|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''

Revision as of 23:53, 9 November 2020

Previous | Next | Getting Started with GCHP | GCHP Main Page

  1. Hardware and Software Requirements
  2. Setting Up the GCHP Environment
  3. Downloading Source Code and Data Directories
  4. Compiling
  5. Obtaining a Run Directory
  6. Running GCHP: Basics
  7. Running GCHP: Configuration
  8. Output Data
  9. Developing GCHP
  10. Run Configuration Files


Compiling GCHP is the same procedure as compiling GEOS-Chem Classic. Please see Compiling with CMake for instructions.


Previous | Next | Getting Started with GCHP | GCHP Main Page