Compiling with GNU Make
- Minimum system requirements
- Installing required software
- Configuring your computational environment
- Downloading source code
- Downloading data directories
- Creating run directories
- Configuring runs
- Compiling GEOS-Chem
- ... with CMake
- ... with GNU Make
- Output files
- Python tools for use with GEOS-Chem
- Coding and debugging
- Further reading
On this page, we describe how to compile GEOS-Chem using the GNU Make build system.
- 1 GNU Make will be retired in GEOS-Chem 13.0.0
- 2 Compiling GEOS-Chem "Classic"
- 2.1 Run directory contents
- 2.2 Determining available compilation options
- 2.3 Clean up files in the run directory
- 2.4 Build the GEOS-Chem executable
- 2.5 Build the HEMCO standalone executable
- 2.6 Log files created by the compilation
- 2.7 Examples
- 3 Compiling GCHP (prior to 13.0.0)
- 4 Further reading
GNU Make will be retired in GEOS-Chem 13.0.0
The GNU Make build system will be retired in both GEOS-Chem and GCHP 13.0.0. This is necessary in order to keep pace with software engineering developments that are taking place at NASA/GMAO and elsewhere in the GEOS-Chem modeling community.
GEOS-Chem "Classic" versions 12.6.0 through 12.9.* are compatible with both GNU Make and CMake.
Compiling GEOS-Chem "Classic"
Each run directory that you create contains a Makefile that enables you to easily compile and run GEOS-Chem from the run directory. Using this feature enables you to only select those options that are relevant to the GEOS-Chem simulation that you are using.
In this section, we list the steps that are needed to compile GEOS-Chem 12.4.0 to 12.9.* with GNU Make. If you are using an earlier GEOS-Chem version, then please see the next section.
Run directory contents
The following files and folders are part of a typical run directory. This example is for the geosfp_4x5_standard simulation.
CodeDir@ getRunInfo* HISTORY.rc OutputDir/ download_data.py* HEMCO_Config.rc input.geos README GEOSChem.Restart.YYYYMMDD_hhmmz.nc4@ HEMCO_Diagn.rc Makefile* validate.pl*
- CodeDir is a symbolic link to the code directory that you specified when you created the run directory.
- Makefile is the run-directory Makefile. This controls the build sequence. The Makefile relies on the getRunInfo script to obtain necessary information.
- OutputDir is where diagnostic files will be placed.
- input.geos and the *.rc files are configuration files that allow you to specify settings for the GEOS-Chem simulation.
- download_data.py is the data download script for the GEOS-Chem dry-run simulation (available in 12.7.0 and later versions).
- validate.pl is only used for GEOS-Chem unit tests and difference tests. You can usually ignore this.
Earlier versions of GEOS-Chem might not have all of these files in the run directory. For example, the CodeDir symbolic link was only added in GEOS-Chem 12.3.0.
Determining available compilation options
The GEOS-Chem Makefiles allow you to choose from several different user-definable options. The best way to learn about these options is to type:
at the Unix prompt. Near the bottom of the printout you will see this section:
---------------------------------------------------------- OPTIONAL-FLAGS may be one of the following: ---------------------------------------------------------- DEBUG=y Compiles GEOS-Chem with various debugging options BOUNDS=y Compiles GEOS-Chem with out-of-bounds error checks FPE=y Compiles GEOS-Chem with floating-point math error checks TRACEBACK=y Compiles GEOS-Chem with traceback error printout (this is the default) TIMERS=1 Compiles GEOS-Chem with timers turned on
Because the options might change from version to version, you should always use make help to find the specific options for the GEOS-Chem version that you are using.
Please see the Examples section below for some common compilation commands.
Clean up files in the run directory
If you are reusing the same run directory to start a new GEOS-Chem simulation (i.e. for debugging or testing purposes), then we recommend that you remove any files that were generated by a prior simulation.
If you are using a recent version of GEOS-Chem (say 12.6.0 or newer), you can clean up the run directory with:
But if you are using an older version (prior to 12.6.0), use this command instead:
If you also want to remove all object (*.o), module (*.mod) and library (*.a) files in the GEOS-Chem code directory (all GEOS-Chem versions), type:
Build the GEOS-Chem executable
To create the GEOS-Chem executable file, type:
make -j4 build [OPTIONS]
This will build the geos executable file and send all text output to the compile.log file.
If you are using a GEOS-Chem version prior to 12.4.0, use this command instead:
make -j4 mpbuild [OPTIONS]
[OPTIONS] denotes additional Makefile options that you wish to apply to the build. These are displayed with make help, as described above.
NOTE: the -jN option will compile N files at a time. If you have 8 cores available to you, you can type make -j8 ..., etc.
Build the HEMCO standalone executable
To build the HEMCO standalone executable (if you are in a HEMCO standalone run directory), type:
make -j4 hcobuild [OPTIONS]
This will build the hemco_standalone.x executable file.
Log files created by the compilation
GEOS-Chem version 12.6.0 and later will produce these compilation log files:
Versions prior to this sent the compilation output (i.e. what would go into compile.log) into the GEOS-Chem log file. The lastbuild file would have been named either:
- lastbuild.mp: Compilation output when make -j4 mpbuild was used (i.e. for multi-processor)
- lastbuild.sp: Compilation output when make -j4 spbuild was used (i.e. for single-processor)
Here are a few examples of the most common GEOS-Chem compilation commands with GNU Make:
Build GEOS-Chem with debugging options
To build GEOS-Chem with debugging flags turned on, use the command below. This will allow you to run GEOS-Chem in a debugger such as gdb:
make -j4 build DEBUG=y BOUNDS=y FPEX=y
Build GEOS-Chem with timers
To turn on GEOS-Chem timers, use:
make -j4 build TIMERS=1
Compiling GCHP (prior to 13.0.0)
GCHP versions prior to 13.0.0 use GNU Make as well. But the compilation process is more complex than for GEOS-Chem "Classic". For more information, please see our Compiling GCHP wiki page.
- GNU Make home page
- GNU Make manual
- GNU Make in detail for beginners (Open Source for you)
- GEOS-Chem coding and debugging
- Guide to GEOS-Chem error messages