--- manual/s_getstarted/text/getting_started.tex 2006/06/30 15:56:52 1.39 +++ 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.39 2006/06/30 15:56:52 molod 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} \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 @@ -92,19 +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} \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} @@ -139,7 +143,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} . @@ -148,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} @@ -162,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 @@ -208,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 @@ -219,11 +223,11 @@ 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: -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} \begin{verbatim} http://mitgcm.org/download/ \end{verbatim} @@ -276,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) @@ -300,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. @@ -311,7 +315,7 @@ \end{itemize} \section[Building MITgcm]{Building the code} -\label{sect:buildingCode} +\label{sec:buildingCode} \begin{rawhtml} \end{rawhtml} @@ -320,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. @@ -395,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/* . @@ -409,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 @@ -513,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 @@ -595,6 +613,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: @@ -617,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. @@ -656,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 @@ -698,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 @@ -713,9 +726,9 @@ \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} + href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/"> \end{rawhtml} \begin{center} \texttt{MITgcm/tools/build\_options/} @@ -748,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 @@ -766,14 +779,21 @@ 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} + href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/"> + \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 - http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm\_contrib/test\_scripts/ } + http://mitgcm.org/viewvc/MITgcm/MITgcm\_contrib/test\_scripts/ } \begin{rawhtml} \end{rawhtml} \end{enumerate} @@ -795,12 +815,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.