s_phys_pkgs/text/packages.tex

% $Header:  $
% $Name:  $

\section{Using MITgcm Packages}

The set of packages that will be used within a partiucular model can
be configured using a combination of both ``compile--time'' and
``run--time'' options.  Compile--time options are those used to select
which packages will be ``compiled in'' or implemented within the
program.  Packages excluded at compile time are completely absent from
the executable program(s) and thus cannot be later activated by any
set of subsequent run--time options.

\subsection{Package Inclusion/Exclusion}

There are numerous ways that one can specify compile--time package
inclusion or exclusion and they are all implemented by the
\texttt{genmake2} program which was previously described in Section
\ref{sect:buildingCode}.  The options are as follows:
\begin{enumerate}
\item Setting the \texttt{genamake2} options \texttt{--enable PKG}
  and/or \texttt{--disable PKG} specifies inclusion or exclusion.
  This method is intended as a convenient way to perform a single
  (perhaps for a quick test) compilation.
  
\item By creating a text file with the name \texttt{packages.conf} in
  either the local build directory or the \texttt{-mods=DIR}
  directory, one can specify a list of packages (one package per line,
  with '\texttt{\#}' as the comment character) to be included.  Since
  the \texttt{packages.conf} file can be saved, this is the preferred
  method for setting and recording (for future reference) the package
  configuration.
  
\item For convenience, a list of ``standard'' package groups is
  contained in the \texttt{pkg/pkg\_groups} file.  By selecting one of
  the package group names in the \texttt{packages.conf} file, one
  automatically obtains all packages in that group.

\item By default (that is, if a \texttt{packages.conf} file is not
  found), the \texttt{genmake2} program will use the contents of the
  \texttt{pkg/pkg\_default} file to obtain a list of packages.

\item To help prevent users from creating unusable package groups, the
  \texttt{genmake2} program will parse the contents of the
  \texttt{pkg/pkg\_depend} file to determine:
  \begin{itemize}
  \item whether any two requested packages cannot be simultaneously
    included (\textit{eg.} \textit{seaice} and \textit{thsice} are
    mutually exclusive),
  \item whether additional packages must be included in order to
    satisfy package dependencies (\textit{eg.} \textit{rw} depends
    upon functionality within the \textit{mdsio} package), and
  \item whether the set of all requested packages is compatible with
    the dependencies (and producing an error if they aren't).
  \end{itemize}
  Thus, as a result of the dependencies, additional packages may be
  added to those originally requested.

\end{enumerate}


\subsection{Package Activation}

For run--time package control, MITgcm uses flags set through a
\texttt{data.pkg} file.  While some packages (\textit{eg.}
\texttt{debug}, \texttt{mnc}, \texttt{cost}) may have their own
conventions, most follow a simple flag naming convention of the
form:
\begin{verbatim}
  usePackageName=.TRUE.
\end{verbatim}
where the \texttt{usePackageName} variable can activate or disable the
package at runtime.


%\subsection{Modifying or Creating Packages}

1	edhill	1.1	% $Header: $
2			% $Name: $
3
4			\section{Using MITgcm Packages}
5
6			The set of packages that will be used within a partiucular model can
7			be configured using a combination of both ``compile--time'' and
8			``run--time'' options. Compile--time options are those used to select
9			which packages will be ``compiled in'' or implemented within the
10			program. Packages excluded at compile time are completely absent from
11			the executable program(s) and thus cannot be later activated by any
12			set of subsequent run--time options.
13
14			\subsection{Package Inclusion/Exclusion}
15
16			There are numerous ways that one can specify compile--time package
17			inclusion or exclusion and they are all implemented by the
18			\texttt{genmake2} program which was previously described in Section
19			\ref{sect:buildingCode}. The options are as follows:
20			\begin{enumerate}
21			\item Setting the \texttt{genamake2} options \texttt{--enable PKG}
22			and/or \texttt{--disable PKG} specifies inclusion or exclusion.
23			This method is intended as a convenient way to perform a single
24			(perhaps for a quick test) compilation.
25
26			\item By creating a text file with the name \texttt{packages.conf} in
27			either the local build directory or the \texttt{-mods=DIR}
28			directory, one can specify a list of packages (one package per line,
29			with '\texttt{\#}' as the comment character) to be included. Since
30			the \texttt{packages.conf} file can be saved, this is the preferred
31			method for setting and recording (for future reference) the package
32			configuration.
33
34			\item For convenience, a list of ``standard'' package groups is
35			contained in the \texttt{pkg/pkg\_groups} file. By selecting one of
36			the package group names in the \texttt{packages.conf} file, one
37			automatically obtains all packages in that group.
38
39			\item By default (that is, if a \texttt{packages.conf} file is not
40			found), the \texttt{genmake2} program will use the contents of the
41			\texttt{pkg/pkg\_default} file to obtain a list of packages.
42
43			\item To help prevent users from creating unusable package groups, the
44			\texttt{genmake2} program will parse the contents of the
45			\texttt{pkg/pkg\_depend} file to determine:
46			\begin{itemize}
47			\item whether any two requested packages cannot be simultaneously
48			included (\textit{eg.} \textit{seaice} and \textit{thsice} are
49			mutually exclusive),
50			\item whether additional packages must be included in order to
51			satisfy package dependencies (\textit{eg.} \textit{rw} depends
52			upon functionality within the \textit{mdsio} package), and
53			\item whether the set of all requested packages is compatible with
54			the dependencies (and producing an error if they aren't).
55			\end{itemize}
56			Thus, as a result of the dependencies, additional packages may be
57			added to those originally requested.
58
59			\end{enumerate}
60
61
62			\subsection{Package Activation}
63
64			For run--time package control, MITgcm uses flags set through a
65			\texttt{data.pkg} file. While some packages (\textit{eg.}
66			\texttt{debug}, \texttt{mnc}, \texttt{cost}) may have their own
67			conventions, most follow a simple flag naming convention of the
68			form:
69			\begin{verbatim}
70			usePackageName=.TRUE.
71			\end{verbatim}
72			where the \texttt{usePackageName} variable can activate or disable the
73			package at runtime.
74
75
76			%\subsection{Modifying or Creating Packages}
77