This section goes into more detail about how to build and install the ESMF software.
Major releases of the ESMF software can be downloaded by following the instructions on the the Download link on the ESMF website, http://www.earthsystemmodeling.org.
The ESMF is distributed as a full source code tree. You will need to compile the code into the libesmf.a library. On some platforms a shared library, libesmf.so, is also created. Follow the instructions in the following sections to build the library and link it with your application.
The following compilers and utilities are required for compiling, linking and testing the ESMF software:
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.
In order to build html and pdf version of the ESMF documentation, LATEX, the latex2html conversion utility, and the Unix/Linux dvipdf utility must be installed.
Some portions of the ESMF library can offer enhanced capabilities when certain third party libraries are available. This section describes these dependencies and the associated environment settings that allow the user to control them.
A few targets are known to always have a vendor-provided LAPACK library available. Where possible, these are incorporated into the build environment by default.
The following environment variables enable, and specify the name and location of the desired LAPACK library:
Specifies the path where the LAPACK library is located.
Specifies the linker directive needed to link the LAPACK library to the application. On some systems, the BLAS library must also be included.
Specifies the path where the NETCDF header files are located.
Specifies the path where the NETCDF library file is located.
Specifies the linker directives needed to link the NETCDF library to the application.
The default value depends on the setting of ESMF_NETCDF. For the typical case where ESMF_NETCDF is set to "standard", ESMF_NETCDF_LIBS is set to "-lnetcdf_c++ -lnetcdf". When ESMF_NETCDF is set to "split", ESMF_NETCDF_LIBS is set to "-lnetcdff -lnetcdf_c++ -lnetcdf".
When defined, enables the use of PNETCDF.
Specifies the path where the PNETCDF header files are located.
Specifies the path where the PNETCDF library file is located.
Specifies the linker directives needed to link the PNETCDF library to the application.
Specifies the path where the XERCES header files are located.
Specifies the path where the XERCES library file is located.
Specifies the linker directives needed to link the XERCES library to the application.
The default value depends on the setting of ESMF_XERCES. For the typical case where ESMF_XERCES is set to "standard", ESMF_XERCES_LIBS is set to "-lxerces-c".
The following is a full alphabetical list of all environment variables which are used by the ESMF build system. In many cases only ESMF_DIR must be set. On Linux and Darwin systems ESMF_COMPILER and ESMF_COMM must also be set to select the appropriate Fortran and C++ compilers and MPI implementation. The other variables have default values which work for most systems.
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.
Not normally set by user. ESMF auto-generates subroutine interfaces for a wide variety of data arrays of different ranks, shapes, and types. If no data of rank greater than 4D will be used, setting this variable to any value will prevent ESMF from generating interfaces for 5D to 7D arrays. This will shrink the amount of autogenerated code.
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.
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".
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.
This variable can be used to override the default C++ compiler and linker front-end executables. The executable may be specified with absolute path overriding the location determined by default from the user's PATH variable.
This variable can be used to prepend flags to default compiler flags.
This variable can be used to override the default C++ compiler front-end executables. The executable may be specified with absolute path overriding the location determined by default from the user's PATH variable.
This variable can be used to prepend directories to default linker directories.
This variable can be used to prepend libraries to default linker libraries.
This variable can be used to prepend flags to default linker flags.
This variable can be used to override the default C++ linker front-end executables. The executable may be specified with absolute path overriding the location determined by default from the user's PATH variable.
This variable can be used to override the default C++ optimization flag.
This variable can be used to override the deferring of the build of the ESMF library. By default, the library is built after all of the source files have been compiled. This speeds up the build process. It also allows parallel compilation of source code when the -j flag is used with gmake. Setting this environment variable to OFF forces the library to be updated after each individual compilation, thus disabling the ability to use parallel compilation.
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.
This variable can be used to override the default Fortran90 compiler and linker front-end executables. The executable may be specified with absolute path overriding the location determined by default from the user's PATH variable.
This variable can be used to prepend flags to default compiler flags.
This variable can be used to override the default Fortran90 compiler front-end executables. The executable may be specified with absolute path overriding the location determined by default from the user's PATH variable.
This variable can be used to override the default flag used to specify the F90 module directory.
This variable can be used to prepend directories to default linker directories.
This variable can be used to prepend libraries to default linker libraries.
This variable can be used to prepend flags to default linker flags.
This variable can be used to override the default Fortran90 linker front-end executables. The executable may be specified with absolute path overriding the location determined by default from the user's PATH variable.
This variable can be used to override the default Fortran90 optimization flag.
Location into which to install the documentation during installation. This location can be specified as absolute path or relative to ESMF_INSTALL_PREFIX.
Location into which to install the header files during installation. This location can be specified as absolute path or relative to ESMF_INSTALL_PREFIX.
Location into which to install the library files during installation. This location can be specified as absolute path or relative to ESMF_INSTALL_PREFIX.
Location into which to install the F90 module files during installation. This location can be specified as absolute path or relative to 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.
Not normally set by user. This variable indicates achitectual details about the machine on which the ESMF library is being built. The value of this variable will affect which ABI settings are available and what they mean. ESMF_MACHINE is set automatically.
Variable used to pass system-specific queue options to the batch system. Typically the queue, project and limits are set. See section 8.1.1 for a discussion of this option.
Variable used to pass system-specific options to the MPI launch facility. See section 8.1.1 for a discussion of this option.
This variable can be used to override the default utility used to launch parallel execution of ESMF test applications in MPMD mode. The executable in ESMF_MPIMPMDRUN may be specified with path.
This variable can be used to override the default utility used to launch parallel ESMF test or example applications. The executable in ESMF_MPIRUN may be specified with path. See section 8.1.1 for a discussion of this option.
Variable used to pass system-specific options to the first level MPI script accessed by ESMF. See section 8.1.1 for a discussion of this option.
Not normally set by user. Setting this variable to ON will prevent ESMF from generating data array interfaces for data types of 1-byte integers.
Same as ESMF_NO_INTEGER_1_BYTE but for 2-byte integers.
Compiles and links the ESMF library with OpenMP compiler flags.
See ESMF_BOPT for details.
Not normally set by user unless cross-compiling. This variable indicates the target system for which the ESMF library is being built. Under normal circumstances, i.e. ESMF is being build 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.
This compile-time option controls ESMF's dependency on a functioning Pthreads library. The default option is set to ON with the exception of IRIX64 and platforms that don't provide Pthreads. On IRIX64 the use of Pthreads in ESMF is disabled by default because the Pthreads library conflicts with the use of OpenMP on this platform.
The user can override the default setting of ESMF_PTHREADS on all platforms that provide Pthread support. Setting the ESMF_PTHREADS environment variable to OFF will disable ESMF's Pthreads feature set. On platforms that don't support Pthreads, e.g. IBM BlueGene/L or Cray XT3, the default OFF setting cannot be overridden!
Build configure file site name or the value default. If not set, then the value of default is assumed. When including platform-specific files, this value is used as the third part of the directory name (parts 1 and 2 are the ESMF_OS value and ESMF_COMPILER value, respectively.)
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.
Variable specifying how to compile the unit tests. If set to the value ON, then all unit tests will be compiled and will be executed when the test is run. If unset or set to any other value, only a subset of the unit tests will be included to verify basic functions. Note that this is a compile-time selection, not a run-time option.
The ON setting enforces usage of OpenMP compiler flags when building ESMF test applications. This allows testing of user-level OpenMP usage even with ESMF_OPENMP set to OFF.
Variable specifying the test harness makefile target for the array class. If this variable is not specified, a default test scenario will be run for the array class. See the ESMF Software Developer's Guide for instructions for selecting other test harness scenarios.
Variable specifying the test harness makefile target for the field class. If this variable is not specified, a default test scenario will be run for the field class. See the ESMF Software Developer's Guide for instructions for selecting other test harness scenarios.
Variable specifying whether to run MPMD-style tests, i.e. test applications that start up as multiple separate executables.
Variable specifying whether to run shared object tests. This requires that the compute environment supports shared objects, and that the ESMF library is available in form of a shared library.
If this environment variable is set to ON before the ESMF system tests are build they will activate ESMF threading in their code. Specifically each component will be executed using ESMF single threading instead of the default non-threaded mode. The difference between non-threaded and ESMF single threaded execution should be completely transparent. Notice that the setting of ESMF_TESTWITHTHREADS does not alter ESMF's dependency on Pthreads but tests ESMF threading features during the system tests. An ESMF library that was compiled with disabled Pthread features (via the ESMF_PTHREADS variable) will produce ESMF error messages during system test execution if the system tests were compiled with ESMF_TESTWITHTHREADS set to ON.
Environment variables must be set in the user's shell or when calling gmake. It is not necessary to edit ESMF makefiles or other build system files to set these variables. Here is an example of setting an environment variable in the csh/tcsh shell:
setenv ESMF_ABI 32
In bash/ksh shell environment variables are set this way:
export ESMF_ABI=32
Environment variables can also be set from the gmake command line:
gmake ESMF_ABI=32
The following two tables list various combinations of environment variable settings used by the ESMF build system. A default value in the compiler column indicates the vendor compiler. A mpi value in the comm column indicates the vendor MPI implementation.
The first table lists the exact combinations which are tested regularly and are fully supported. The second table lists all possible combinations which are included in the build system.
Fully tested combinations: (See http://www.earthsystemmodeling.org/download/platforms/
for the most up-to-date table of supported combinations.)
| ESMF_OS | ESMF_COMPILER | ESMF_COMM | ESMF_ABI | F90 compiler | C++ compiler | |
| Cray XT4 | Unicos | intel | mpi | 64 | ftn/ifort 11.1.046 | CC/icpc 11.1.046 |
| Cray XT4 | Unicos | pgi | mpi | 64 | ftn/pgf90 10.2-0 | CC/pgCC 10.2-0 |
| Cray XT5 | Unicos | intel | mpi | 64 | ftn/ifort 11.1.046 | CC/icpc 11.1.046 |
| Cray XT5 | Unicos | pgi | mpi | 64 | ftn/pgf90 10.2-0 | CC/pgCC 10.2-0 |
| IBM Bluegene | Linux | xlf | mpi | 32 | mpxlf90 11.1.0.3 | mpxlC 9.0.0.3 |
| IBM SP | AIX | default | mpi | 32,64 | mpxlf90_r 12.1.0.7 | mpCC_r 10.1.0.6 |
| Mac Xeon (64) | Darwin | g95 | mpiuni | 32 | g95 0.92(4.0.3) | g++ 4.2.1 |
| Mac Xeon (64) | Darwin | gfortran | mpich2 | 64 | gfortran 4.4.2 | g++ 4.4.2 |
| mvapich2 | ||||||
| Mac Xeon (64) | Darwin | nag | mpiuni | 64 | nagfor 5.2(711) | g++ 4.2.1 |
| PC Xeon (64) | Linux | g95 | mpich2 | 64 | g95 0.92(4.0.3) | g++ 4.4.0 |
| mvapich2 | ||||||
| openmpi | ||||||
| PC Xeon (64) | Linux | gfortran | mpich2 | 64 | gfortran 4.4.0 | g++ 4.4.0 |
| mvapich2 | ||||||
| openmpi | ||||||
| PC Xeon (64) | Linux | nag | mpiuni | 64 | nagfor 5.2(668) | g++ 4.4.0 |
| mpich2 | ||||||
| mvapich2 | ||||||
| PC Xeon (64) Cluster | Linux | gfortran | mvapich2 | 64 | gfortran 4.4.2 | g++ 4.4.2 |
| PC Xeon (64) Cluster | Linux | intel | mvapich2 | 64 | ifort 11.1.059 | icpc 11.1.059 |
| PC Xeon (64) Cluster | Linux | pgi | mpich | 64 | pgf90 9.0-4 | pgCC 9.0-4 |
| PC Xeon (64) Cluster | Linux | intel | mvapich2 | 64 | ifort 11.1.038 | icpc 11.1.038 |
| PC Xeon (64) Cluster | Linux | pgi | mvapich2 | 64 | pgf90 7.1-3 | pgCC 7.1-3 |
| PC Xeon (64) Cluster | Linux | pgi | mvapich2 | 64 | pgf90 10.3-0 | pgCC 10.3-0 |
| PC Xeon (64) Cluster | Linux | intel | intelmpi | 64 | ifort 10.1.021 | icpc 10.1.021 |
| openmpi | ||||||
| scalimpi | ||||||
| PC Xeon (64) Cluster | Linux | nag | mpiuni | 64 | nagfor 5.2(638) | g++ 4.1.2 |
| PC Xeon (64) Cluster | Linux | pgi | scalimpi | 64 | pgf90 7.1-6 | pgCC 7.1-6 |
| SGI Altix (ia64) | Linux | intel | mpi | 64 | ifort 11.0.083 | icpc 11.0.083 |
| SGI Altix ICE | Linux | intel | mpi | 64 | ifort 10.1.021 | icpc 10.1.021 |
| SGI Altix XE Cluster | Cygwin | g95 | mpiuni | 32 | g95 0.92(4.1.1) | g++ 4.3.4 |
| SGI Altix XE Cluster | Cygwin | gfortran | mpiuni | 32 | gfortran 4.3.4 | g++ 4.3.4 |
| SGI Altix XE Cluster | MinGW | intel | msmpi | 64 | ifort 11.1.060 | icl 11.1.060 |
| SGI Altix XE Cluster | MinGW | intelcl | msmpi | 64 | ifort 11.1.060 | cl 14.00.50727.762 |
| Sun SPARC | SunOS | default | mpi | 64 | f95 8.3 | CC 5.9 |
All possible options. Where multiple options exist, and the default is independent of ESMF_MACHINE, the default value is in bold:
| ESMF_OS | ESMF_COMPILER | ESMF_COMM | ESMF_ABI | |
| AIX | default | mpiuni,mpi,user | 32, 64 | |
| Cygwin | g95 | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Cygwin | gfortran | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | absoft | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | g95 | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | gfortran | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32, 64 | |
| Darwin | intel | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | intelgcc | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | nag | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | xlf | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| Darwin | xlfgcc | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| IRIX64 | default | mpiuni,mpi,user | 32, 64 | |
| Linux | absoft | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32, 64 | |
| Linux | absoftintel | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Linux | g95 | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32, 64, ia64_64, | |
| x86_64_32, x86_64_small, | ||||
| x86_64_medium | ||||
| Linux | gfortran | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32, 64, ia64_64, | |
| x86_64_32, x86_64_small, | ||||
| x86_64_medium | ||||
| Linux | intel | mpiuni,mpi,mpich,mpich2,mvapich2,lam,openmpi, | 32, 64, ia64_64, | |
| user,intelmpi,scalimpi | x86_64_32, x86_64_small, | |||
| x86_64_medium | ||||
| Linux | intelgcc | mpiuni,mpi,mpich,mpich2,lam,openmpi, | 32, 64, ia64_64, | |
| user,intelmpi | x86_64_32, x86_64_small, | |||
| x86_64_medium | ||||
| Linux | lahey | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32 | |
| Linux | nag | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32 | |
| Linux | nagintel | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| Linux | pathscale | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64, x86_64_32, | |
| x86_64_small, x86_64_medium | ||||
| Linux | pgi | mpiuni,mpich,mpich2,mvapich2,lam,openmpi,user | 32, 64, x86_64_32, | |
| scalimpi | x86_64_small, x86_64_medium | |||
| Linux | pgigcc | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| Linux | xlf | mpiuni,mpi,user | 32 | |
| MinGW | intel | mpiuni,msmpi,user | 32, 64 | |
| MinGW | intelcl | mpiuni,msmpi,user | 32, 64 | |
| OSF1 | default | mpiuni,mpi,user | 64 | |
| SunOS | default | mpiuni,mpi,user | 32, 64 | |
| Unicos | default | mpiuni,mpi,user | 64 | |
| Unicos | intel | mpiuni,mpi,user | 64 | |
| Unicos | pgi | mpiuni,mpi,user | 64
|
Building the library for multiple architectures or options at the same time is supported; building or running the tests or examples is restricted to one platform/architecture at a time. The output from the test cases will be stored in a separate directories so the results will be kept separate for different architectures or options.
GNU make is required to build the library. On some systems this will be just the command make. On others it might be installed as gmake or even gnumake. In any event, use the -version option with the make command to determine if it is GNU make.
Build the library with the command:
gmake
Makefiles throughout the framework are configured to allow users to compile files only in the directory where gmake is entered. Shared libraries are rebuilt only if necessary. In addition the entire ESMF framework may be built from any directory by entering gmake all, assuming that all the environmental variables are set correctly as described in Section 6.4.
The makefiles are also configured to allow multiple make targets to be compiled in parallel, via the gmake -j flag. For example, to use eight parallel processes to build the library, use -j8:
gmake -j8 lib
The parallel compilation feature depends on ESMF_DEFER_LIB_BUILD=ON (the default) so that the library build will be deferred until all files have been compiled.
The -j option should only be used during the creation of the library. The test base and examples will not work correctly with -j set larger than 1.
Users may also run examples or execute unit tests of specific classes by changing directories to the desired class examples or tests directories and entering gmake run_examples or gmake run_unit_tests, respectively. For non-multiprocessor machines, uni-processor targets are available as gmake run_examples_uni or gmake run_unit_tests_uni.
The ESMF source documentation consists of an ESMF User's Guide and an ESMF Reference Manual for Fortran.
The tarballs on the ESMF website for ESMF versions 3.0.1 and later do not contain the ESMF documentation files. The documentation is available on the ESMF website in html or pdf form and most users should not need to build it from the source.
If a user does want to build the documentation, they will need to download the esmf module from the ESMF SourceForge repository (see section 5.1.1. Latex and latex2html must be installed.
To build documentation:
gmake doc ! Builds the manuals, including pdf and html.
The resulting documentation files will be located in the top level directory $ESMF_DIR/doc
The ESMF build system offers the standard install target to install all necessary files created during the build process into user specified locations. The installation procedure will also install the ESMF documentation if it has been built successfully following the procedure outlined above.
The installation location can be customized using five ESMF_ environment variables:
Section 6.4 describes what each of these environment variables does and how to set them.
Install ESMF with the command:
gmake install
Check the ESMF installation with the command:
gmake installcheck
Advice to installers. Complete the installation of ESMF by defining a single ESMF specific environment variable, named ESMFMKFILE. This variable shall point to the esmf.mk file that was generated during the installation process. Systems that support multiple ESMF installations via management software (e.g. modules, softenv, ...) shall set/reset variable ESMFMKFILE as part of the configuration.
By default file esmf.mk is located next to the ESMF library file in directory ESMF_INSTALL_LIBDIR. Consequently, unless esmf.mk has been moved to a different location after the installation, the correct setting for ESMFMKFILE is $(ESMF_INSTALL_LIBDIR)/esmf.mk.
Rationale. The only piece of information that is needed to use an ESMF installation is the exact location of the associated esmf.mk file. This file contains all of the relevant settings and flags that allow a user to build their application against the ESMF installation. (See section 9 for details about esmf.mk.) Standardizing the mechanism by which the location of esmf.mk is made available to the user by the system will help users in the design of portable application build systems.