5 Quick Start

This section gives a brief description of to how to get the ESMF software, build it, and run the self-tests to verify the installation was successful. More detailed information on each of these steps, as well as information on running a quick_start application and linking the ESMF with your own code is found in Sections 6 and 8.

5.1 Downloading ESMF

5.1.1 From the ESMF web site

ESMF is distributed as a source code tar file. The tar file for the latest public release, release notes, known bugs, supported platforms, documentation, and other related information can be found on the ESMF website, under the Download tab:

    http://www.earthsystemmodeling.org -> Download

The source code for all other releases including the HEAD of the CVS trunk and the last stable version can be found by following the View All Releases link on the left hand navigation bar under Download:

    http://www.earthsystemmodeling.org -> Download -> View All Releases

5.1.2 From the SourceForge website

ESMF can also be downloaded from the SourceForge website from the Files link on that website.

    http://sourceforge.net/projects/esmf -> Files

Follow the directions on that web page to download a tar file.

5.2 Unpacking the download

The source code comes as a zipped tar file. First unzip the file:

gunzip esmf*.tar.gz

Then untar the file:

tar -xf esmf*.tar

This will create a directory called esmf.

5.3 Directory Structure

The current list of directories includes the following:

• README
• application
• build
• build_config
• makefile
• scripts
• src

The build_config directory contains subdirectories for different operating system, compiler combinations. This is a useful area to examine if porting ESMF to a new platform.

5.4 Building ESMF

After downloading and unpacking the ESMF tar file, the build procedure is:

1. Set the required environment variables.
2. Type gmake info to view and verifty your settings
3. Type gmake to build the library.
4. Type gmake check to run self-tests to verify the build was successful.

See the following sections for more information on each of these steps.

5.4.1 Environment Variables

The syntax for setting environment variables depends on which shell you are running. Examples of the two most common ways to set an environment variable are:

ksh

export ESMF_DIR=/home/joeuser/esmf

csh

setenv ESMF_DIR /home/joeuser/esmf

The shell environment variables listed below are the ones most frequently used. There are others which address needs on specific platforms or are needed under more unusual circumstances; see Section 6 for the full list.

ESMF_DIR

The environment variable ESMF_DIR must be set to the full pathname of the top level ESMF directory before building the framework. This is the only environment variable which is required to be set on all platforms under all conditions.

ESMF_BOPT

This environment variable controls the build option. To make a debuggable version of the library set ESMF_BOPT to g before building. The default is O (capital oh) which builds an optimized version of the library. If ESMF_BOPT is O, ESMF_OPTLEVEL can also be set to a numeric value between 0 and 4 to select a specific optimization level.

ESMF_COMM

On systems with a vendor-supplied MPI communications library the vendor library is chosen by default for communications and ESMF_COMM need not be set. For other systems (e.g. Linux or Darwin) a multitude of MPI implementations is available and ESMF_COMM must be set to indicate which implementation is used to build the ESMF library. Set ESMF_COMM according to your situation to: mpich, mpich2, lam, openmpi or intelmpi. ESMF_COMM may also be set to user indicating that the user will set all the required flags using advanced ESMF environment variables.

Alternatively, ESMF comes with a single-processor MPI-bypass library which is the default for Linux and Darwin systems. To force the use of this bypass library set ESMF_COMM equal to "mpiuni".

ESMF_COMPILER

The ESMF library build requires a working Fortran90 and C++ compiler. On platforms that don't come with a single vendor supplied compiler suite (e.g. Linux or Darwin) ESMF_COMPILER must be set to select which Fortran and C++ compilers are being used to build the ESMF library. Notice that setting the ESMF_COMPILER variable does not affect how the compiler executables are located on the system. ESMF_COMPILER (together with ESMF_COMM) affect the name that is expected for the compiler executables. Furthermore, the ESMF_COMPILER setting is used to select compiler and linker flags consistent with the compilers indicated.

By default Fortran and C++ compiler executables are expected to be located in a location contained in the user's PATH environment variable. This means that if you cannot locate the correct compiler executable via the which command on the shell prompt the ESMF build system won't find it either!

There are advanced ESMF environment variables that can be used to select specific compiler executables by specifying the full path. This can be used to pick specific compiler executables without having to modify the PATH environment variable.

Use 'gmake info' to see which compiler executables the ESMF build system will be using according to your environment variable settings.

To see possible values for ESMF_COMPILER, cd to $ESMF_DIR/build_config and list the directories there. The first part of each directory name corresponds to the output of 'uname -s' for this platform. The second part contains possible values for ESMF_COMPILER. In some cases multiple combinations of Fortran and C++ compilers are possible, e.g. there is intel and intelgcc available for Linux. Setting ESMF_COMPILER to intel indicates that both Intel Fortran and C++ compilers are used, whereas intelgcc indicates that the Intel Fortran compiler is used in combination with GCC's C++ compiler.

If you do not find a configuration that matches your situation you will need to port ESMF.

ESMF_ABI

If a system supports 32-bit and 64-bit (pointer wordsize) application binary interfaces (ABIs), this variable can be set to select which ABI to use. Valid values are 32 or 64. By default the most common ABI is chosen. On x86_64 achitectures three additional, more specific ABI settings are available, x86_64_32, x86_64_small and x86_64_medium.

ESMF_SITE

The SourceForge esmfcontrib repository contains makefiles which have already been customized for certain machines. If one exists for your site and you wish to use it, download the corresponding files into the build_contrib directory and set ESMF_SITE to your location (which corresponds to the last part of the directory name). See the SourceForge site http://sourceforge.net/projects/esmfcontrib for more information.

ESMF_ETCDIR

If a user wants to add Attribute package specification files for their own customized Attribute packages, this is where they should go. ESMF will look in this directory for files that specify which Attributes are in an Attribute package for certain ESMF objects, and what the appropriate initial values would be for those Attributes. The format for these Attribute package specification files is to be defined in a future ESMF release. This environment variable is largely for internal use at this point.

ESMF_INSTALL_PREFIX

This variable specifies the prefix of the installation path used during the installation process accessible thought the install target. Libraries, F90 module files, header files and documentation all are installed relative to ESMF_INSTALL_PREFIX by default. The ESMF_INSTALL_PREFIX may be provided as absolute path or relative to ESMF_DIR.

5.4.2 GNU make

The ESMF build system uses the GNU make program; it is normally named gmake but may also be simply make or gnumake on some platforms (we will use gmake in this document). ESMF does not use configure or autoconf; the selection of various options is done by setting environment variables before building the framework.

5.4.3 gmake info

gmake info is a command that assists the user in verifying that the ESMF variables have been set appropriatly. It also tells the user the paths to various libraries e.g. MPI that are set on the system. The user to review this information to verify their settings. In the case of a build failure, this information is invaluable and will be the first thing asked for by the ESMF support team. Below is an example output from gmake info:

--------------------------------------------------------------
Make version:
GNU Make version 3.79, by Richard Stallman and Roland McGrath.
Built for powerpc-apple-darwin7.0
Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99
	Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

Report bugs to <bug-make@gnu.org>.


--------------------------------------------------------------
Fortran Compiler version:
ERROR: No input files.
Pro Fortran 9.0

--------------------------------------------------------------
C++ Compiler version:
g++ (GCC) 3.3 20030304 (Apple Computer, Inc. build 1666)
Copyright (C) 2002 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


--------------------------------------------------------------
Preprocessor version:
gcc (GCC) 3.3 20030304 (Apple Computer, Inc. build 1666)
Copyright (C) 2002 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


--------------------------------------------------------------
ESMF_VERSION_STRING "3.1.0r beta snapshot"
--------------------------------------------------------------
 
--------------------------------------------------------------
 * User set ESMF environment variables *
ESMF_OS=Darwin
ESMF_DIR=/Users/svasquez/script_dirs/branch_builds/esmf
ESMF_TESTWITHTHREADS=OFF
ESMF_INSTALL_PREFIX=/Users/svasquez/script_dirs/branch_builds/esmf/../install_dir
ESMF_COMM=mpiuni
ESMF_TESTEXHAUSTIVE=ON
ESMF_SITE=default
ESMF_ABI=32
ESMF_COMPILER=absoft
 
--------------------------------------------------------------
 * ESMF environment variables *
ESMF_DIR: /Users/svasquez/script_dirs/branch_builds/esmf
ESMF_OS:                Darwin
ESMF_MACHINE:           Power Macintosh
ESMF_ABI:               32
ESMF_COMPILER:          absoft
ESMF_BOPT:              g
ESMF_COMM:              mpiuni
ESMF_SITE:              default
ESMF_PTHREADS:          ON
ESMF_ARRAY_LITE:        FALSE
ESMF_NO_INTEGER_1_BYTE: FALSE
ESMF_NO_INTEGER_2_BYTE: FALSE
ESMF_FORTRANSYMBOLS:    default
ESMF_TESTEXHAUSTIVE:    ON
ESMF_TESTWITHTHREADS:   OFF
ESMF_TESTMPMD:          OFF
 
--------------------------------------------------------------
 * ESMF environment variables pointing to 3rd party software *
 
--------------------------------------------------------------
 * ESMF environment variables for final installation *
ESMF_INSTALL_PREFIX:    /Users/svasquez/script_dirs/branch_builds/esmf/../install_dir
ESMF_INSTALL_HEADERDIR: include
ESMF_INSTALL_MODDIR:    mod/modg/Darwin.absoft.32.mpiuni.default
ESMF_INSTALL_LIBDIR:    lib/libg/Darwin.absoft.32.mpiuni.default
ESMF_INSTALL_DOCDIR:    doc
 
 
--------------------------------------------------------------
 * Compilers, Linkers, Flags, and Libraries *
Location of the preprocessor:      /usr/bin/gcc
Location of the Fortran compiler:  /Applications/Absoft/bin/f90
Location of the Fortran linker:    /Applications/Absoft/bin/f90
Location of the C++ compiler:      /usr/bin/g++
Location of the C++ linker:        /usr/bin/g++

Fortran compiler flags:
ESMF_F90COMPILEOPTS: -g -YEXT_NAMES=LCS -YEXT_SFX=_
ESMF_F90COMPILEPATHS: -p/Users/svasquez/script_dirs/branch_builds/esmf/mod/modg/Darwin.absoft.32.mpiuni.default -I/Users/svasquez/script_dirs/branch_builds/esmf/src/include
ESMF_F90COMPILECPPFLAGS:  -DESMF_TESTEXHAUSTIVE -DS32=1 -DESMF_OS_Darwin=1 -DESMF_MPIUNI

Fortran linker flags:
ESMF_F90LINKOPTS:  -YEXT_NAMES=LCS -YEXT_SFX=_
ESMF_F90LINKPATHS: -L/Users/svasquez/script_dirs/branch_builds/esmf/lib/libg/Darwin.absoft.32.mpiuni.default
ESMF_F90LINKRPATHS: 
ESMF_F90LINKLIBS:  -lstdc++
ESMF_F90ESMFLINKLIBS: -lesmf  -lstdc++

C++ compiler flags:
ESMF_CXXCOMPILEOPTS: -g -DESMF_LOWERCASE_SINGLEUNDERSCORE
ESMF_CXXCOMPILEPATHS: -I/Users/svasquez/script_dirs/branch_builds/esmf/src/include -I/Users/svasquez/script_dirs/branch_builds/esmf/src/Infrastructure/stubs/mpiuni
ESMF_CXXCOMPILECPPFLAGS: -DESMF_TESTEXHAUSTIVE  -DS32=1 -DESMF_OS_Darwin=1 -D__SDIR__='' -DESMF_MPIUNI

C++ linker flags:
ESMF_CXXLINKOPTS: 
ESMF_CXXLINKPATHS: -L/Users/svasquez/script_dirs/branch_builds/esmf/lib/libg/Darwin.absoft.32.mpiuni.default -L/Applications/Absoft/lib
ESMF_CXXLINKRPATHS: 
ESMF_CXXLINKLIBS:  -lf90math -lfio -lac -lf77math -lm
ESMF_CXXESMFLINKLIBS: -lesmf  -lf90math -lfio -lac -lf77math -lm


--------------------------------------------------------------
Compiling on Mon Apr 7 03:11:21 MDT 2008 on glass.image.ucar.edu
Machine characteristics: Darwin glass.image.ucar.edu 7.9.0 Darwin Kernel Version 7.9.0: Wed Mar 30 20:11:17 PST 2005; root:xnu/xnu-517.12.7.obj~1/RELEASE_PPC Power Macintosh powerpc
==============================================================

5.4.4 Building Makefile Targets

The makefiles follow the GNU target standards where possible. The most frequently used targets for building are listed below:

lib

build the ESMF libraries only (default)

all

build the libraries, unit and system tests and examples

doc

build the documentation (requires specific latex macros packages and additional utilities; see Section 6 for more details on the requirements).

info

print out extensive system configuration information about what compilers, libraries, paths, flags, etc are being used

clean

remove all files built for this platform/compiler/wordsize.

clobber

remove all files built for all architectures

install

install the ESMF library in a custom location

5.4.5 Testing Makefile Targets

To build and run the unit and system tests, type:

gmake check

A summary report of success and failures will be printed out at the end.

See section 8.1.1 on how to set up ESMF to be able to launch the bundled test and example applications.

Other test-related targets are:

all_tests

build and run all available tests

build_all_tests

build tests only, do not execute

run_all_tests

run tests without rebuilding and print a summary of the results

check_all_tests

print out the results summary without re-executing the tests again

clean_all_tests

remove all test executables

For all the targets listed above, the string all_tests can be replaced with one of the strings listed below to select a specific type of test:

unit_tests

unit tests exercise a single part of the system

system_tests

system tests combine functions across the system

examples

examples contain code illustrating a single type of function

For example, gmake build_examples recompiles the example programs but does not execute them. gmake clean_system_tests removes all executables and files associated with the system tests.

For the unit tests only, there is an additional environment variable which affects how the tests are built:

ESMF_TESTEXHAUSTIVE

If this variable is set to ON before compiling the unit tests, longer and more exhaustive unit tests will be run. Note that this is a compile-time and not run-time option.