--- manual/s_getstarted/text/getting_started.tex	2010/01/22 00:38:16	1.41
+++ manual/s_getstarted/text/getting_started.tex	2011/05/11 18:58:02	1.45
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.41 2010/01/22 00:38:16 jmc Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.45 2011/05/11 18:58:02 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}
 <!-- CMIREDIR:whereToFindInfo: -->
 \end{rawhtml}
@@ -29,7 +29,7 @@
 \begin{rawhtml} </A> \end{rawhtml}
 
 \section{Obtaining the code}
-\label{sect:obtainingCode}
+\label{sec:obtainingCode}
 \begin{rawhtml}
 <!-- CMIREDIR:obtainingCode: -->
 \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
@@ -92,20 +92,23 @@
 
 To obtain the latest sources type:
 \begin{verbatim}
-% cvs co MITgcm
+% cvs co -P MITgcm
 \end{verbatim}
 or to get a specific release type:
 \begin{verbatim}
-% cvs co -P -r checkpoint52i_post  MITgcm
+% cvs co -P -r checkpoint52i_post MITgcm
 \end{verbatim}
+The CVS command ``\texttt{cvs co}'' is the abreviation of the full-name
+``\texttt{cvs checkout}'' command and using the option ``-P'' (\texttt{cvs co -P})
+will prevent to download unnecessary empty directories.
+
 The MITgcm web site contains further directions concerning the source
 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} <A href="http://mitgcm.org/download" target="idontexist"> \end{rawhtml}
 \begin{rawhtml} <A href="http://mitgcm.org/viewvc/MITgcm/MITgcm/" target="idontexist"> \end{rawhtml}
 \begin{verbatim}
-http://mitgcm.org/source_code.html
+http://mitgcm.org/viewvc/MITgcm/MITgcm/
 \end{verbatim}
 \begin{rawhtml} </A> \end{rawhtml}
 
@@ -149,7 +152,7 @@
 \texttt{-d DIRNAME} option.  However, the \texttt{MITgcm} directories
 they create can be changed to a different name following the check-out:
 \begin{verbatim}
-   %  cvs co MITgcm_verif_basic
+   %  cvs co -P MITgcm_verif_basic
    %  mv MITgcm MITgcm_verif_basic
 \end{verbatim}
 
@@ -163,7 +166,7 @@
 \end{verbatim}
 and then issue the cvs update command such as:
 \begin{verbatim}
-% cvs -q update -r checkpoint52i_post -d -P
+% cvs -q update -d -P -r checkpoint52i_post
 \end{verbatim}
 This will update the ``tag'' to ``checkpoint52i\_post'', add any new
 directories (-d) and remove any empty directories (-P). The -q option
@@ -209,7 +212,7 @@
 latest code'' and we haven't made a ``tag'' or ``release'' since that
 patch then you'll need to get the latest code:
 \begin{verbatim}
-% cvs -q update -A -d -P
+% cvs -q update -d -P -A
 \end{verbatim}
 Unlike, the ``check-out'' and ``update'' procedures above, there is no
 ``tag'' or release name. The -A tells CVS to upgrade to the
@@ -220,7 +223,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 +280,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 +304,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 +315,7 @@
 \end{itemize}
 
 \section[Building MITgcm]{Building the code}
-\label{sect:buildingCode}
+\label{sec:buildingCode}
 \begin{rawhtml}
 <!-- CMIREDIR:buildingCode: -->
 \end{rawhtml}
@@ -321,7 +324,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 +399,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 +413,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 +517,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 +613,8 @@
 \begin{rawhtml} </A> \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 +637,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 +686,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 +711,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 +726,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} <A
     href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">
   \end{rawhtml}
@@ -749,7 +761,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
@@ -803,12 +815,12 @@
 \end{verbatim} }
 
 \section[Running MITgcm]{Running the model in prognostic mode}
-\label{sect:runModel}
+\label{sec:runModel}
 \begin{rawhtml}
 <!-- CMIREDIR:runModel: -->
 \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.
 
