File	Date	Author	Commit
build	2020-01-17	Ryan.O'Kuinghttons	[09c537] remove etc dir search from build
build_config	2020-01-03	Silverio Vasquez	[cda15c] Update Copyright to 2002-2020.
cmake	2019-08-26	bekozi	[1f5cba] Fixed parsing of ESMF makefile globals #3614802
scripts	2020-01-17	Ryan.O'Kuinghttons	[09c537] remove etc dir search from build
src	2020-01-28	Robert Oehmke	[bb487e] Add check to make sure that patch isnt used whe...
.gitattributes	2013-01-04	Gerhard Theurich	[06f547] Try to exclude docs from export.
.gitignore	2019-09-05	Gerhard Theurich	[b09a08] Correction in path for Trace/preload files.
LICENSE	2020-01-03	Silverio Vasquez	[cda15c] Update Copyright to 2002-2020.
README	2020-01-03	Silverio Vasquez	[cda15c] Update Copyright to 2002-2020.
makefile	2019-10-31	Gerhard Theurich	[c7ffcc] Consistently run "ranlib" on archives that star...

Read Me

================================================================================

                        README - ESMF 8.1.0 beta snapshot

                    Earth System Modeling Framework (ESMF)

 Earth System Modeling Framework
 Copyright 2002-2020, University Corporation for Atmospheric Research,
 Massachusetts Institute of Technology, Geophysical Fluid Dynamics
 Laboratory, University of Michigan, National Centers for Environmental
 Prediction, Los Alamos National Laboratory, Argonne National Laboratory,
 NASA Goddard Space Flight Center.
 Licensed under the University of Illinois-NCSA License.

================================================================================

Hello and welcome to ESMF.


If you need to compile and link your code against an already-built ESMF library,
go to the "APPLICATION" section below.


If you need to build the ESMF library, go to the "BUILDING and INSTALLING"
section below. (If you just downloaded the ESMF tarball, it is source code and
you will have to build the library first.)


If you are looking for more documentation, or higher-level information
about the ESMF project itself, go to the "MORE HELP" section below.


Several addon packages are included with this ESMF release under ./src/addon:
  ESMPy   - Python interface to ESMF.
  MAPL    - Usability layer developed under the NASA 
            Modeling Analysis and Prediction (MAP) program.
  NUOPC   - Interoperability layer developed under the 
            National Unified Operational Prediction Capability (NUOPC) program.
See each addon package for a specific README file.


Please contact <esmf_support@ucar.edu> with any questions or problems.

================================================================================
================================================================================

APPLICATION compilation and linking
-----------------------------------

If you want to compile and link your application against an ESMF library
which has already been installed on your system, you will need to tell
the compiler where the ESMF module files and ESMF library files are located.
If this has already been documented by the installer of the ESMF library,
follow the directions given. However, if not, then you must determine the
correct compiler and linker flags yourself.

You can do this in a variety of ways. If you already have build scripts or
existing makefiles, you can explicitly add the correct compiler and linker
flags. The ESMF build process puts the modules and library into separate
directories depending on the options used when building the ESMF library.
The directory containing the ESMF library file also contains a makefile 
fragment named "esmf.mk" (e.g. ./lib/libg/Linux.intel.32.mpich.default/esmf.mk
for an ESMF library built on Linux with the Intel compiler for 32-bit using
the mpich MPI-implementation). This makefile fragment defines several variables
indicating compiler options, include paths, linker options, library paths and
libraries necessary to compile and link against ESMF with Fortran or C++. Look
at "esmf.mk" to pull out the necessary flags to compile and link your own code
against the installed ESMF library.

Alternatively, you may want to include "esmf.mk" from within your own build
system. All of the variables defined in "esmf.mk" have prefix "ESMF_"
as to prevent name space conflicts with users' makefiles. Notice that "esmf.mk"
is a self-contained file and is not affected by environment variables. It is
not necessary to set any ESMF_ environment variables to use an ESMF library
that has been installed on your system!

================================================================================
================================================================================

BUILDING and INSTALLING the ESMF library
----------------------------------------

The following compilers and utilities are required for compiling, linking and
testing the ESMF software:
* Fortran90 (or later) compiler
* C++ compiler
* GNU's gcc compiler - for a standard cpp preprocessor implementation
* GNU make
* MPI implementation compatible with the above compilers (but see below)
* LAPACK library compatible with the above compilers (but see below)
* Perl - for running test scripts

Alternatively ESMF can be built using a single-processor MPI-bypass library
that comes with ESMF. It allows ESMF applications to be linked and run in
single-process mode.


Steps of the standard build and install procedure:

 1) Set required environment variable(s) (see next section below).

 2) Type 'gmake' (the GNU make program) to build the ESMF library.

 3) Optionally test the ESMF library build using any of the following targets:
    a) 'gmake unit_tests' to build and run the unit tests.
    b) 'gmake system_tests' to build and run the system tests.
    c) 'gmake check' to build and run the unit and system tests.
    d) 'gmake examples' to build and run the examples.
    f) 'gmake all_tests' to build and run all available tests and examples.
    
    Please consult the "Platform Specific Notes Related to Executing Test 
    Targets" below before attempting to use any of these targets.
    
 4) Type 'gmake install' to install the ESMF library in a custom location.
 
 5) Optionally test the ESMF library installation via 'gmake installcheck'.

================================================================================

GNUmake
-------

The ESMF build system uses the GNU make program; it is generally named
'gmake' but may also be simply 'make' or 'gnumake' on some platforms. We do
not use configure or autoconf; the selection of various options is done by
setting environment variables before building the framework.


Environment Variables
---------------------

The following environment variables are the most likely ones to be used
for a typical ESMF library build under normal circumstances. In most
situations only one or two environment variables need to be set. There are
other environment variables which can be set to customize the ESMF library
build process. In particular, ESMF's dependency on 3rd party libraries, such as
LAPACK, NETCDF, etc., is controlled by special environment variables. The ESMF
User's Guide documents all environment variables in detail. 

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.

bsh/ksh example  :  export ESMF_DIR=/home/joeuser/esmf
csh/tcsh example :  setenv ESMF_DIR /home/joeuser/esmf

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 are 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. Please see the User's Guide for more details.

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. Please see the User's Guide for details.

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. Please see the "PORTING" section below for help.

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.

ESMF_OS

Typically equal to the output of "uname -s" except for UNICOS/mp where
ESMF_OS is set to Unicos. This variable is not normally set by the user unless 
cross-compiling. ESMF_OS indicates the target system for which the ESMF library
is being built. Under normal circumstances, i.e. ESMF is being built on the 
target system, ESMF_OS is set automatically. However, when cross-compiling for
a different target system ESMF_OS must be set to the respective target OS. For
example, when compiling for the Cray X1 on an interactive X1 node ESMF_OS will
be set automatically. However, when ESMF is being cross-compiled for the X1 on
a Linux host the user must set ESMF_OS to Unicos manually in order to indicate
the intended target platform.

ESMF_INSTALL_PREFIX

This variable specifies the prefix of the installation path used with the
install target. Library, F90 module files, header files and documentation
all are installed relative to ESMF_INSTALL_PREFIX by default. See the ESMF
User's Guide on how to customize the installation location of the installed
files using additional "ESMF_INSTALL_..." environment variables.
The ESMF_INSTALL_PREFIX may be provided as an absolute path or relative to 
ESMF_DIR.


Supported Makefile Targets
--------------------------

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

 clean      : remove all files built for this OS/compiler/ABI.
 distclean  : remove all files built for all architectures.
 clobber    : same as distclean.

 lib        : build the ESMF library only (default).
 check      : build and run the unit and system tests to validate the library.
 all        : build the library, the unit and system tests, and examples.
 doc        : build the documentation (requires specific latex macros packages
              and additional utilities).  See the ESMF web site for details;
              the web site also provides pre-built pdf and html versions of all
              docs.

 unit_tests           : build and run the unit tests
 unit_tests_uni       : build unit tests and run them in uni-processor mode
 build_unit_tests     : build unit tests (don't run)
 run_unit_tests       : run unit tests (don't build)
 run_unit_tests_uni   : run unit tests in uni-processor mode (don't build)
 clean_unit_tests     : remove unit test executables only

 system_tests         : build and run the system tests
 system_tests_uni     : build system tests and run them in uni-processor mode
 build_system_tests   : build system tests (don't run)
 run_system_tests     : run system tests (don't build)
 run_system_tests_uni : run system tests in uni-processor mode (don't build)
 clean_system_tests   : remove system test executables only

 examples             : build and run the examples
 examples_uni         : build examples and run them in uni-processor mode
 build_examples       : build examples (don't run)
 run_examples         : run examples (don't build)
 run_examples_uni     : run examples in uni-processor mode (don't build)
 clean_examples       : remove example executables only

 all_tests            : build and run all available tests and examples.
 build_all_tests      : build all available tests and examples (don't run)
 run_all_tests        : run all available tests and examples (don't build)
 clean_all_tests      : remove all available test and example executables

 install              : install the ESMF library in a custom location
 installcheck         : check the ESMF library installation
 

Platform Specific Notes Related to Executing Test Targets
---------------------------------------------------------

After the ESMF library has been built successfully it is a good idea to test
its functional integrity by building and executing a range of test applications.
It is important to use the same environment settings for the ESMF gmake test 
targets as were used during the library build.

The ESMF library source tree comes with 3 flavors of test codes:
- unit_tests:   separately test the functionality of individual ESMF code units
- system_tests: test the interplay of multiple ESMF code units
- examples:     demonstrate features of individual ESMF code units. Example
                sources are quoted in the ESMF Reference Manual.

Unless the ESMF library was built in MPI-bypass mode (mpiuni), all applications
compiled and linked against ESMF automatically become MPI applications and must
be executed as such. Details of how to execute MPI applications vary widely from
system to system. ESMF uses an mpirun script mechanism to abstract away most of
these differences.

ESMF provides mpirun scripts for a wide range of system configurations. These
are used by ESMF by default or can be set by the user via the ESMF_MPIRUN
environment variable. The best way to see how the existing scripts are used
on the supported platforms is to go to the "Supported Platforms" web page at
https://www.earthsystemcog.org/projects/esmf/platforms_7_0_0 and follow the link
for the platform of interest. Each test report contains the output of 
"gmake info", which lists the settings of the ESMF_MPIxxx environment variables.

Users are encouraged to read the "Setting up ESMF to run Test Suite
Applications" in the User's Guide to gain a deeper insight into how ESMF
manages parallel application launching. This User's Guide section is especially
valuable in case no suitable script is available and the user is confronted
with the task of writing a customized, system specific mpirun script to work
with ESMF.

================================================================================
================================================================================

PORTING the ESMF library to a new platform and/or fixing build problems:
-----------------------------------------------------------------------


Overview
--------

If the build_config directory does not already contain a directory for your
platform/compiler, or if your platform/compiler is already supported but you
need to make some adaptations for your local system, this section should help
you get started.

The top level makefile is $ESMF_DIR/makefile. It should not need to be
modified. The bulk of the makefile rules and settings used by all platforms
and compilers is $ESMF_DIR/build/common.mk. This makefile should not be
changed unless the modification is intended to apply to every system on which
ESMF is built. This makefile is included by the top level makefile.

The per-platform makefile fragments which contain the settings which differ
for each system and compiler combination are in separate subdirectories under
$ESMF_DIR/build_config.

If you find the settings are close and you just need to add additional
information, or the changes are very specific to a particular system, you can
set the environment variable ESMF_SITE to a value, and then the makefiles will
include
$ESMF_DIR/build_config/$ESMF_OS.$ESMF_COMPILER.$ESMF_SITE/build_rules.mk,
in addition to the default settings.

If you are supporting a completely new platform, make a new directory
following the naming pattern described below. Copy the contents of the
closest existing match into that directory and start making changes.


Naming Conventions
------------------

In $ESMF_DIR/build_config, each compiler/platform combination has
a separate subdirectory which follows a 3-part naming convention:

The first part is the system name as it is automatically set in ESMF_OS.

The second part is the compiler name for those platforms which support
compilers from different vendors.  For those systems which come with a
single vendor-supplied compiler, the compiler name is 'default'.  
The environment variable ESMF_COMPILER is used to select the compiler.

The last part of the name is the site-specific information. The 'default'
directories contain files which are always read for the given 
architecture/compiler combination. Then, in addition, if the environment
variable ESMF_SITE has a value, the corresponding directory will be 
searched after the default directory, for overrides and additional settings 
of directory names, values, flags, and other custom information.

Note that building on the SGI Altix is the same as the other Linux/Intel 
platforms, so set ESMF_COMPILER to 'intel' to use the files in the
Linux.intel.default directory. For Altix set ESMF_COMM to 'mpi' in order to
pick up the vendor MPI library.


File Descriptions
-----------------

Each default directory contains the following files:

 ESMC_Conf.h    : C++ preprocessor definitions needed for this platform.

 ESMF_Conf.inc  : values needed by both preprocessed F90 and C++; contains
                  information in a format parseable by both languages.         

 build_rules.mk : makefile fragment which is included by the main ESMF build
                  system and contains specific settings for this platform.


Customizing an Existing Platform
--------------------------------

0. Check on http://sourceforge.net/projects/esmfcontrib -> CVS to be sure
   someone else has not already done this for your location or machine.

1. Set the environment variable ESMF_SITE to a string.  Suggested values are
   either your location (e.g. mit, cola) or a specific machine (e.g. bluesky).

2. Make a subdirectory named in the form:  system.compiler.site

3. Initially copy over only build_rules.mk from the corresponding default
   directory and remove all values which remain the same.  The build_rules.mk
   file in this site-specific directory will be included after the default
   one has been read, so only differences should be maintained.  

4. The ESMC_Conf.h and ESMF_conf.inc files do not need to be copied.

5. Test and get it working.

6. Post it back on the esmfcontrib sourceforge site for others to use.


Adding a New Platform
---------------------

1. Create a new subdirectory which follows the naming conventions.

2. Copy the contents of the most similar existing directory over to the 
   new directory.

3. Edit the build_rules.mk file to set the compiler names, flags, etc.
   Since ESMF contains both F90 and C++ code, generally the linkers are
   not able to simply link without being given additional libraries.

4. Edit the ESMC_Conf.h file and look over the macro definitions.

5. Once it is working, post it back on the esmfcontrib sourceforge site and
   email esmf_support@ucar.edu so we can include it in our next
   release.


Directories
-----------

build_config:    Contains makefile fragments that can be customized by the 
                 user for specific platforms, compilers, and sites.
                 See the README in this directory for help with porting to
                 new platforms or compilers.

build:           Contains the generic portion of the build that a
                 user would not be expected to modify.  Also contains a 
                 sample user makefile.

scripts:         Contains scripts for testing and uniprocessor runs, and some
                 templates.

src:             Contains the source code.


The following directories are created during the building and testing stages:

lib:             Contains the ESMF library file.

mod:             Contains the Fortran module files.

test:            Contains unit and system test executables and output.

examples:        Contains examples executables and output.

doc:             Contains documentation (if built).

================================================================================

MORE HELP:
---------

Information about the ESMF project can be found at the ESMF web site:
        https://www.earthsystemcog.org/

Software documentation for the last public release is at:
        https://www.earthsystemcog.org/ -> Users -> User Docs

Software documentation for all releases is at:
        https://www.earthsystemcog.org/ -> Software -> Download/Releases

The ESMF User's Guide contains information on building and installing the ESMF.
The ESMF Reference Manual contains information on the architecture of the ESMF,
example code, and details of the API (Application Programming Interface).

The ESMF library source code is also available for download at:
        http://sourceforge.net/projects/esmf

Follow the directions on that web page to download a tarball and for
access to the ESMF CVS repository.  The Sourceforge site also contains 
the bugs, support, and task lists for ESMF.

Demos, system tests, and use test cases, demonstrating how ESMF can be used in 
realistic situations are available at:
        https://www.earthsystemcog.org/projects/esmf/code_examples/

Contributions from ESMF users are available at:
        http://sourceforge.net/projects/esmfcontrib

Please contact esmf_support@ucar.edu with any questions or problems.

================================================================================
$Id$