esmf_install.tex

CCSM Research Tools: Community Atmosphere Model (CAM)

% $Id: ESMF_install.tex,v 1.1.6.1 2002/04/24 03:26:01 erik Exp $

\section{Installation}

Currently the following environment variables need to be set:
\begin{verbatim}
  ESMF_DIR      top-level ESMF directory
  ESMF_ARCH     platform and compiler configuration
\end{verbatim}

\noindent The following configurations are supported:

\begin{tabular}{lll}
{\tt ESMF\_ARCH}  & {\tt alpha}      &  OSF1, Native compilers. \\
                  & {\tt IRIX64}     &  IRIX64, MIPSpro/mpt 64 bit compilers. \\
                  & {\tt IRIX}       &  IRIX64, MIPSpro/mpt n32 abi compilers. \\
                  & {\tt rs6000\_sp}  &  AIX, mpxlf90\_r, mpcc\_r, and mpCC\_r.  \\
                  & {\tt linux\_gnupgf90} & Linux, pgf90, gcc and g++.  \\
                  & {\tt linux\_pgi}  &  Linux, pgf90, pgcc, pgCC. \\
                  & {\tt linux\_lf95} &  Linux, lf95, gcc, g++. \\
                  & {\tt solaris}        &  SunOs, SUNWspro compilers. \\
                  & {\tt solaris\_hpc}   &  SunOs, SUNWhpc compilers. \\
\end{tabular}

\smallskip

The library requires {\tt gmake} to build.  Simultaneous multiple architecture builds are supported, with
one restriction; the test cases may only be run on one platform at a time. 

\smallskip

\noindent Build the library with the command:
\begin{verbatim}
  gmake BOPT=g  
\end{verbatim}
  for a debug version or
\begin{verbatim}
  gmake BOPT=O  
\end{verbatim}
  for an optimized version.

A test suite is included with the library.  Tests are provided for both MPI
and uniprocessor builds. 

\noindent To build and run MPI C tests:

\begin{verbatim}
  gmake BOPT=g test_c
\end{verbatim}

\noindent To build and run MPI F90 tests:
\begin{verbatim}
  gmake BOPT=g test_f90
\end{verbatim}

\noindent To build and run non-MPI C tests:
\begin{verbatim}
  gmake BOPT=g test_cuni
\end{verbatim}

\noindent To build and run non-MPI F90 tests:
\begin{verbatim}
  gmake BOPT=g test_f90uni
\end{verbatim}

Output files from the test examples will be directed to files in:
\begin{verbatim}
${ESMF_DIR}/test${BOPT}/${ESMF_ARCH}
\end{verbatim}

Exhaustive tests exist that may be activated by setting the environment variable
{\tt ESMF\_EXHTEST} to {\tt on}.  While this activation will test the library more thoroughly,
it will take significantly longer to complete than the basic tests.

\smallskip

\noindent To build documentation:
\begin{verbatim}
  gmake dvi           ! Makes the dvi files
  gmake pdf           ! Makes the pdf files
  gmake html          ! Creates the html directory.
  gmake alldoc        ! Builds all the above documents.
\end{verbatim}

To use the library from C/C++, link with the library executable and include
the {\tt ``ESMC.h''} file.
To use the library from Fortran, link with the library executable and
create links to the library modules in your build directory.  These are
in the top level {\tt mod} directory under the appropriate architecture.  Alternately, 
most compilers have a module-include-path directive which may be used to point
to the correct module directory.
To include the library in application modules, {\tt USE} the
module, e.g. {\tt ESMF\_TimeMgmtMod}.  

There is an install target which will copy the library and mod files to an
install location.  To invoke this target use:
\begin{verbatim}
  gmake BOPT=[O,g] ESMF_LIB_INSTALL=dir_for_lib ESMF_MOD_INSTALL=dir_for_mod_files install 
\end{verbatim}

Some users may wish for the library to be built in a directory different from 
where the source code resides.  To do this, build using:
\begin{verbatim}
   gmake ESMF_BUILD=build_directory_here BOPT=[O,g]
\end{verbatim}

The {\tt ESMF\_BUILD} variable gives an alternate path in which to place the libraries,
mod files and object files.  This variable defaults to {\tt ESMF\_DIR}.  If it is 
assigned another value, the {\tt ESMF\_BUILD} variable will need to be passed as
an additional argument to the the above make commands.  (Alternatively the variable
{\tt ESMF\_BUILD} can be set in the environment (using setenv or export) and then it 
need not be passed to any make calls).