Compiling with GNU Make
Previous | Next | Getting Started with GEOS-Chem
- Minimum system requirements
- Configuring your computational environment
- Downloading source code
- Downloading data directories
- Creating run directories
- Configuring runs
- Compiling GEOS-Chem
- ... with CMake
- ... with GNU Make
- Running
- Output files
- Visualizing and processing output
- Coding and debugging
- Further reading
On this page, we describe how to compile GEOS-Chem using the GNU Make build system.
Contents
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* HEMCO_Diagn.rc input.geos OutputDir/ validate.pl* download_data.py* HEMCO_Config.rc HISTORY.rc Makefile* README
- 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:
make help
at the Unix prompt. 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.
Clean up files in the run directory
If you have created a fresh run directory, then there is no need to clean it prior to starting a simulation.
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:
make cleanup_output
But if you are using an older version (prior to 12.4.0), use this command instead:
make fileclean
If you also want to remove all object (*.o), module (*.mod) and library (*.a) files in the GEOS-Chem code directory (CodeDir), then type:
make superclean
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.
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.
--Bob Yantosca (talk) 18:31, 20 December 2019 (UTC)
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)
--Bob Yantosca (talk) 19:20, 20 December 2019 (UTC)
Examples
To find a list of Makefile options (assuming GEOS-Chem 12.7.0), type:
make help
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
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
To turn on GEOS-Chem timers, use:
make -j4 build TIMERS=1
etc.
--Bob Yantosca (talk) 19:04, 20 December 2019 (UTC)
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.
