Difference between revisions of "Compiling with GNU Make"
(→Makefile options) |
(→Makefile options in versions 12.4.0 to 12.9.0) |
||
| Line 132: | Line 132: | ||
TRACEBACK=y Compiles GEOS-Chem with traceback error printout (this is the default) | TRACEBACK=y Compiles GEOS-Chem with traceback error printout (this is the default) | ||
TIMERS=1 Compiles GEOS-Chem with timers turned on | TIMERS=1 Compiles GEOS-Chem with timers turned on | ||
| − | |||
==== Makefile options prior to version 12.4.0 ==== | ==== Makefile options prior to version 12.4.0 ==== | ||
Revision as of 16:52, 20 December 2019
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
Contents
GNU Make will be retired in GEOS-Chem 13.0.0
Compiling from a run directory
*** RECOMMENDED COMPILING APPROACH ***
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.
Setting up the run directory Makefile
Once you have a run directory, open the Makefile in a text editor and edit the following three configurable variables with your preferences:
# Source code location ifndef CODE_DIR CODE_DIR :=/home/$(USER)/GC/Code.v11-01 endif # Output log file destination (default is run directory) ifndef LOG_DIR LOG_DIR :=. endif
Each of these three variables are automatically passed to the make command using the default values you define in this file. Alternatively, you may define them at the terminal within the make call. For example, if you want to override your default CODE_DIR, you can include CODE_DIR=/GC/Code.Ref to compile Code.Ref rather than Code.Dev.
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:
- Single processor ("sp")
- 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.
