--- manual/s_getstarted/text/getting_started.tex 2010/01/21 19:20:08 1.40
+++ manual/s_getstarted/text/getting_started.tex 2010/08/30 23:09:20 1.44
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.40 2010/01/21 19:20:08 jmc Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.44 2010/08/30 23:09:20 jmc Exp $
% $Name: $
%\section{Getting started}
@@ -14,7 +14,7 @@
\ref{chap:sarch}.
\section{Where to find information}
-\label{sect:whereToFindInfo}
+\label{sec:whereToFindInfo}
\begin{rawhtml}
\end{rawhtml}
@@ -29,7 +29,7 @@
\begin{rawhtml} \end{rawhtml}
\section{Obtaining the code}
-\label{sect:obtainingCode}
+\label{sec:obtainingCode}
\begin{rawhtml}
\end{rawhtml}
@@ -63,7 +63,7 @@
\end{enumerate}
\subsection{Method 1 - Checkout from CVS}
-\label{sect:cvs_checkout}
+\label{sec:cvs_checkout}
If CVS is available on your system, we strongly encourage you to use it. CVS
provides an efficient and elegant way of organizing your code and keeping
@@ -102,10 +102,9 @@
code and CVS. It also contains a web interface to our CVS archive so
that one may easily view the state of files, revisions, and other
development milestones:
-%\begin{rawhtml} \end{rawhtml}
\begin{rawhtml} \end{rawhtml}
\begin{verbatim}
-http://mitgcm.org/source_code.html
+http://mitgcm.org/viewvc/MITgcm/MITgcm/
\end{verbatim}
\begin{rawhtml} \end{rawhtml}
@@ -140,7 +139,7 @@
the files in \texttt{CVS}! You can also use CVS to download code
updates. More extensive information on using CVS for maintaining
MITgcm code can be found
-\begin{rawhtml} \end{rawhtml}
+\begin{rawhtml} \end{rawhtml}
here
\begin{rawhtml} \end{rawhtml}
.
@@ -220,7 +219,7 @@
with. So please be sure you understand what you're doing.
\subsection{Method 2 - Tar file download}
-\label{sect:conventionalDownload}
+\label{sec:conventionalDownload}
If you do not have CVS on your system, you can download the model as a
tar file from the web site at:
@@ -277,7 +276,7 @@
package corresponds to a subdirectory. For example, \texttt{gmredi}
contains the code related to the Gent-McWilliams/Redi scheme,
\texttt{aim} the code relative to the atmospheric intermediate
- physics. The packages are described in detail in chapter \ref{chap.packagesI}.
+ physics. The packages are described in detail in chapter \ref{chap:packagesI}.
\item \texttt{tools}: this directory contains various useful tools.
For example, \texttt{genmake2} is a script written in csh (C-shell)
@@ -301,7 +300,7 @@
decompositions.
\item \texttt{verification}: this directory contains the model
- examples. See section \ref{sect:modelExamples}.
+ examples. See section \ref{sec:modelExamples}.
\item \texttt{jobs}: contains sample job scripts for running MITgcm.
@@ -312,7 +311,7 @@
\end{itemize}
\section[Building MITgcm]{Building the code}
-\label{sect:buildingCode}
+\label{sec:buildingCode}
\begin{rawhtml}
\end{rawhtml}
@@ -321,7 +320,7 @@
file (\texttt{Makefile}) that allows us to pre-process source files,
specify compiler and optimization options and also figures out any
file dependencies. We supply a script (\texttt{genmake2}), described
-in section \ref{sect:genmake}, that automatically creates the
+in section \ref{sec:genmake}, that automatically creates the
\texttt{Makefile} for you. You then need to build the dependencies and
compile the code.
@@ -396,7 +395,7 @@
number of CPUs available.
Now you are ready to run the model. General instructions for doing so are
-given in section \ref{sect:runModel}. Here, we can run the model by
+given in section \ref{sec:runModel}. Here, we can run the model by
first creating links to all the input files:
\begin{verbatim}
ln -s ../input/* .
@@ -410,7 +409,7 @@
\subsection{Building/compiling the code elsewhere}
-In the example above (section \ref{sect:buildingCode}) we built the
+In the example above (section \ref{sec:buildingCode}) we built the
executable in the {\em input} directory of the experiment for
convenience. You can also configure and compile the code in other
locations, for example on a scratch disk with out having to copy the
@@ -514,16 +513,30 @@
\subsection{Using \texttt{genmake2}}
-\label{sect:genmake}
+\label{sec:genmake}
To compile the code, first use the program \texttt{genmake2} (located
in the \texttt{tools} directory) to generate a Makefile.
\texttt{genmake2} is a shell script written to work with all
``sh''--compatible shells including bash v1, bash v2, and Bourne.
-Internally, \texttt{genmake2} determines the locations of needed
-files, the compiler, compiler options, libraries, and Unix tools. It
-relies upon a number of ``optfiles'' located in the
-\texttt{tools/build\_options} directory.
+%Internally, \texttt{genmake2} determines the locations of needed
+%files, the compiler, compiler options, libraries, and Unix tools. It
+%relies upon a number of ``optfiles'' located in the
+%\texttt{tools/build\_options} directory.
+\texttt{genmake2} parses information from the following sources:
+\begin{description}
+\item[-] a {\em gemake\_local} file if one is found in the current
+ directory
+\item[-] command-line options
+\item[-] an "options file" as specified by the command-line option
+ \texttt{--optfile=/PATH/FILENAME}
+\item[-] a {\em packages.conf} file (if one is found) with the
+ specific list of packages to compile. The search path for
+ file {\em packages.conf} is, first, the current directory and
+ then each of the "MODS" directories in the given order (see below).
+\end{description}
+
+\subsubsection{Optfiles in \texttt{tools/build\_options} directory:}
The purpose of the optfiles is to provide all the compilation options
for particular ``platforms'' (where ``platform'' roughly means the
@@ -596,6 +609,8 @@
\begin{rawhtml} \end{rawhtml}
mailing list.
+\subsubsection{Command-line options:}
+
In addition to the optfiles, \texttt{genmake2} supports a number of
helpful command-line options. A complete list of these options can be
obtained from:
@@ -618,21 +633,31 @@
the user's path. When these three items have been identified,
genmake2 will try to find an optfile that has a matching name.
-\item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default
- set of packages to be used. The normal order of precedence for
- packages is as follows:
- \begin{enumerate}
- \item If available, the command line (\texttt{--pdefault}) settings
- over-rule any others.
-
- \item Next, \texttt{genmake2} will look for a file named
- ``\texttt{packages.conf}'' in the local directory or in any of the
- directories specified with the \texttt{--mods} option.
-
- \item Finally, if neither of the above are available,
- \texttt{genmake2} will use the \texttt{/pkg/pkg\_default} file.
- \end{enumerate}
+\item[\texttt{--mods='DIR1 DIR2 DIR3 ...'}] specifies a list of
+ directories containing ``modifications''. These directories contain
+ files with names that may (or may not) exist in the main MITgcm
+ source tree but will be overridden by any identically-named sources
+ within the ``MODS'' directories.
+ The order of precedence for this "name-hiding" is as follows:
+ \begin{itemize}
+ \item ``MODS'' directories (in the order given)
+ \item Packages either explicitly specified or provided by default
+ (in the order given)
+ \item Packages included due to package dependencies (in the order
+ that that package dependencies are parsed)
+ \item The "standard dirs" (which may have been specified by the
+ ``-standarddirs'' option)
+ \end{itemize}
+
+\item[\texttt{--pgroups=/PATH/FILENAME}] specifies the file
+ where package groups are defined. If not set, the package-groups
+ definition will be read from {\em pkg/pkg\_groups}.
+ It also contains the default list of packages (defined
+ as the group ``{\it default\_pkg\_list}'' which is used
+ when no specific package list ({\em packages.conf})
+ is found in current directory or in any "MODS" directory.
+
\item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file
used for packages.
@@ -657,26 +682,9 @@
"STAF" compiler. As with any compilers, it is helpful to have their
directories listed in your {\tt \$PATH} environment variable.
-\item[\texttt{--mods='DIR1 DIR2 DIR3 ...'}] specifies a list of
- directories containing ``modifications''. These directories contain
- files with names that may (or may not) exist in the main MITgcm
- source tree but will be overridden by any identically-named sources
- within the ``MODS'' directories.
-
- The order of precedence for this "name-hiding" is as follows:
- \begin{itemize}
- \item ``MODS'' directories (in the order given)
- \item Packages either explicitly specified or provided by default
- (in the order given)
- \item Packages included due to package dependencies (in the order
- that that package dependencies are parsed)
- \item The "standard dirs" (which may have been specified by the
- ``-standarddirs'' option)
- \end{itemize}
-
\item[\texttt{--mpi}] This option enables certain MPI features (using
CPP \texttt{\#define}s) within the code and is necessary for MPI
- builds (see Section \ref{sect:mpi-build}).
+ builds (see Section \ref{sec:mpi-build}).
\item[\texttt{--make=/path/to/gmake}] Due to the poor handling of
soft-links and other bugs common with the \texttt{make} versions
@@ -699,7 +707,7 @@
\subsection{Building with MPI}
-\label{sect:mpi-build}
+\label{sec:mpi-build}
Building MITgcm to use MPI libraries can be complicated due to the
variety of different MPI implementations available, their dependencies
@@ -714,7 +722,7 @@
\item Determine the locations of your MPI-enabled compiler and/or MPI
libraries and put them into an options file as described in Section
- \ref{sect:genmake}. One can start with one of the examples in:
+ \ref{sec:genmake}. One can start with one of the examples in:
\begin{rawhtml}
\end{rawhtml}
@@ -749,7 +757,7 @@
\end{itemize}
\item Build the code with the \texttt{genmake2} \texttt{-mpi} option
- (see Section \ref{sect:genmake}) using commands such as:
+ (see Section \ref{sec:genmake}) using commands such as:
{\footnotesize \begin{verbatim}
% ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE
% make depend
@@ -767,10 +775,17 @@
library and a job scheduling and queueing system such as PBS,
LoadLeveller, Condor, or any of a number of similar tools. A few
example scripts (those used for our \begin{rawhtml} \end{rawhtml}regular
+ href="http://mitgcm.org/public/testing.html"> \end{rawhtml}regular
verification runs\begin{rawhtml} \end{rawhtml}) are available
at:
\begin{rawhtml}
+ \end{rawhtml}
+ {\footnotesize \tt
+ http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example\_scripts/ }
+ \begin{rawhtml} \end{rawhtml}
+ or at:
+ \begin{rawhtml}
\end{rawhtml}
{\footnotesize \tt
@@ -796,12 +811,12 @@
\end{verbatim} }
\section[Running MITgcm]{Running the model in prognostic mode}
-\label{sect:runModel}
+\label{sec:runModel}
\begin{rawhtml}
\end{rawhtml}
-If compilation finished succesfully (section \ref{sect:buildingCode})
+If compilation finished succesfully (section \ref{sec:buildingCode})
then an executable called \texttt{mitgcmuv} will now exist in the
local directory.