Skip navigation
NASA Logo, National Aeronautics and Space Administration
Modeling Guru Banner
Currently Being Moderated

The GEOS-5 build system

VERSION 7  Click to view document history
Created on: Mar 31, 2008 10:08 AM by Carlos Cruz - Last Modified:  Nov 28, 2012 9:59 AM by Carlos Cruz

GEOS-5 uses gmake. gmake (GNU make - called simply make on linux systems) is a tool to help you build a program from its source. In GEOS-5 there are some very large programs made with a number of libraries with hundreds and possibly thousands of source files. Rebuilding such a system from scratch can take hours and is not practical during program development.

 

Having once built a program it isn't necessary to completely rebuild it after making some changes. Only things that are out of date need to be rebuilt and the rules are very simple:-

 

1. Recompile any .o file if its source has changed.

2. Recreate any library if any of its .o files have changed.

3. Rebuild any executable if its libraries have changed.

 

Again, applying such rules to a large software project, like GEOS-5, would be both tedious and error prone. Instead the gmake tool is used. You create a special file called a makefile (the default name is GNUmakefile) which contains instructions on how to create all object, library and executable files and then pass this file to gmake along with a request to build the program. gmake applies the instructions recursively and rebuilds just those parts that need to be rebuilt.

 

For more info see the GNU Make web page.

 

In GEOS-5 the instructions are not all included in one GNUmakefile. Instead the build mechanism centers around the instructions in several makefile fragment files in a Config directory. The most important files are:

 

  • ESMA_base.mk : defines somewhat universal macros and compilation rules which are then costumized for each architecture in ESMA_arch.mk

  • ESMA_arch.mk : costumizes ESMF_base.mk for each each architecture

  • GMAO_base.mk : defines specific macros associated with basic, shared packages. This file must be included after ESMA_base.mk and ESMA_arch.mk.

 

Config also contains other utilities that help automate the GEOS-5 build and make it portable among several platforms.

 

The ESMA_arch.mk file contains machine-specific makefile directives. In the current release, the directives have been divided into different platform-dependent sections each containing site/machine specific options. The site and operating system characteristics are set in the machine-independent file, ESMA_base.mk via the environment variables $ARCH$, $MACH and $SITE.

 

If a user needs to modify compiler options for a specific machine, only the ESMA_arch.mk file needs to be edited.  Similarly, if a user wants to add a new machine to the GEOS-5 scripts, they will need to add or modify the ESMA_arch.mk file appropriately to support that  new machine.  More information about porting GEOS-5 to a new machine is available in section Porting GEOS-5 to new platforms.

 

GEOS-5 can be built either interactively running gmake install or by batch submission of parallel_build.csh. For a first time user or when doing model development we recommend that GEOS-5 be built interactively. There is one good reason for this: building interactively allows the user to immediately detect build related problems without waiting in the batch queueing system.

 

The gmake install command does the following (here $ARCH refers to a particular architecture like Linux or IBM):

 

  • sources several files in the Config directory

  • creates the necessary model directory hierarchy under the GEOS-5 installation path:

  • creates the necessary GEOS-5 libraries under the $ARCH directory

  • copies component resource files under $ARCH/etc

  • copies include files under $ARCH/include

  • creates component executables under $ARCH/bin

  • if gmake doc is executed, it copies documentation files under $ARCH/doc

 

If the installation is not successful, a warning and/or error messages will be printed and the gmake install script will stop. If the build is successful, the user will find the GEOSgcm.x executable under $ARCH/bin.

 

If a compiler or link problem occur the user should carefully review the build output to determine the source of the problem. Note that if building interactively one should use gmake install > & make.log & to generate build output in the make.log file.

 

Each GEOS-5 component generates its own library by invoking gmake install inside that component's directory.

Also, the GEOS-5 make system generates file dependencies automatically.  Users do not need to maintain these dependencies manually.

 

-


Up to: Building and Installing the GEOS-5 AGCM

Return to: GEOS-5 AGCM User's Guide

Comments (0)
USAGov logo NASA Logo - nasa.gov