Subsections


9 Porting the ESMF

This section goes into more detail about the ESMF build system and how to port the ESMF software to new platforms.


9.1 The ESMF Build System

For most users the description of the build system in previous sections should be sufficient. Some users, however, may wish to have a more detailed knowledge of the make system either for configuring different build options or for porting to unsupported platforms.

9.1.1 General structure

The main components of the build system are:

9.1.2 Build configuration

A single makefile or makefile fragment from the build system never constitutes a complete set of build rules and settings. Starting from the local makefile, successive include commands are used to string together makefiles and makefile fragments to create a complete system of build rules and settings. Configuration of the build system is done by including a configuration makefile fragment. A configuration for a specific machine or compiler is referred to as a site configuration.

The string of files included is fairly short. Makefiles below the top level makefile include the top level makefile. The top level makefile includes build/common.mk and then build/common.mk includes a configuration file from the build_config directory. The configuration files in the build_config directory contain the platform and site specific build settings. The os, compiler and site that a file configures is determined by its name. The configuration makefile fragments follow the naming convention

    build_config/ESMF_OS.ESMF_COMPILER.ESMF_SITE/build_rules.mk

where ESMF_OS, ESMF_COMPILER and ESMF_SITE are environment variables either set by the user or given default values by the build system. ESMF_OS is the target operating system. If the build is performed on the target system ESMF_OS will typically have the value returned by the command uname -s. ESMF_COMPILER is the compiler name. ESMF_SITE, if set, is generally the current machine name, the location, or the organization (e.g. mit, cola). If there are no site specific files for a particular platform, then ESMF_COMPILER and ESMF_SITE will be set to default. Examples:

    ! Default configuration for IBM AIX systems
    build_config/AIX.default.default/build_rules.mk
    
    ! Linux configuration using lahey compilers.    
    build_config/Linux.lahey.default/build_rules.mk

9.1.3 Source code configuration

Some of the ESMF C++ and Fortran source files contain preprocessor directives to configure the source code for specific platforms. The directives are included in the source code and are pre-processed before the source code is compiled. The directives are used to determine among other things, the size of variable types.

The ESMF build system provides preprocessor directives in ESMC_Conf.h and ESMF_Conf.inc files that are included in the source code. These files are located in

    build_config/ESMF_OS.ESMF_COMPILER.ESMF_SITE/ESMC_Conf.h
    build_config/ESMF_OS.ESMF_COMPILER.ESMF_SITE/ESMF_Conf.inc

where ESMF_OS, ESMF_COMPILER and ESMF_SITE are environment variables set by the user or given default values be the build system. Based on the settings of these environment variables the build system provides a path to the correct files during source code compilation.

9.2 Porting the ESMF to New Platforms

The ESMF build system can be ported to other Unix platforms by adding a new platform specific makefile fragment and two associated configuration files. These files (build_rules.mk, ESMC_Conf.h, ESMF_Conf.inc) must be placed into a new subdirectory of the build_config directory, following the ESMF_OS.ESMF_COMPILER.ESMF_SITE naming convention.

When porting to a new platform it is often helpful to start with a copy of the configuration of an existing ESMF port. You may, for example, want to start with a copy of the build_config/Linux.g95.default directory when working on a new Linux configuration.

9.2.1 Customizing the build_rules.mk fragment

The purpose of the build_rules.mk makefile fragment is to customize the build procedure for a specific platform. The customization is done via makefile variables. The main makefile at the top level of the ESMF directory structure first includes the common.mk makefile fragment. This common makefile fragment defines a large number of variables, setting them either to generally valid default values or to specific values the user has set in their environment using ESMF_ style environment variables.

The platform specific build_rules.mk makefile fragment is included by common.mk after the variables have been initialized, but before any rules are defined in common.mk using these variables. This gives build_rules.mk a chance to modify these variables as it may be necessary to accommodate platform specific properties.

Fortunately only a very small subset of variables pre-defined in common.mk typically need to be modified or overridden in build_rules.mk with platform specific settings. However, there are some variables that must be set in every build_rules.mk file. These are variables that are not pre-set in common.mk.

ESMF_CXXDEFAULT
Default C++ compiler to be used on this platform. This variable will be used by common.mk to set the associated ESMF_CXX variables.
ESMF_CXXCOMPILER_VERSION
Command that when executed will provide information about the version of the C++ compiler to stdout.
ESMF_F90DEFAULT
Default Fortran compiler to be used on this platform. This variable will be used by common.mk to set the associated ESMF_F90 variables.
ESMF_F90COMPILER_VERSION
Command that when executed will provide information about the version of the F90 compiler to stdout.
ESMF_MPIRUNDEFAULT
Default MPI job launch facility to be used on this platform. This variable will be used by common.mk to set the associated ESMF_MPIRUN variables.

The following is a complete alphabetical list of variables that are pre-set in common.mk before build_rules.mk is included. Some of these variables correspond to ESMF_ environment variables while others have a more complicated dependency on the environment variables set by the user.

ESMF_ABI
ESMF_APPSDIR
ESMF_AR
ESMF_ARCREATEFLAGS
ESMF_ARCREATEFLAGSDEFAULT
ESMF_ARDEFAULT
ESMF_AREXTRACTFLAGS
ESMF_AREXTRACTFLAGSDEFAULT
ESMF_ARRAY_LITE
ESMF_BOPT
ESMF_BUILD
ESMF_BUILD_DOCDIR
ESMF_COMM
ESMF_COMPILER
ESMF_CONFDIR
ESMF_CPP
ESMF_CPPDEFAULT
ESMF_CXXCOMPILECPPFLAGS
ESMF_CXXCOMPILEOPTS
ESMF_CXXCOMPILEPATHS
ESMF_CXXCOMPILEPATHSLOCAL
ESMF_CXXCOMPILER
ESMF_CXXCOMPILERDEFAULT
ESMF_CXXESMFLINKLIBS
ESMF_CXXLINKER
ESMF_CXXLINKERDEFAULT
ESMF_CXXLINKLIBS
ESMF_CXXLINKOPTS
ESMF_CXXLINKPATHS
ESMF_CXXLINKRPATHS
ESMF_CXXOPTFLAG
ESMF_CXXOPTFLAG_G
ESMF_CXXOPTFLAG_O
ESMF_CXXOPTFLAG_X
ESMF_DIR
ESMF_DOCDIR
ESMF_EXDIR
ESMF_F90COMPILECPPFLAGS
ESMF_F90COMPILEFIXCPP
ESMF_F90COMPILEFIXNOCPP
ESMF_F90COMPILEFREECPP
ESMF_F90COMPILEFREENOCPP
ESMF_F90COMPILEOPTS
ESMF_F90COMPILEPATHS
ESMF_F90COMPILEPATHSLOCAL
ESMF_F90COMPILER
ESMF_F90COMPILERDEFAULT
ESMF_F90ESMFLINKLIBS
ESMF_F90IMOD
ESMF_F90LINKER
ESMF_F90LINKERDEFAULT
ESMF_F90LINKLIBS
ESMF_F90LINKOPTS
ESMF_F90LINKPATHS
ESMF_F90LINKRPATHS
ESMF_F90MODDIR
ESMF_F90OPTFLAG
ESMF_F90OPTFLAG_G
ESMF_F90OPTFLAG_O
ESMF_F90OPTFLAG_X
ESMF_GREPV
ESMF_INCDIR
ESMF_INSTALL_BINDIR
ESMF_INSTALL_BINDIR_ABSPATH
ESMF_INSTALL_DOCDIR
ESMF_INSTALL_DOCDIR_ABSPATH
ESMF_INSTALL_HEADERDIR
ESMF_INSTALL_HEADERDIR_ABSPATH
ESMF_INSTALL_LIBDIR
ESMF_INSTALL_LIBDIR_ABSPATH
ESMF_INSTALL_MODDIR
ESMF_INSTALL_MODDIR_ABSPATH
ESMF_INSTALL_PREFIX
ESMF_INSTALL_PREFIX_ABSPATH
ESMF_LDIR
ESMF_LIBDIR
ESMF_LOCOBJDIR
ESMF_MACHINE
ESMF_MODDIR
ESMF_MPIBATCHOPTIONS
ESMF_MPILAUNCHOPTIONS
ESMF_MPIMPMDRUN
ESMF_MPIMPMDRUNDEFAULT
ESMF_MPIRUN
ESMF_MPIRUNDEFAULT
ESMF_MPISCRIPTOPTIONS
ESMF_MV
ESMF_NO_INTEGER_1_BYTE
ESMF_NO_INTEGER_2_BYTE
ESMF_OS
ESMF_OPTLEVEL
ESMF_PTHREADS
ESMF_PTHREADSDEFAULT
ESMF_RANLIB
ESMF_RANLIBDEFAULT
ESMF_RM
ESMF_RPATHPREFIX
ESMF_SED
ESMF_SEDDEFAULT
ESMF_SITE
ESMF_SITEDIR
ESMF_SL_LIBLIBS
ESMF_SL_LIBLINKER
ESMF_SL_LIBOPTS
ESMF_SL_LIBS_TO_MAKE
ESMF_SL_SUFFIX
ESMF_STDIR
ESMF_TEMPLATES
ESMF_TESTDIR
ESMF_TESTEXHAUSTIVE
ESMF_TESTMPMD
ESMF_TESTWITHTHREADS
ESMF_UTCDIR
ESMF_UTCSCRIPTS
ESMF_WC

9.2.2 Customizing ESMC_Conf.h and ESMF_Conf.inc

The ESMC_Conf.h file is used to define several settings used during compilation of ESMF library code written in C++.

FTN_X(func)
Macro that will correctly expand "func" to match the Fortran symbol convention. Use this macro for function names that contain an underscore.

FTNX(func)
Macro that will correctly expand "func" to match the Fortran symbol convention. Use this macro for function names that do not contain an underscore.

ESMCI_FortranStrLenArg
Typedef to match the data type of the 'hidden' string length argument that Fortran uses when passing CHARACTER strings.

ESMF_PRESENT(arg)
Macro for a boolean expression that returns TRUE if "arg" is a "present" argument passed from Fortran into C++.

ESMC_POINTER_SIZE
Size of C pointer in bytes.

The ESMF_Conf.inc file is used to optionally define two important macros:

ESMF_NO_INITIALIZERS
If this macro is defined ESMF will assume that initializers inside Fortran derived type definitions are not supported.

ESMF_SEQUENCE_BUG
If this macro is defined ESMF will not use the SEQUENCE specifier inside Fortran derived types under certain circumstances.

9.3 Shared Object Libraries

On many platforms, a shared object library is created in addition to the standard .a archive library. Shared object libraries are libraries that are pre-linked into an executable. They can then be linked to an application at run time. There are many advantages to using shared libraries. These include smaller executable files, and shared memory usage when multiple executables are running - as is often the case of programs using MPI. They also allow easier bug fixing and development because the library can often be upgraded without necessarily re-linking the executables which call into it.

Shared object libraries can be pre-linked to system libraries and using them can simplify dealing with ESMF's dependency on Fortran90 and C++ runtime libraries.

See 8.4 for third party library build requirements.

9.4 Customized SITE Files

In an effort to provide platform specific information for building ESMF and linking the libraries with your application, a SourceForge site, esmfcontrib, has been created. To locate the platform makefiles for a specific institution, check out the build_config_files using the appropriate CVSROOT. The URL for the esmfcontrib SourceForge site is:

        http://sourceforge.net/projects/esmfcontrib/

Additionally, you may check out all the platform makefile fragments for a particular institution from the esmfcontrib site. For example, to check out the available makefile fragments for platforms at the National Center for Atmospheric Research, ncar, change directories to

 	$ESMF_DIR/build_config

and use the following CVS command:

	cvs -z3 -d:ext:$username@cvs.sourceforge.net:/cvsroot/esmfcontrib checkout ncar

The following directories will be checked out:

	AIX.default.bluesky
	Linux.lahey.longs

To build using these makefiles you must set the environment variable ESMF_SITE to bluesky, or longs.

At the present time, we have files for the following institutions:

anl  - Argonne National Laboratory
cola - Center for Ocean-Land-Atmosphere Studies
gsfc - Goddard Space Flight Center
mit  - Massachusetts Institute of Technology
ncar - National Center for Atmospheric Research

Users are encouraged to contribute pertinent information to the esmfcontrib repository.

esmf_support@ucar.edu