This section goes into more detail about the ESMF build system and how to port the ESMF software to new platforms.
The main components of the build system are:
There are two directories containing makefile fragment files used by the ESMF build system.
The build directory contains the generic makefile fragment file common.mk that is included by the top level makefile in the source tree. The common.mk contains generic build system settings and build rules used across all platforms. A user should have no reason to edit common.mk.
The build_config directory contains subdirectories with makefile fragments (build_rules.mk) for each supported platform defining compilers, compiler flags and the various other definitions that are necessary to build on each platform. One of the build_rules.mk files will be included by the build/common.mk file depending on the values of the environment variables ESMF_OS, ESMF_COMPILER and ESMF_SITE. See below for more details on environment variables.
Environment variables with the prefix ESMF_ are used to pass user specified information to the ESMF build system. A full list of ESMF_ environment variables is provided in section 8.5 of this document.
Most environment variables are optional and the ESMF build system will use default settings if it finds these variable unset. One piece of information that must always be provided by setting the respective environment variable is the root of the ESMF directory. There are three sets of source codes the build system supports. All need environment variables set to point to their top level source code directories.
To build the ESMF library, ESMF_DIR needs to be set to the top level ESMF library source code directory.
The build system needs ESMF_IMPL_DIR set to the top level source code directory of the Implementation Report source tree to build the report and to build and run the examples.
An EVA source code tree does not contain a copy of the ESMF build system. Instead it uses a copy found in an ESMF library source code tree. Building the EVA applications requires that ESMF_EVA_DIR and ESMF_DIR be set. ESMF_EVA_DIR has to be set to the top directory of the EVA source code. ESMF_DIR has to be set to the top directory of an ESMF source code tree.
Every source tree contains a makefile in its top level directory. This makefile includes the common.mk file from the build directory which in turn includes the platform specific build_rules.mk file from one of the build_config subdirectories. The top level makefile contains makefile settings specific for the source code that it is found in.
Each directory in the source tree contains a makefile which includes the top level makefile. These local makefiles include definitions that allow the local files and documents to be built.
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
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.
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.
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.
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.
The ESMC_Conf.h file is used to define several settings used during compilation of ESMF library code written in C++.
The ESMF_Conf.inc file is used to optionally define two important macros:
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.
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.