Difference between revisions of "Compiling with GNU Make"

From Geos-chem
Jump to: navigation, search
(Setting up the run directory Makefile)
(Compiling from a run directory (in versions 12.4.0 to 12.9.*))
Line 22: Line 22:
  
 
== Compiling from a run directory (in versions 12.4.0 to 12.9.*) ==
 
== Compiling from a run directory (in versions 12.4.0 to 12.9.*) ==
 
<span style="color:red">'''*** RECOMMENDED COMPILING APPROACH ***'''</span>
 
  
 
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.
 
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.

Revision as of 17:51, 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

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.

Makefile 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 set using the getRunInfo perl script located in the run directory which reads the simulation information from the input.geos configuration file. If you wish to change any of these options you must create a new run directory.

There are two processing modes available for compiling GEOS-Chem:

  1. Single processor ("sp")
  2. Multi-processor ("mp"), which uses OpenMP parallelization

Output files, including the GEOS-Chem executable geos, have a .sp or .mp suffix depending on what processing mode is used.

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.

Makefile options in versions 12.4.0 to 12.9.0

If you are using GEOS-Chem 12.4.0 or later, then you will see a screen similar to this:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%    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

or if you are using a version of GEOS-Chem older than 12.4.0, you will see this screen:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%    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

Prior to compiling, geos.mp, lastbuild.mp, and all .mp log files will be removed from the directory by calling other make targets mpexeclean and mplogclean. All standard output generated while building the new executable will be displayed in your terminal window. The executable created will reside in the /bin directory within CODE_DIR and a copy will be placed in the run directory with name geos.mp. Finally, your compile settings will be stored in log lastbuild.mp 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. make mplogclean to remove all .mp logs). You can then submit your GEOS-Chem simulation to your local cluster's queue using a simple script.

For testing purposes, you may also compile and run GEOS-Chem interactively, by typing the following at the command line:

make -j4 mp

With this option, output data files are appended with the .mp suffix except for restart and HEMCO diagnostic files that do not correspond to the simulation end date.

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.

--Lizzie Lundgren 10:59, 22 April 2015 (EDT)

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