2 |
% $Name$ |
% $Name$ |
3 |
|
|
4 |
\section{Using MITgcm Packages} |
\section{Using MITgcm Packages} |
5 |
|
\label{sec:pkg:using} |
6 |
|
\begin{rawhtml} |
7 |
|
<!-- CMIREDIR:package_using: --> |
8 |
|
\end{rawhtml} |
9 |
|
|
10 |
The set of packages that will be used within a partiucular model can |
The set of packages that will be used within a partiucular model can |
11 |
be configured using a combination of both ``compile--time'' and |
be configured using a combination of both ``compile--time'' and |
20 |
There are numerous ways that one can specify compile--time package |
There are numerous ways that one can specify compile--time package |
21 |
inclusion or exclusion and they are all implemented by the |
inclusion or exclusion and they are all implemented by the |
22 |
\texttt{genmake2} program which was previously described in Section |
\texttt{genmake2} program which was previously described in Section |
23 |
\ref{sect:buildingCode}. The options are as follows: |
\ref{sec:buildingCode}. The options are as follows: |
24 |
\begin{enumerate} |
\begin{enumerate} |
25 |
\item Setting the \texttt{genamake2} options \texttt{--enable PKG} |
\item Setting the \texttt{genamake2} options \texttt{--enable PKG} |
26 |
and/or \texttt{--disable PKG} specifies inclusion or exclusion. |
and/or \texttt{--disable PKG} specifies inclusion or exclusion. |
41 |
automatically obtains all packages in that group. |
automatically obtains all packages in that group. |
42 |
|
|
43 |
\item By default (that is, if a \texttt{packages.conf} file is not |
\item By default (that is, if a \texttt{packages.conf} file is not |
44 |
found), the \texttt{genmake2} program will use the contents of the |
found), the \texttt{genmake2} program will use the |
45 |
\texttt{pkg/pkg\_default} file to obtain a list of packages. |
package group default ``\texttt{default\_pkg\_list}'' as defined |
46 |
|
in \texttt{pkg/pkg\_groups} file. |
47 |
|
|
48 |
\item To help prevent users from creating unusable package groups, the |
\item To help prevent users from creating unusable package groups, the |
49 |
\texttt{genmake2} program will parse the contents of the |
\texttt{genmake2} program will parse the contents of the |
80 |
still be aware of the dependency. |
still be aware of the dependency. |
81 |
|
|
82 |
|
|
83 |
\section{Package Coding Standards} |
\subsection{Package Coding Standards} |
84 |
|
|
85 |
The following sections describe how to modify and/or create new MITgcm |
The following sections describe how to modify and/or create new MITgcm |
86 |
packages. |
packages. |
87 |
|
|
88 |
\subsection{Packages are Not Libraries} |
\subsubsection{Packages are Not Libraries} |
89 |
|
|
90 |
To a beginner, the MITgcm packages may resemble libraries as used in |
To a beginner, the MITgcm packages may resemble libraries as used in |
91 |
myriad software projects. While future versions are likely to |
myriad software projects. While future versions are likely to |
229 |
|
|
230 |
#ifdef ALLOW_${PKG} |
#ifdef ALLOW_${PKG} |
231 |
if ( use${Pkg} ) |
if ( use${Pkg} ) |
232 |
& CALL ${PKG}_DIAGS( ) |
& CALL ${PKG}_OUTPUT( ) |
233 |
#endif |
#endif |
234 |
|
|
235 |
7. S/R PACKAGES_WRITE_PICKUP() |
7. S/R PACKAGES_WRITE_PICKUP() |
241 |
} |
} |
242 |
|
|
243 |
|
|
244 |
\subsubsection{Package Startup or Boot Sequence} |
\subsubsection{Adding a package to PARAMS.h and packages\_boot()} |
245 |
|
|
246 |
|
An MITgcm package directory contains all the code needed for that package apart |
247 |
|
from one variable for each package. This variable is the {\it use\$\{Pkg\} } |
248 |
|
flag. This flag, which is of type logical, {\bf must} be declared in the |
249 |
|
shared header file {\it PARAMS.h} in the {\it PARM\_PACKAGES} block. This |
250 |
|
convention is used to support a single runtime control file {\it data.pkg} |
251 |
|
which is read by the startup routine {\it packages\_boot()} and that sets a |
252 |
|
flag controlling the runtime use of a package. This routine needs to be able to |
253 |
|
read the flags for packages that were not built at compile time. Therefore |
254 |
|
when adding a new package, in addition to creating the per-package directory |
255 |
|
in the {\it pkg/} subdirectory a developer should add a {\it use\$\{Pkg\} } |
256 |
|
flag to {\it PARAMS.h} and a {\it use\$\{Pkg\} } entry to the |
257 |
|
{\it packages\_boot()} {\it PACKAGES} namelist. |
258 |
|
The only other package specific code that should appear outside the individual |
259 |
|
package directory are calls to the specific package API. |
260 |
|
|
261 |
|
|