================================================================================ README - ESMF v5.2.0r Earth System Modeling Framework (ESMF) Earth System Modeling Framework Copyright 2002-2011, 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. Please contact 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 http://www.earthsystemmodeling.org/download/platforms/ 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@list.woc.noaa.gov 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: http://www.earthsystemmodeling.org Software documentation for the last public release is at: http://www.earthsystemmodeling.org -> Users -> Documentation Software documentation for all releases is at: http://www.earthsystemmodeling.org -> Download -> View All 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. Use test cases demonstrating how ESMF can be used in realistic situations are available as a separate module through CVS. Please follow the instructions on the ESMF web site: http://www.earthsystemmodeling.org -> Developers -> Test & Validation Contributions from ESMF users are available at: http://sourceforge.net/projects/esmfcontrib Please contact esmf_support@list.woc.noaa.gov with any questions or problems. ================================================================================ $Id: README,v 1.118 2011/07/07 05:19:09 theurich Exp $