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.esmf.ucar.edu.
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.
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.
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.
On IBM systems using the LSF batch system ESMF_BATCH is used to select the correct method to launch parallel execution.
Variable used to pass system-specific queue options to the batch system. Typically the queue, project and limits are set using ESMF_BATCHOPTIONS.
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.
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.
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.
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.
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.
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.
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.
This variable can be used to override the default utility used to launch parallel execution of ESMF test applications. The executable in ESMF_MPIRUN may be specified with path.
This variable can be used to provide additional options to ESMF_MPIRUN.
This variable can be used to point to the desired NETCDF header files.
This variable can be used to point to the desired NETCDF library files.
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.
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.
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.esmf.ucar.edu/download/platforms/
for the most up-to-date table of supported combinations.)
| ESMF_OS | ESMF_COMPILER | F90 compiler | C++ compiler | ESMF_COMM | ESMF_ABI | |
| Cray X1 | Unicos | default | ftn 5.5.0.6 | CC 5.5.0.6 | mpi | 64 |
| Cray X1 | Unicos | default | ftn 5.5.0.9 | CC 5.5.0.9 | mpi | 64 |
| Cray XT3/4 | Unicos | pgi | ftn 7.0-5 | CC 7.0-5 | mpi | 64 |
| HP ZX6000 | Linux | intel | ifort 8.1.021 | icpc 8.1.024 | lam | 64 |
| IBM Bluegene | Linux | xlf | mpxlf90 10.1.0.4 | mpxlC 8.0.0.4 | mpi | 32 |
| IBM Opteron | Linux | pathscale | pathf90 2.4 | pathCC 2.4 | mpich | x86_64_small, |
| x86_64_medium | ||||||
| IBM Opteron | Linux | pgi | pgf90 6.2-3 | pgCC 6.2-3 | mpich | x86_64_small, |
| x86_64_medium | ||||||
| IBM SP | AIX | default | mpxlf90_r 10.1.0.4 | mpCC_r 8.0.0.0 | mpi | 32,64 |
| IBM SP | AIX | default | mpxlf90_r 10.1.0.4 | mpCC_r 8.0.0.5 | mpi | 32,64 |
| Mac G5 | Darwin | absoft | f90 9.0 | g++ 3.3 | lam,mpiuni | 32 |
| Mac G5 | Darwin | absoft | f90 8.2 | g++ 3.3 | lam,mpiuni | 32 |
| Mac G5 | Darwin | nag | f95 5.0(272) | g++ 3.3 | lam,mpiuni | 32 |
| Mac G5 | Darwin | xlf | xlf90_r 8.1 | xlC_r 6.0 | lam,mpiuni | 32 |
| Mac G5 | Darwin | xlfgcc | xlf90_r 8.1 | g++ 3.3 | lam,mpiuni | 32 |
| PC Pentium III | Linux | lahey | lf95 L6.20d | g++ 3.2.3 | mpiuni | 32 |
| PC Pentium III | Linux | pgi | pgf90 7.0-6 | pgCC 7.0-6 | mpiuni | 32 |
| PC Pentium III | Linux | pgigcc | pgf90 7.0-6 | g++ 3.2.3 | mpiuni | 32 |
| PC Xeon Cluster | Linux | absoftintel | f90 9.0 r2 | icpc 8.1 | mpich | 32 |
| PC Xeon Cluster | Linux | g95 | g95 4.0.2 | g++ 4.0.2 | mpich | 32 |
| PC Xeon Cluster | Linux | intel | ifort 8.1 | icpc 8.1 | mpich | 32 |
| PC Xeon Cluster | Linux | intel | ifort 9.1.036 | icpc 9.1.042 | mpich2 | 64 |
| PC Xeon Cluster | Linux | nagintel | f95 5.0(361) | icpc 8.1 | mpich | 32 |
| SGI Altix | Linux | intel | ifort 9.1.033 | icpc 9.1.039 | mpi | 64 |
| SGI Origin 3800 | IRIX64 | default | f90 7.4.3m | CC 7.4.3m | mpi | 32,64 |
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 | |
| Darwin | g95 | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Darwin | gfortran | mpiuni,mpich,mpich2,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 | |
| 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,lam,openmpi,user | 32, 64 | |
| Linux | absoftintel | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Linux | g95 | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64, ia64_32, ia64_64, | |
| x86_64_32, x86_64_small, | ||||
| x86_64_medium | ||||
| Linux | gfortran | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Linux | intel | mpiuni,mpich,mpich2,lam,openmpi,user, | 32, 64, ia64_32, ia64_64, | |
| intelmpi | x86_64_32, x86_64_small, | |||
| x86_64_medium | ||||
| Linux | intelgcc | mpiuni,mpich,mpich2,lam,openmpi,user | 32, 64 | |
| Linux | lahey | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| Linux | nag | mpiuni,mpich,mpich2,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,lam,openmpi,user | 32, 64, x86_64_32, | |
| x86_64_small, x86_64_medium | ||||
| Linux | pgigcc | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| Linux | xlf | mpiuni,mpich,mpich2,lam,openmpi,user | 32 | |
| OSF1 | default | mpiuni,mpi,user | 64 | |
| Unicos | default | 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.3.
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:
Install ESMF with the command:
gmake install
Check the ESMF installation with the command:
gmake installcheck