Difference between revisions of "Compiling with GNU Make"

From Geos-chem
Jump to: navigation, search
(GNU Make will be retired in GEOS-Chem 13.0.0)
(Makefile options)
Line 31: Line 31:
 
Please see the [[Creating_GEOS-Chem_run_directories|''Creating GEOS-Chem run directories'' wiki page]] for instructions on how to create a GEOS-Chem run directory from the GEOS-Chem Unit Tester.  
 
Please see the [[Creating_GEOS-Chem_run_directories|''Creating GEOS-Chem run directories'' wiki page]] for instructions on how to create a GEOS-Chem run directory from the GEOS-Chem Unit Tester.  
  
=== Makefile options ===
 
  
The compiler flags required for compiling GEOS-Chem, specifically <tt>MET</tt> and <tt>GRID</tt>, and in some cases <tt>NEST</tt>, <tt>TOMAS</tt>, <tt>RRTMG</tt>, or <tt>UCX</tt>, are automatically passed when you compile using the run directory Makefile. The flags are set using the <tt>getRunInfo</tt> perl script located in the run directory which reads the simulation information from the <tt>input.geos</tt> configuration file. If you wish to change any of these options you must create a new run directory.
+
== Compiling GEOS-Chem "Classic" versions 12.4.0 to 12.9.0 ==
  
There are two processing modes available for compiling GEOS-Chem:
+
In this section
#Single processor ("sp")
+
#Multi-processor ("mp"), which uses [[Parallelizing_GEOS-Chem|OpenMP parallelization]]
+
  
Output files, including the GEOS-Chem executable <tt>geos</tt>, have a <tt>.sp</tt> or <tt>.mp</tt> suffix depending on what processing mode is used.
+
=== Run directory contents ===
 +
 
 +
The following files and folders are part of a typical run directory.  This example is for the <tt>geosfp_4x5_standard</tt> simulation.
 +
 
 +
CodeDir@          getRunInfo*      HEMCO_Diagn.rc  input.geos OutputDir/  validate.pl*
 +
download_data.py*  HEMCO_Config.rc  HISTORY.rc      Makefile*  README
 +
 
 +
#<tt>CodeDir</tt> is a symbolic link to the code directory that you specified when you created the run directory. 
 +
#<tt>Makefile</tt> is the run-directory Makefile. This controls the build sequence.  The Makefile relies on the <tt>getRunInfo</tt> script to pass the ver
 +
#<tt>OutputDir</tt> is where diagnostic files will be placed.
 +
#<tt>input.geos</tt> and <tt>*.rc</tt> files are [[GEOS-Chem_configuration_files|configuration files]] that allow you to specify settings for the GEOS-Chem simulation.
 +
#<tt>download_data.py</tt> is the data download script for the GEOS-Chem dry-run simulation (available in [[GEOS-Chem 12#12.7.0|12.7.0]] and later versions).
 +
#<tt>validate.pl</tt> is only used for GEOS-Chem unit tests and difference tests.  You can usually ignore this.
 +
 
 +
=== Determining available compilation options ===
 +
 
 +
The compiler flags required for compiling GEOS-Chem, specifically <tt>MET</tt> and <tt>GRID</tt>, and in some cases <tt>NEST</tt>, <tt>TOMAS</tt>, <tt>RRTMG</tt>, or <tt>UCX</tt>, are automatically passed when you compile using the run directory Makefile. The flags are automatically set bu tje <tt>getRunInfo</tt> script, which parses the <tt>input.geos</tt> configuration file.
  
 
The GEOS-Chem Makefiles allow you to choose from several different options. The best way to learn about these options is to type:  
 
The GEOS-Chem Makefiles allow you to choose from several different options. The best way to learn about these options is to type:  
Line 45: Line 58:
 
  make help
 
  make help
  
at the Unix prompt.  
+
at the Unix prompt.  Because the options might change from version to version, you should always use <tt>make help</tt> to find the specific options for the GEOS-Chem version that you are using.
  
==== Makefile options in versions 12.4.0 to 12.9.0 ====
+
=== Clean up files in the run directory ===
  
If you are using '''''GEOS-Chem 12.4.0 or later''''', then you will see a screen similar to this:
+
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. This can be done by the following options:
%%%    GEOS-Chem Run Directory Makefile Options        %%%
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
Usage: make -jN TARGET [OPTIONAL-FLAGS]
+
+
-jN              Compiles N files at a time (reduces compile time)
+
+
----------------------------------------------------------
+
TARGET may be one of the following:
+
----------------------------------------------------------
+
+
%%% COMPILE AND RUN %%%
+
all              Cleans, compiles, and runs GEOS-Chem
+
hco              Cleans, compiles, and runs HEMCO
+
+
%%% BUILD ONLY %%%
+
build            Compiles GEOS-Chem
+
hcobuild          Compiles HEMCO
+
+
%%% RUN ONLY %%%
+
run              Runs GEOS-Chem
+
hcorun            Runs HEMCO
+
+
%%% CLEAN UP %%%
+
cleanup_output    Synonym for: cleanup_data cleanup_logs
+
cleanup_data      Removes all GEOS-Chem diagnostic and restart file
+
cleanup_hco      Removes all HEMCO diagnostic and restart files
+
  cleanup_logs      Removes all GEOS-Chem and HEMCO output log files
+
cleanup_exe      Removes all GEOS-Chem and HEMCO executable files
+
+
%%% CLEAN SOURCE CODE %%%
+
clean            Makes "clean" in source code directory ODE_DIR
+
realclean        Makes "realclean" in the source code directory ODE_DIR
+
tauclean          Removes all TAU files in the source code directory ODE_DIR
+
+
%%% CLEAN AND REMOVE ALL %%%
+
superclean        Synonym for: realclean tauclean cleanup_output cleanup_exe
+
+
%%% PRINT INFORMATION %%%
+
printruninfo      Prints the run settings for GEOS-Chem simulations
+
printruninfohco  Prints the run settings for HEMCO standalone simulations
+
printbuildinfo    Prints the build settings for GEOS-Chem simulations
+
printallinfo      Synonym for: printbuildinfo printruninfo
+
printcodeinfo    Print code directory git information
+
+
%%% UTILITIES %%%
+
help              Prints this help screen
+
%%% PRINT INFORMATION %%%
+
printruninfo      Prints the run settings for GEOS-Chem simulations
+
printruninfohco  Prints the run settings for HEMCO standalone simulations
+
printbuildinfo    Prints the build settings for GEOS-Chem simulations
+
printallinfo      Synonym for: printbuildinfo printruninfo
+
printcodeinfo    Print code directory git information
+
+
%%% UTILITIES %%%
+
help              Prints this help screen
+
+
----------------------------------------------------------
+
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
+
  
==== Makefile options prior to version 12.4.0 ====
+
make logclean    # Removes all log files
 +
make dataclean  # Removes
 +
make fileclean  # fileclean + dataclean
 +
make superclean  # fileclean + dataclean + cleans up the GEOS-Chem source code (in ../CodeDir)
  
or if you are using a version of GEOS-Chem older than 12.4.0, you will see this screen:
+
=== Build the GEOS-Chem or HEMCO standalone executable ===
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
To create the GEOS-Chem executable file, type:
%%%    GEOS-Chem Run Directory Makefile Help Screen    %%%
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
Usage: make -jN TARGET [OPTIONAL-FLAGS]
+
+
-jN              Compiles N files at a time (reduces compile time)
+
+
----------------------------------------------------------
+
TARGET may be one of the following:
+
----------------------------------------------------------
+
all              Default target (synonym for "unittest")
+
+
%%% COMPILE AND RUN %%%
+
unittest          Runs a GEOS-Chem unit test:
+
                  (1) Builds & runs GEOS-Chem with parallelization OFF;
+
                  (2) Builds & runs GEOS-Chem with parallelzation ON;
+
                  (3) Checks to see if the output is identical.
+
sp                Builds and runs GEOS-Chem with parallelization OFF.
+
mp                Builds and runs GEOS-Chem with parallelization ON.
+
+
%%% BUILD ONLY %%%
+
spbuild          Just builds GEOS-Chem with parallelization OFF.
+
mpbuild          Just builds GEOS-Chem with parallelization ON.
+
+
%%% RUN ONLY %%%
+
sprun            Just runs GEOS-Chem with parallelization OFF.
+
mprun            Just runs GEOS_Chem with parallelization ON.
+
+
%%% REMOVE DATA FILES %%%
+
dataclean        Removes ALL GEOS-Chem diagnostic and restart files
+
spdataclean      Removes diagnostic and restart files from GEOS-Chem
+
                    simulations with parallelization turned OFF.
+
mpdataclean      Removes diagnostic and restart files from GEOS-Chem
+
                    simulations with parallelization turned ON.
+
+
%%% REMOVE LOG FILES %%%
+
logclean          Removes all GEOS-Chem and HEMCO output log files.
+
splogclean        Removes GEOS-Chem and HEMCO log files from GEOS-Chem
+
                    simulations with parallelization turned OFF.
+
mplogclean        Removes GEOS-Chem and HEMCO log files from GEOS-Chems
+
                    simulations with parallelization turned ON.
+
+
%%% REMOVE EXECUTABLE FILES %%%
+
execlean          Removes all GEOS-Chem executable files
+
spexeclean        Removes GEOS-Chem executable files for which the
+
                    parallelization has been turned OFF.
+
mpexeclean        Removes GEOS-Chem executable files for which the
+
                    parallelization has been turned ON.
+
+
%%% REMOVE ALL FILES %%%
+
fileclean        Synonym for: dataclean  logclean  execlean
+
spclean          Synonym for: spdataclean splogclean spexeclean
+
mpclean          Synonym for: mpdataclean mplogclean mpexeclean
+
+
%%% REMOVE CONFIG FILES %%%
+
extrafileclean  Removes input.geos and HEMCO_Config.rc files
+
+
%%% CLEAN SOURCE CODE %%%
+
clean            Makes "clean" in source code directory ODE_DIR
+
realclean        Makes "realclean" in the source code directory ODE_DIR
+
tauclean          Removes all TAU files in the source code directory ODE_DIR
+
+
%%% CLEAN AND REMOVE ALL %%%
+
superclean        Synonym for: fileclean realclean
+
+
...
+
 
+
To compile only, type the following at the command line, including any optional compiler flags as needed:
+
  
 
  make -j4 mpbuild
 
  make -j4 mpbuild
  
Prior to compiling, <tt>geos.mp</tt>, <tt>lastbuild.mp</tt>, and all <tt>.mp</tt> log files will be removed from the directory by calling other make targets <tt>mpexeclean</tt> and <tt>mplogclean</tt>. All standard output generated while building the new executable will be displayed in your terminal window. The executable created will reside in the <tt>/bin</tt> directory within <tt>CODE_DIR</tt> and a copy will be placed in the run directory with name <tt>geos.mp</tt>. Finally, your compile settings will be stored in log <tt>lastbuild.mp</tt> and will also be printed to the terminal window. The unix commands for each of these steps is stored under various targets in the Makefile. Note that you make call any of the make targets from the command line (e.g. <tt>make mplogclean</tt> to remove all <tt>.mp</tt> logs). You can then [[Running GEOS-Chem|submit your GEOS-Chem simulation]] to your local cluster's queue using a simple script.  
+
This will build the <tt>geos</tt> executable file and send all text output to the <tt>compile.log</tt> file.
 +
 
 +
NOTE: the -jN option will compile N files at a time. If you have 8 cores available to you, you can type <tt>make -j8 ...</tt>, etc.
 +
 
 +
=== Build the HEMCO standalone executable ===
  
For testing purposes, you may also  compile and run GEOS-Chem interactively, by typing the following at the command line:
+
To build the HEMCO standalone executable (if you are in a HEMCO standalone run directory), type:
  
  make -j4 mp
+
  make -j4 hcobuild
  
With this option, output data files are appended with the <tt>.mp</tt> suffix except for restart and HEMCO diagnostic files that do not correspond to the simulation end date.  
+
This will build the <tt>hemco_standalone.x</tt> executable file.
  
The GNU Make utility is a powerful and flexible software development tool and we encourage you to explore the existing Makefile options and to customize the Makefile to optimize your own needs.
+
NOTE: the -jN option will compile N files at a time. If you have 8 cores available to you, you can type <tt>make -j8 ...</tt>, etc.
  
--[[User:Lizzie Lundgren|Lizzie Lundgren]] 10:59, 22 April 2015 (EDT)
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 18:31, 20 December 2019 (UTC)
  
 
=== Information from the last time GEOS-Chem was compiled ===
 
=== Information from the last time GEOS-Chem was compiled ===

Revision as of 18:31, 20 December 2019

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Configuring your computational environment
  3. Downloading source code
  4. Downloading data directories
  5. Creating run directories
  6. Configuring runs
  7. Compiling GEOS-Chem
  8. Running
  9. Output files
  10. Visualizing and processing output
  11. Coding and debugging
  12. Further reading


Page is under construction.jpg

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 from a run directory (in versions 12.4.0 to 12.9.*)

All run directories downloaded from the GEOS-Chem Unit Tester come with a router Makefile that enables you to easily compile and run GEOS-Chem from the run directory. Using this feature enables you to eliminate certain compile options from the make command that are always the same for a given run directory (e.g. MET and GRID) and thereby avoid common mistakes. It also creates and stores compile logs locally for easy reference.

Please see the Creating GEOS-Chem run directories wiki page for instructions on how to create a GEOS-Chem run directory from the GEOS-Chem Unit Tester.


Compiling GEOS-Chem "Classic" versions 12.4.0 to 12.9.0

In this 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
  1. CodeDir is a symbolic link to the code directory that you specified when you created the run directory.
  2. Makefile is the run-directory Makefile. This controls the build sequence. The Makefile relies on the getRunInfo script to pass the ver
  3. OutputDir is where diagnostic files will be placed.
  4. input.geos and *.rc files are configuration files that allow you to specify settings for the GEOS-Chem simulation.
  5. download_data.py is the data download script for the GEOS-Chem dry-run simulation (available in 12.7.0 and later versions).
  6. validate.pl is only used for GEOS-Chem unit tests and difference tests. You can usually ignore this.

Determining available compilation options

The compiler flags required for compiling GEOS-Chem, specifically MET and GRID, and in some cases NEST, TOMAS, RRTMG, or UCX, are automatically passed when you compile using the run directory Makefile. The flags are automatically set bu tje getRunInfo script, which parses the input.geos configuration file.

The GEOS-Chem Makefiles allow you to choose from several different 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. This can be done by the following options:

make logclean    # Removes all log files
make dataclean   # Removes 
make fileclean   # fileclean + dataclean
make superclean  # fileclean + dataclean + cleans up the GEOS-Chem source code (in ../CodeDir)

Build the GEOS-Chem or HEMCO standalone executable

To create the GEOS-Chem executable file, type:

make -j4 mpbuild

This will build the geos executable file and send all text output to the compile.log 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.

Build the HEMCO standalone executable

To build the HEMCO standalone executable (if you are in a HEMCO standalone run directory), type:

make -j4 hcobuild

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)

Information from the last time GEOS-Chem was compiled

When compiling from the run directory Makefile, a [[GEOS-Chem_log_files#The_lastbuild_filelog file called lastbuild]] will be created. This file contains the settings that were used to compile GEOS-Chem, for your reference.

Compiling from a run directory (in versions prior to 12.4.0)


Previous | Next | Getting Started with GEOS-Chem