/[MITgcm]/MITgcm/doc/devel_HOWTO.sgml
ViewVC logotype

Diff of /MITgcm/doc/devel_HOWTO.sgml

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.3 by edhill, Thu Aug 28 22:44:00 2003 UTC revision 1.16 by jmc, Sun Apr 24 00:04:40 2011 UTC
# Line 1  Line 1 
1  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   
 <article id="MITgcm-Development-HOWTO">  
   
2  <!--  <!--
3  Build commands:   $Header$
4    db2ps -d ldp.dsl devel_HOWTO.sgml   $Name$
   db2pdf -d ldp.dsl devel_HOWTO.sgml  
   db2html -d ./ldp.dsl devel_HOWTO.sgml  
   db2html -u -d ./ldp.dsl devel_HOWTO.sgml  
5  -->  -->
6    
7    <article id="MITgcm-Development-HOWTO">
8    
9    <articleinfo>    <articleinfo>
10      <title>MITgcm Development HOWTO</title>      <title>MITgcm Development HOWTO</title>
11    
# Line 30  Build commands: Line 26  Build commands:
26            Initial version.            Initial version.
27          </revremark>          </revremark>
28        </revision>        </revision>
29          <revision>
30            <revnumber>0.02</revnumber>
31            <date>2010-01-21</date>
32            <authorinitials>jmc</authorinitials>
33            <revremark>
34              Update links.
35            </revremark>
36          </revision>
37          <revision>
38            <revnumber>0.03</revnumber>
39            <date>2010-04-25</date>
40            <authorinitials>jmc</authorinitials>
41            <revremark>
42              Add subsection "Developer settings" (under CVS Repository).
43            </revremark>
44          </revision>
45          <revision>
46            <revnumber>0.04</revnumber>
47            <date>2011-04-24</date>
48            <authorinitials>jmc</authorinitials>
49            <revremark>
50              Update subsection "The verification suite".
51            </revremark>
52          </revision>
53      </revhistory>      </revhistory>
54    
55      <abstract>      <abstract>
# Line 45  Build commands: Line 65  Build commands:
65      <sect2>      <sect2>
66        <title>New Versions of This Document</title> <para>You can        <title>New Versions of This Document</title> <para>You can
67        obtain the latest version of this document <ulink        obtain the latest version of this document <ulink
68        url="http://mitgcm.org/dev_docs/devel_HOWTO/">online</ulink> in        url="http://mitgcm.org/public/docs.html">online</ulink> in
69        various formats.</para>        various formats.</para>
70      </sect2>      </sect2>
71      <sect2>      <sect2>
# Line 63  Build commands: Line 83  Build commands:
83      <sect2>      <sect2>
84        <title>User Manual</title>        <title>User Manual</title>
85    
86        <para>Before jumping into        <para>Before jumping into development, please familiarize yourself with
87        development, please familiarize yourself with the MITgcm user          the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
88        manual which is available <ulink          </ulink>.  This document contains volumes of useful information and is
89        url="http://mitgcm.org/">on the main web page</ulink>.  This          included here by reference.</para>
       document contains volumes of useful information and is included  
       here by reference.</para>  
90    
91        <para>Also, a "snapshot" or<ulink        <!--
92          <para>Also, a "snapshot" or <ulink
93        url="http://mitgcm.org/dev_docs/">development version</ulink> of        url="http://mitgcm.org/dev_docs/">development version</ulink> of
94        the user manual may be available, though this is only put on the        the user manual may be available, though this is only put on the
95        web for testing purposes.</para>        web for testing purposes.</para>
96          -->
97      </sect2>      </sect2>
98    
99      <sect2>      <sect2>
# Line 102  Build commands: Line 122  Build commands:
122    
123    <sect1 id="cvs">    <sect1 id="cvs">
124      <title>CVS Repository</title>      <title>CVS Repository</title>
125    
126      <sect2>      <sect2>
127        <title>Layout</title>        <title>Layout</title>
128    
# Line 112  Build commands: Line 133  Build commands:
133        others.  The tree currently resembles:</para>        others.  The tree currently resembles:</para>
134    
135  <programlisting>gcmpack/  <programlisting>gcmpack/
136    MITgcm-contrib        contributed code    CVSROOT               -hidden-
   CS-regrid             goes into utils  
   cvspolicy.html        -save-  
   CVSROOT               -save-  
   development           experimental stuff  
   manual                -save-  
   misc                  -?-  
137    
138    MITgcm                code    MITgcm                code
139         adjoint                  fold into genmake         bin                      empty
140         bin                      stub for ecco build         doc                      basic developpment documentation
141         compare01                old from 20th century         eesupp                   execution environment support code (wrapper)
142         diags                    timeave f77 in pkgs now         exe                      empty
143         doc                      tags -- connect to real docs?         jobs                     runtime shell scripts for
144         eesupp                   cnh?                                    various platforms (not maintained)
145         exe                      ecco user build         lsopt                    line search
146      *- jobs                     runtime shell scripts for         model                    main dynamics (core)
147      |                             various platforms         optim                    line search interface
148      |  lsopt                    line search         pkg                      alternate and optional numerics, etc.
149     m|  model                    main dynamics (core)         tools                    scripts to build (and test)
150     e|    optimization_drivers   ?         utils                    pre/post processing tools (matlab, ..)
151     r|  optim                    line search interface         verification             standard regression tests + examples
152     g|  pkg                      alternate and optional numerics, etc.                                        + documented examples (tutorials)
153     e*- tools         tutorial_examples        (only in release1 branch)
    ?|  tutorial_examples        documented tests  
     |                             only populated on release1 branch  
     |                             and not validated during "testscript"  
     *- utils  
        verification             std tests  
154    
155      MITgcm_contrib        contributed code
156    
157    mitgcmdoc -> manual   -remove-    acesgrid.org          build acesgrid web site
158      development           experimental stuff
159      gfd_lab               -?-
160      manual                source of MITgcm documentation
161    mitgcm.org            build web site    mitgcm.org            build web site
162    models                -?-    old_develop           old and early development source
163    packages              -?-         misc                 -?-
164    preprocess            -?-         models               -?-
165    tmp                   -?-         packages             -?-
166           preprocess           -?-
167      pdfs                  some pdfs
168      planetinabottle.org   unfinished web site
169      www.ecco-group.org    build ecco web site ?
170  </programlisting>  </programlisting>
171    
172     <!--
173        <para>Efforts are underway to reduce the complexity.</para>        <para>Efforts are underway to reduce the complexity.</para>
174    -->
175    
176      </sect2>      </sect2>
177    
# Line 190  Build commands: Line 210  Build commands:
210        <title>Branches</title>        <title>Branches</title>
211    
212        <para>As shown in the online <ulink        <para>As shown in the online <ulink
213        url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">ViewCVS-generated        url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?view=graph">
214        tree</ulink>, the MITgcm codebase is split into to two branches        ViewCVS-generated tree</ulink>, the MITgcm codebase is split into
215        or "lines" under which development proceeds.  These two lines        branches or "lines" under which development proceeds.  The main line
216        are referred to as the "MAIN" and "ecco" versions of the code.        of development is referred to as the "MAIN" version of the code.
       While not identical, the bulk of the MAIN and ecco lines are  
       composed of files from the same codebase.  
217        </para>        </para>
218    
219        <para>Periodically, a "Release" branch is formed from the "MAIN"        <para>Periodically, a "Release" branch is formed from the "MAIN"
220        development branch.  This is done in order to create a        development branch.  This is done in order to create a relatively stable
221        relatively stable reference point for both users and developers.        reference point for both users and developers.  The intent is that once a
222        The intent is that once a relese branch has been created, only        release branch has been created, only bug-fixes will be added to it.
223        bug-fixes will be added to it.  Meanwhile, development (which        Meanwhile, development (which might "break" or otherwise render invalid
224        might "break" or otherwise render invalid the documentation,        the documentation, tutorials, and/or examples contained within a release
225        tutorials, and/or examples contained within a release branch) is        branch) is allowed to continue along the MAIN line.</para>
       allowed to continue along the MAIN and ecco lines.</para>  
226      </sect2>      </sect2>
227    
228      <sect2>      <sect2>
229        <title>Tagging</title>        <title> Developer settings </title>
   
       <para>The intent of tagging is to create "known-good"  
       checkpoints that developers can use as references.  
       Traditionally, MITgcm tagging has maintained the following  
       conventions:</para>  
230    
231          <para>CVS is a convenient tool to keep up-to-date a personal copy of the
232          MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html">
233          using CVS </ulink>). The same tool is used by developers to
234          incorporate any change into the repository. However, this later
235          function requires specific settings, as detailed here after:</para>
236        <orderedlist>        <orderedlist>
237          <listitem>          <listitem>
238            <para>Developer checks out code into a local CVS-managed            <para> You will need an account (loggin access) to the server
239            directory, makes various changes/additions, tests these             "mitgcm.org" with the proper group setting (e.g.,
240            edits, and eventually reaches a point where (s)he is              group "gcmctrb" to add/modify code into MITgcm_contrib).
241            satisfied that the changes form a new "useful" point in the              This kind of account is granted only upon well motivated request.
242            evolution of the code.</para>              The access to the server mitgcm.org is through ssh-key authorization
243                which will need to be set properly on both side (on your local machine
244                and on your server account). You need to be able to
245                to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename>
246                in case of different user-name on both sides) to proceed further.</para>
247            </listitem>
248    
249            <listitem>
250              <para> You need to register to the
251            <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs">
252          mitgcm-cvs </ulink> mailing list.
253              This ensures that other developers will receive email notification
254               when you make changes; you will also receive as well such email
255               when others make changes to the repository.
256              </para>
257            </listitem>
258    
259            <listitem>
260              <para> It is highly recommended that you register also to the
261            <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel">
262          mitgcm-devel </ulink> mailing list (expect a short delay for
263           this request to be processed).
264              This list is intended for developer discussions.
265              </para>
266            </listitem>
267    
268            <listitem>
269              <para> The standard anonymous mode (using "cvsanon", as mentionned
270            <ulink url="http://mitgcm.org/public/source_code.html">
271          here </ulink>) does not allow check-in ("cvs commit") permission.
272             Instead, you will need to set our CVS environment as follow:</para>
273    <screen>
274      $ export CVS_RSH=ssh
275      $ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
276    </screen>
277              <para> After downloading a directory, e.g.: <filename>myCopy</filename>,
278               from the CVS repository (e.g.,
279                <filename>MITgcm_contrib/thisPart</filename>) using the command:</para>
280    <screen>
281      $ cvs co -P -d myCopy MITgcm_contrib/thisPart
282    </screen>
283              <para> the type of CVS environment which has been used
284               is stored in the file <filename>myCopy/CVS/Root</filename>
285               and makes it difficult to re-use, for cvs-commit purpose,
286               a cvs local copy (<filename>myCopy</filename>) which was obtained
287               using the CVS anonymous mode.</para>
288            </listitem>
289    
290            <listitem>
291              <para> At this stage, you should be able to send your modified source
292              file (e.g., <filename>src_file</filename>) from your local copy directory
293              (<filename>myCopy</filename>) to the CVS repository
294              (<filename>MITgcm_contrib/thisPart</filename>) using the command
295              "cvs commit":</para>
296    <screen>
297      $ cd myCopy
298      $ cvs -n update        (optional; check if new changes have been made)
299      $ cvs diff src_file    (optional; list your changes)
300      $ cvs commit src_file
301    </screen>
302              <para> It is essential that you provide a short description of the
303              changes you made to <filename>src_file</filename> as you check-in
304              this file (the "cvs commit" command automatically opens your standard
305              editor for this purpose).</para>
306            </listitem>
307    
308          </orderedlist>
309    
310        </sect2>
311    
312        <sect2>
313          <title>Main code development</title>
314          <para><emphasis>(formerly named "Tagging" ; this section needs an update)
315            </emphasis></para>
316    
317          <para>The intent of tagging is to create "known-good" checkpoints that
318          developers can use as references.  Traditionally, MITgcm tagging has
319          maintained the following conventions:</para>
320    
321          <orderedlist>
322            <listitem>
323              <para>Developer checks out code into a local CVS-managed directory,
324              makes various changes/additions, tests these edits, and eventually
325              reaches a point where (s)he is satisfied that the changes form a new
326              "useful" point in the evolution of the code.</para>
327          </listitem>          </listitem>
328    
329          <listitem>          <listitem>
330            <para>The developer then runs the <ulink            <para>The developer then runs the <ulink
331            url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">testscript</ulink>            url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
332            shell script to see if any problems are introduced.  While            testreport</ulink> shell script to see if any problems are introduced.
333            not intended to be exhaustive, the test cases within the            While not intended to be exhaustive, the test cases within the
334            verification directory do provide some indication whether            verification directory do provide some indication whether gross errors
335            gross errors have been introduced.            have been introduced.
336            </para>            </para>
337          </listitem>          </listitem>
338    
# Line 241  Build commands: Line 342  Build commands:
342            then:</para>            then:</para>
343            <orderedlist>            <orderedlist>
344              <listitem>              <listitem>
345                <para>adds a "checkpointXY_pre" comment (where X is a                <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
346                checkpoint number and Y is a letter) to the <ulink                number and Y is a letter) to the <ulink
347                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">tag-index</ulink>                url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">
348                file and checks it into the CVS repository</para>                tag-index</ulink> file and checks it into the CVS
349                  repository</para>
350              </listitem>              </listitem>
351              <listitem>              <listitem>
352                <para>submits the set of changes to the CVS repository                <para>submits the set of changes to the CVS repository and adds
353                and adds comments to <filename>tag-index</filename>                comments to <filename>tag-index</filename> describing what the
354                describing what the changes are along with a matching                changes are along with a matching "checkpointXY_post" entry</para>
               "checkpointXY_post" entry</para>  
355              </listitem>              </listitem>
356            </orderedlist>            </orderedlist>
357          </listitem>          </listitem>
358        </orderedlist>        </orderedlist>
359    
360        <para>The result of this tagging procedure is a sequence of        <para>The result of this tagging procedure is a sequence of development
361        development checkpoints with comments which resembles:</para>        checkpoints with comments which resembles:</para>
362    
363  <programlisting>  <programlisting>
364  checkpoint50e_post  checkpoint50e_post
365  o make KPP work with PTRACERS  o make KPP work with PTRACERS
366   - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is   - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is
367     nearly a copy of kpp_transport_s     nearly a copy of kpp_transport_s
368   - there is no analogue to SurfaceTendencyS, so I have to use   - there is no analogue to SurfaceTendencyS, so I have to use
369     gPtr(of the surface layer) instead     gPtr(of the surface layer) instead
370  o add a new platform SunFire+mpi (SunFire 15000) to genmake  o add a new platform SunFire+mpi (SunFire 15000) to genmake
371  checkpoint50e_pre  checkpoint50e_pre
372    
373  checkpoint50d_post  checkpoint50d_post
374  o change kpp output from multiple-record state files to single-record state  o change kpp output from multiple-record state files to single-record state
375    files analogous to write_state.F    files analogous to write_state.F
376  o reduce the output frequency of cg3d-related stuff to the monitor frequency,  o reduce the output frequency of cg3d-related stuff to the monitor frequency,
377    analogous to the cg2d-related output.    analogous to the cg2d-related output.
378  o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,  o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
379    so that writing to internal file fn (with length 512) fails.    so that writing to internal file fn (with length 512) fails.
380  checkpoint50d_pre  checkpoint50d_pre
381  </programlisting>  </programlisting>
382    
383        <para>This information can be used to refer to various stages of        <para>This information can be used to refer to various stages of the code
384        the code development.  For example, bugs can be traced to        development.  For example, bugs can be traced to individual sets of CVS
385        individual sets of CVS checkins based upon their first        checkins based upon their first appearance when comparing the results from
386        appearance when comparing the results from different        different checkpoints.</para>
       checkpoints.</para>  
387    
388      </sect2>      </sect2>
389    </sect1>    </sect1>
390    
391    
   <sect1 id="documentation">  
     <title>Editing the Documentation</title>  
   
     <sect2 id="documentation_getting">  
       <title>Getting the Docs and Code</title>  
   
       <para>The first step towards editing the documentation is to  
       checkout a copy of code, docs, and build scripts from the CVS  
       server using:</para>  
   
 <screen>  
 $ export CVS_RSH=ssh  
 $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'  
 $ mkdir scratch  
 $ cvs co MITgcm manual mitgcm.org  
 </screen>  
   
       <para>These commands extract the necessary information from the  
       CVS server and create a temporary (called  
       <filename>scratch</filename>) directory for the storage of the  
       HTML and other files that will be created.  Please note that you  
       must either create <filename>scratch</filename> as shown or edit  
       the various <filename>Makefile</filename>s and scripts used to  
       create the documentation.</para>  
     </sect2>  
   
     <sect2>  
       <title>Editing</title>  
   
       <para>The documentation is contained in the  
       <filename>manual</filename> directory in a raw LaTeX format.  
       The main document is <filename>manual.tex</filename> and it uses  
       <command>\input{}</command>s to include the chapters and  
       subsections.</para>  
   
       <para>Since the same LaTeX source is used to produce PostScript,  
       PDF, and HTML output, care should be taken to follow certain  
       conventions.  Two of the most important are the usage of the  
       <command>\filelink{}{}</command> and  
       <command>\varlink{}{}</command> commands.  Both of these  
       commands have been defined to simplify the connection between  
       the automatically generated ("code browser") HTML and the HTML  
       version of the manual produced by LaTeX2HTML.  They each take  
       two arguments (corresponding to the contents of the two sets of  
       curly braces) which are the text that the author wishes to be  
       "wrapped" within the link, and a specially formatted link thats  
       relative to the <filename>MITgcm</filename> directory within the  
       CVS tree.</para>  
   
       <para>The result is a command that resembles either</para>  
         
       <orderedlist>  
         <listitem>  
           <para>a reference to a variable or subroutine name such as  
           <command>\varlink{tRef}{tRef}</command>, or </para>  
         </listitem>  
   
         <listitem>  
           <para>a reference to a file such as  
               <command>\varlink{tRef}{path-to-the-file_name.F}</command>  
               where the absolute path to the file is of the form  
               <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>  
               <para>(please note how the leading "/foo/MITgcm"  
               component of the path is dropped leaving the path  
               <emphasis>relative</emphasis> to the head of the code  
               directory and each directory separator "/" is turned  
               into a "-")</para>  
         </listitem>  
       </orderedlist>  
             
   
   
     </sect2>  
   
     <sect2>  
       <title>Building</title> <para>Given the directory structure of  
       <xref linkend="documentation_getting">, the entire documentation  
       for the web site can be built using:</para>  
   
 <screen>  
 $ cd mitgcm.org/devel/buildweb  
 $ make All  
 </screen>  
   
       <para>Which builds the PDF from the LaTeX source, creates the  
       HTML output from the LaTeX source, parses the FORTRAN code base  
       to produce a hyperlinked HTML version of the source, and then  
       determines the cross-linking between the various HTML  
       components.</para>  
   
       <para>If there are no errors, the result of the build process  
       (which can take 30+ minutes on a P4/2.5Ghz) will be contained  
       within a single directory called  
       <filename>scratch/dev_docs</filename>.  This is a freshly built  
       version of the entire on-line users manual.  If you have the  
       correct permissions, it can be directly copied to the web server  
       area:</para>  
   
 <screen>  
 $ mv scratch/dev_docs /u/u0/httpd/html  
 </screen>  
   
       <para>and the update is complete.</para>  
   
     </sect2>  
   
   </sect1>  
   
392    <sect1 id="coding">    <sect1 id="coding">
393      <title>Coding for MITgcm</title>      <title>Coding for MITgcm</title>
394    
395      <sect2 id="build_tools">      <sect2 id="build_tools">
396        <title>Build Tools</title>        <title>Build Tools</title>
397    
398        <para>Many Open Source projects use the "GNU Autotools" to help        <para>Many Open Source projects use the "GNU Autotools" to help streamline
399        streamline the build process for various Unix and Unix-like          the build process for various Unix and Unix-like architectures.  For a
400        architectures.  For a user, the result is the common "configure"          user, the result is the common "configure" (that is,
401        (that is, "<filename>./configure && make && make          "<filename>./configure && make && make install</filename>") commands.
402        install</filename>") commands.  For MITgcm, the process is          For MITgcm, the process is similar.  Typical commands are:</para>
       similar.  Typical commands are:</para>  
403    
404  <screen>  <screen>
405  $ genmake -mods=../code    $ genmake2 -mods=../code
406  $ make depend    $ make depend
407  $ make    $ make
408  </screen>  </screen>
409    
410        <para>The following sections describe the individual steps in        <para>The following sections describe the individual steps in the build
411        the build process.</para>          process.</para>
412    
413        <sect3 id="genmake">        <sect3 id="genmake">
414          <title>The <filename>genmake2</> Utility</title>          <title>The <filename>genmake2</> Utility</title>
415    
416          <para><emphasis>Please note that the older          <para><emphasis>(Note: the older <filename>genmake</>
417          <filename>genmake</> is deprecated and will eventually              has been replaced by <filename>genmake2</>)</emphasis></para>
418          be replaced by <filename>genmake2</>.  This HOWTO only  
419          describes the newer tool.</emphasis></para>          <para>The first step in any MITgcm build is to create a Unix-style
420              <filename>Makefile</filename> which will be parsed by
421          <para>The first step in any MITgcm build is to create a            <filename>make</filename> to specify how to compile the MITgcm source
422          Unix-style <filename>Makefile</filename> which will be parsed            files.  For more detailed descriptions of what the make tools are and
423          by <filename>make</filename> to specify how to compile the            how they are used, please see:</para>
         MITgcm source files.  For more detailed descriptions of what  
         the make tools are and how they are used, please see:</para>  
424    
425          <itemizedlist>          <itemizedlist>
426            <listitem>            <listitem>
427              <para><ulink url="http://www.gnu.org/software/make/make.html">http://www.gnu.org/software/make/make.html</></para>              <para><ulink url="http://www.gnu.org/software/make/make.html">
428                    http://www.gnu.org/software/make/make.html</></para>
429            </listitem>            </listitem>
430            <listitem>            <listitem>
431              <para><ulink url="http://www.oreilly.com/catalog/make2/">http://www.oreilly.com/catalog/make2/</></para>              <para><ulink url="http://www.oreilly.com/catalog/make2/">
432                    http://www.oreilly.com/catalog/make2/</></para>
433            </listitem>            </listitem>
434          </itemizedlist>          </itemizedlist>
435    
436          <para>Due to the poor handling of soft-links and other bugs          <para>Genmake can often be invoked successfully with a command line as
437          common with the <filename>make</filename> versions provided by          simple as:</para>
438          commercial Unix vendors, GNU <filename>make</filename>  
439          (sometimes called <filename>gmake</filename>) should be  <screen>
440          preferred.</para>    $ genmake2 -mods=../code
441    </screen>
442          <para>As the name implies, <filename>genmake2</filename>  
443          generates a <filename>Makefile</filename>.  It does so by          <para>However, some systems (particularly commercial Unixes that lack a
444          first parsing the information supplied from the following            more modern "/bin/sh" implementation or that have shells installed in
445          sources</para>            odd locations) may require an explicit shell invocation such as one of
446              the following: </para>
447    
448    <screen>
449      $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
450      $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
451    </screen>
452    
453            <para>The genmake2 code has been written in a Bourne and BASH (v1)
454            compatible syntax so it should work with most "sh" and all recent "bash"
455            implementations.</para>
456    
457            <para>As the name implies, <filename>genmake2</filename> generates a
458              <filename>Makefile</filename>.  It does so by first parsing the
459              information supplied from the following sources</para>
460    
461          <orderedlist>          <orderedlist>
462            <listitem>            <listitem>
463              <para>a <filename>gm_local</filename> file in the current              <para>a <filename>gemake_local</filename> file in the current
464              directory</para>                directory</para>
465            </listitem>            </listitem>
466            <listitem>            <listitem>
467              <para>directly from command-line options</para>              <para>directly from command-line options</para>
468            </listitem>            </listitem>
469            <listitem>            <listitem>
470              <para>an "options file" as specified by the command-line              <para>an "options file" as specified by the command-line option
471              option <filename>-optfile='FILENAME'</filename></para>                <filename>-optfile='FILENAME'</filename></para>
472              </listitem>
473              <listitem>
474                <para> a <filename>packages.conf</filename> file (in the current
475                  directory or in one of the "MODS" directories, see below)
476                  which contains the specific list of packages to compile
477                </para>
478            </listitem>            </listitem>
479          </orderedlist>          </orderedlist>
480    
481          <para>then checking certain dependency rules (the package          <para>then checking certain dependency rules (the package dependencies),
482          dependencies), and then writing a            and finally writing a <filename>Makefile</filename> based upon the
483          <filename>Makefile</filename> based upon the source code that            source code that it finds.  For convenience within various Unix
484          it finds.  For convenience with the various Unix shells,            shells, <filename>genmake2</> supports both "long"- and "short"-style
485          <filename>genmake2</> supports both "long"- and "shor"-style            options.  A complete list of the available options can be obtained
486          options.  A complete list of the available options can be            from:</para>
         obtained from:</para>  
487    
488  <screen>  <screen>
489  $ genmake2 -help    $ genmake2 -help
490  </screen>  </screen>
491    
492          <para>The most important options for <filename>genmake2</>          <para>The most important options for <filename>genmake2</> are:</para>
         are:</para>  
493    
494          <variablelist>          <variablelist>
495    
496            <varlistentry>            <varlistentry>
497              <term><filename>--optfile=/PATH/FILENAME</></term>              <term><filename>--optfile=/PATH/FILENAME</></term>
498    
499              <listitem>              <listitem>
500                <para>This specifies the "options file" that should be                <para>This specifies the "options file" that should be used for a
501                used for a particular build.  The options file is a                  particular build.  The options file is a convenient and
502                convenient and machine-indepenent way of specifying                  machine-indepenent way of specifying parameters such as the
503                parameters such as the FORTRAN compiler                  FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
504                (<filename>FC=</>), FORTRAN compiler optimization flags                  optimization flags (<filename>FFLAGS=</>), and the locations of
505                (<filename>FFLAGS=</>), and the locations of various                  various platform- and/or machine-specific tools
506                platform- and/or machine-specific tools                  (eg. <filename>MAKEDEPEND=</>).  As with <filename>genmake2</>,
507                (eg. <filename>MAKEDEPEND=</>).  As with                  all options files should be written to be compatible with
508                <filename>genmake2</>, all options files should be                  Bourne--shell ("sh" or "BASH v1") syntax.  Examples of various
509                written a BASH v1-compatible syntax.  Examples of                  options files can be found in
510                various options files can be found in                  <filename>$ROOTDIR/tools/build_options</>.</para>
511                <filename>$ROOTDIR/tools/build_options</>.  Everyone is  
512                encouraged to submit their options files to the MITgcm                <para>If no "optfile" is specified (either through the command lin
513                project for inclusion (please send to                  or the environment variable), genmake2 will try to make a
514                <email>MITgcm-support@mitgcm.org</email>).  We are                  reasonable guess from the list provided in
515                particularly grateful for options files tested on new or                  <filename>$ROOTDIR/tools/build_options</>.  The method used for
516                unique platforms!</para>                  making this guess is to first determine the combination of
517                    operating system and hardware (eg. "linux_ia32") and then find a
518                    working Fortran compiler within the user's path.  When these
519                    three items have been identified, genmake2 will try to find an
520                    optfile that has a matching name. </para>
521    
522                  <para>Everyone is encouraged to submit their options files to the
523                    MITgcm project for inclusion (please send to
524                    <email>MITgcm-support@mitgcm.org</email>).  We are particularly
525                    grateful for options files tested on new or unique
526                    platforms!</para>
527              </listitem>              </listitem>
528    
529            </varlistentry>            </varlistentry>
530    
531            <varlistentry>            <varlistentry>
532              <term><filename>-pdepend=/PATH/FILENAME</></term>              <term><filename>-adof=/path/to/file</></term>
533                <term><filename>-adoptfile=/path/to/file</></term>
534                <listitem>
535                  <para>This option specifies the "adjoint" or automatic
536                    differentiation options file to be used.  The file is analogous
537                    to the "optfile" defined above but it specifies information for
538                    the AD build process.  The default file is located in <filename>
539                    $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
540                    defines the "TAF" and "TAMC" compilers.  An alternate version is
541                    also available at <filename>
542                    $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
543                    newer "STAF" compiler.  As with any compilers, it is helpful to
544                    have their directories listed in your $PATH environment
545                    variable.</para>
546                </listitem>
547              </varlistentry>
548    
549              <varlistentry>
550                <term><filename>-mods=DIR</></term>
551                <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
552              <listitem>              <listitem>
553                <para>This specifies the dependency file used for                <para>This option specifies a list of directories containing
554                packages.  If not specified, the default dependency file                  "modifications".  These directories contain files with names
555                is <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for                  that may (or may not) exist in the main MITgcm source tree but
556                this file is parsed on a line-by-line basis where each                  will be overridden by any identically-named sources within the
557                line containes either a comment ("#") or a simple                  "MODS" directories.  The order of precedence for this
558                "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or                  "name-hiding" is as follows:</para>
559                "-" symbol specifies a "must be used with" or a "must                <itemizedlist>
560                not be used with" relationship, respectively.  If no                  <listitem><para>"MODS" directories (in the order given)
561                rule is specified, then it is assumed that the two                    </para></listitem>
562                packages are compatible and will function either with or                  <listitem><para>Packages either explicitly specified or
563                without each other.</para>                      provided by default (in the order given)</para></listitem>
564                    <listitem><para>Packages included due to package dependencies
565                        (in the order that that package dependencies are
566                        parsed)</para></listitem>
567                    <listitem><para>The "standard dirs" (which may have been
568                        specified by the "-standarddirs" option)</para></listitem>
569                  </itemizedlist>
570              </listitem>              </listitem>
571            </varlistentry>            </varlistentry>
572    
573            <varlistentry>            <varlistentry>
574              <term><filename>-pdefault=PKG</></term>              <term><filename>-pgroups=/PATH/FILENAME</></term>
             <term><filename>-pdefault='PKG1 [PKG2 PKG3 ...]'</></term>  
575              <listitem>              <listitem>
576                <para>This option specifies the default set of packages                <para>This option specifies the file where package groups are
577                to be used.  If not set, the default package list will                defined.  If not set, the package-groups definition will
578                be read from                be read from
579                <filename>$ROOTDIR/pkg/pkg_default</>.</para>                <filename>$ROOTDIR/pkg/pkg_groups</>.</para>
580                  <para>
581                  It also contains the default list of packages (defined
582                  as the group <filename>"default_pkg_list"</>) which is used
583                  when no specific package list (file: <filename>packages.conf</>)
584                  is found in current directory or in any "MODS" directory.
585                  </para>
586                </listitem>
587              </varlistentry>
588    
589              <varlistentry>
590                <term><filename>-pdepend=/PATH/FILENAME</></term>
591    
592                <listitem>
593                  <para>This specifies the dependency file used for packages.  If
594                  not specified, the default dependency file is
595                  <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
596                  parsed on a line-by-line basis where each line containes either a
597                  comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
598                  where the "+" or "-" symbol specifies a "must be used with" or a
599                  "must not be used with" relationship, respectively.  If no rule is
600                  specified, then it is assumed that the two packages are compatible
601                  and will function either with or without each other.</para>
602              </listitem>              </listitem>
603            </varlistentry>            </varlistentry>
604    
605            <varlistentry>            <varlistentry>
606              <term><filename></>-mods=DIR</term>              <term><filename>-make=/path/to/gmake</></term>
             <term><filename></>-mods='DIR1 [DIR2 ...]'</term>  
607              <listitem>              <listitem>
608                <para>This option specifies a list of directories                <para>Due to the poor handling of soft-links and other bugs common
609                containing "modifications".  These are files that may                  with the <filename>make</> versions provided by commercial Unix
610                (or may not) exist in the main MITgcm source tree but                  vendors, GNU <filename>make</filename> (sometimes called
611                will be overridden by any identically-named sources                  <filename>gmake</filename>) should be preferred.  This option
612                within the "MODS" directories.</para>                  provides a means for specifying the make program to be
613                    used.</para>
614              </listitem>              </listitem>
615            </varlistentry>            </varlistentry>
616    
617          </variablelist>          </variablelist>
618                    
619          <para>A successful run of <filename>genmake2</> will produce          <para>A successful run of <filename>genmake2</> will produce a
620          both a <filename>Makefile</> and a locally modified copy of            <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
621          the specified <filename>CPP_OPTIONS.h</> file.  The local copy            various convenience files used for the automatic differentiation
622          of <filename>CPP_OPTIONS.h</> will contain a list of            process.</para>
623          <filename>genmake2</>-created #DEFINE and #UNDEF statements  
624          that reflect the list of packages that will be compiled into          <para>In general, it is best to use <filename>genmake2</> on a "clean"
625          the code (either directly through enable/disable/defaults            directory that is free of all source (*.[F,f],*.[F,f]90) and header
626          options or indirectly through dependencies).</para>            (*.h,*.inc) files.  Generally, this can be accomplished in an
627              "un-clean" directory by running "make Clean" followed by "make
628          <para>In general, it is best to use <filename>genmake2</> on a            makefile".</para>
         "clean" directory that is free of all source  
         (*.[F,f],*.[F,f]90) and header (*.h,*.inc) files.  Generally,  
         this can be accomplished in an "un-clean" directory by running  
         "make CLEAN" followed by "make makefile".</para>  
629    
630        </sect3>        </sect3>
631    
632        <sect3 id="makefile_use">        <sect3 id="makefile_use">
633          <title>Using <filename>Makefile</></title>          <title>Using the <filename>Makefile</></title>
634    
635          <para>Once a <filename>Makefile</> has been created, one can          <para>Once a <filename>Makefile</> has been created using
636          build the executable using:</para>            <filename>genmake2</>, one can build a "standard" (forward
637              simulator) executable using:</para>
638    
639  <screen>  <screen>
640  $ make CLEAN    $ make Clean
641  $ make depend    $ make depend
642  $ make    $ make
643  </screen>  </screen>
   
         <para>The "make CLEAN" step will remove any local source  
         files, include files, and links.  It is strongly recommended  
         for "un-clean" directories which may contain the (partial?)  
         results of previous builds.  Such "debris" can interfere with  
         the next stage of the build.</para>  
   
         <para>The "make depend" step will create a large number of  
         symbolic links from the local directory to the source file  
         locations.  It also parses these files and creates an  
         extensive list of dependencies within the  
         <filename>Makefile</> itself.  The links that exist at this  
         stage are mostly "large F" files (*.F and *.F90) that need to  
         be processed by a C preprocessor ("CPP").  
         </para>  
   
         <para>The final "make" invokes the C preprocessor to produce  
         the "little f" files (*.f and *.f90) and then compiles them to  
         object code using the specified FORTRAN compiler and options.  
         An intermediate script is often used during this stage to  
         further process (usually, make simple substitutions) custom  
         definitions such as variable types within the source files.  
         This additional stage is necessary in order to overcome some  
         of the inconsistencies in the sizes of objects (bytes) between  
         different compilers.</para>  
644    
645          <para>Please report compilation failures or other problems to          <para>The "make Clean" step will remove any stale source files, include
646          <email>MITgcm-support@mitgcm.org</email>.</para>            files, and links.  It is strongly recommended for "un-clean"
647              directories which may contain the (perhaps partial) results of
648              previous builds. Such "debris" can interfere with the next stage of
649              the build.
650              A more agressive cleaning option, "make CLEAN", can be used to also
651              remove the executable and output files from a previous run.</para>
652    
653            <para>The "make depend" step will create a large number of symbolic
654              links from the local directory to the source file locations.  It also
655              parses these files and creates an extensive list of dependencies
656              within the <filename>Makefile</> itself.  The links that exist at this
657              stage are mostly "large F" files (*.F and *.F90) that need to be
658              processed by a C preprocessor ("CPP").  Since "make depend" edits the
659              <filename>Makefile</>, it is important not to skip this step!</para>
660    
661            <para>The final "make" invokes the C preprocessor to produce the "little
662              f" files (*.f and *.f90) and then compiles them to object code using
663              the specified FORTRAN compiler and options.  An intermediate script is
664              often used during this stage to further process (usually, make simple
665              substitutions) custom definitions such as variable types within the
666              source files.  This additional stage is necessary in order to overcome
667              some of the inconsistencies in the sizes of objects (bytes) between
668              different compilers. The result of the build process is an executable
669              with the name <filename>mitgcmuv</>.</para>
670    
671            <para>In addition to the forward simulator described above, the
672              <filename>Makefile</> also has a number of targets that can be used to
673              produce various adjoint and tangent-linear builds for optimization and
674              other parameter-sensitivity problems.  The additional targets within
675              the <filename>Makefile</> are:</para>
676    
677            <variablelist>
678    
679              <varlistentry>
680                <term><filename>make adall</></term>
681                <listitem>
682                  <para>This target produces an <filename>mitgcmuv_ad</> executable
683                    using the <filename>taf</> or <filename>staf</> adjoint
684                    compiler.  See the <filename>genmake2</> "-adof" option for
685                    compiler selection.</para>
686                </listitem>
687              </varlistentry>
688    
689              <varlistentry>
690                <term><filename>make ftlall</></term>
691                <listitem>
692                  <para>Similar to <filename>make adall</> above, this
693                    produces...</para>
694                </listitem>
695              </varlistentry>
696    
697            </variablelist>
698    
699            <para>Please report any compilation failures or other build problems to
700              the <email>MITgcm-support@mitgcm.org</email> list.</para>
701    
702        </sect3>        </sect3>
703    
# Line 613  $ make Line 706  $ make
706      <sect2 id="verification">      <sect2 id="verification">
707        <title>The Verification Suite</title>        <title>The Verification Suite</title>
708    
709        <para>The MITgcm CVS tree (within the        <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
710        <filename>$ROOTDIR/verification/</> directory) includes more          directory) includes many (> 90) examples intended for regression
711        than a dozen examples intended for regression testing.  Each one          testing.  Each one of these test-experiment directories contains "known-good"
712        of these example directories contains "known-good" output files          output files along with all the input (including both code and data
713        along with all the input (including both code and data files)          files) required for their re-calculation.
714        required for their re-calculation.  These example directories          Also included in <filename>$ROOTDIR/verification/</> is the shell
715        are further broken down into sets of subdirectories          script <filename>testreport</> to perform regression tests.</para>
716        (eg. <filename>/input</>, <filename>/code</>) intended to  
717        expedite the testing process.</para>        <sect3 id="test-experiment">
718            <title>Test-experiment Directory Content</title>
719    
720              <para> Each test-experiment directory (<filename>TESTDIR</>) contains
721              several standard subdirectories and files which <filename>testreport</>
722              recognizes and uses when running a regression test.
723              The directories/files that <filename>testreport</> uses are different
724              for a forward test and an adjoint test (<filename>testreport -adm</>)
725              and some test-experiments are set-up for only one type of regression
726              test whereas others allow both types of tests (forward and adjoint).</para>
727              <para>Also some test-experiment allows, using the same MITgcm executable,
728              to perform multiple tests using different parameters and input files,
729              with a primary input set-up
730              (<filename>input/ </> or <filename>input_ad/ </>)
731              and corresponding results (<filename>results/output.txt</> or
732              <filename>results/output_adm.txt</>) and with one or several secondary
733              inputs (<filename>input.OTHER/ </> or <filename>input_ad.OTHER/ </>)
734              and corresponding results (<filename>results/output.OTHER.txt </>
735              or <filename>results/output_adm.OTHER.txt</>).</para>
736            <variablelist>
737    
738              <varlistentry>
739                <term>directory <filename>TESTDIR/results/</></term>
740                <listitem>
741                  <para>contains reference standard output used for test comparison.
742                    <filename>results/output.txt</> and
743                    <filename>results/output_adm.txt</>
744                    correspond respectively to primary forward and adjoint test
745                    run on the reference platform (currently
746                    <filename>baudelaire.csail.mit.edu</>)
747                    on one processor (no MPI, single thread)
748                    using the reference compiler (curently the GNU fortran
749                    compiler <filename>gfortran</>).
750                    The presence of these files determines whether or not
751                    <filename>testreport</> is testing or skipping
752                    this test-experiment.
753                    Reference standard output for secondary tests
754                    (<filename>results/output.OTHER.txt</>
755                    or <filename>results/output_adm.OTHER.txt</>) are
756                    also expected here.</para>
757                  <para>The test comparison involves few model variables output, which are,
758                    by default and for a forward test, the 2-D solver initial residual
759                    (<filename>cg2d_init_res</>) and 3-D state variables (T,S,U,V)
760                    monitor output, and, by default and for an adjoint test, the
761                    cost-function and gradient-check. However, some test-experiments
762                    use some package-specific variable/monitor output according to
763                    the file <filename>TESTDIR/input[_ad][.OTHER]/tr_checklist</>
764                    specification.</para>
765                </listitem>
766              </varlistentry>
767    
768              <varlistentry>
769                <term>directory <filename>TESTDIR/build/</></term>
770                <listitem>
771                  <para> initially empty directory where <filename>testreport</>
772                    will build the MITgcm executable for forward and adjoint test.
773                    It might contains an experiment specific
774                    <filename>genmake_local</> file (see <xref linkend="genmake">).
775                    </para>
776                  <para> Note that the original <filename>code[_ad]/SIZE.h_mpi</>
777                    is not directly used as "SIZE.h" to build an MPI-executable ;
778                    instead, a local copy <filename>build/SIZE.h.mpi</> is derived
779                    from <filename>code[_ad]/SIZE.h_mpi</>
780                    by adjusting the number of processors (nPx,nPy) according to
781                    <filename>NUMBER_OF_PROCS</> (see <xref linkend="testreport">,
782                    <filename>testreport -MPI</>) ; then it is linked to "SIZE.h"
783                    (<filename> ln -s SIZE.h.mpi SIZE.h </>) before building
784                    the MPI-executable.</para>
785                </listitem>
786              </varlistentry>
787    
788              <varlistentry>
789                <term>directory <filename>TESTDIR/code/</></term>
790                <listitem>
791                  <para>contains the test-experiment specific source code
792                    used to build the MITgcm executable (<filename>mitgcmuv</>)
793                    for forward-test (using <filename>genmake2 -mods=../code</>).
794                    </para>
795                    <para> It can also contain specific source files with the suffix
796                    "<filename>_mpi</>" to be used
797                    <!--
798                    in the <filename>TESTDIR/build/</> directory
799                    -->
800                    in place of the corresponding file (without suffix)
801                    for an MPI test (see <xref linkend="testreport">).
802                    The presence or absence of <filename>SIZE.h_mpi</>
803                    determines whether or not an MPI test on this
804                    test-experiment is performed or skipped.</para>
805                </listitem>
806              </varlistentry>
807    
808              <varlistentry>
809                <term>directory <filename>TESTDIR/code_ad/</></term>
810                <listitem>
811                  <para>contains the test-experiment specific source code
812                    used to build the MITgcm executable (<filename>mitgcmuv_ad</>)
813                    for adjoint-test (using <filename>genmake2 -mods=../code_ad</>).
814                    It can also contain specific source files with the suffix
815                    "<filename>_mpi</>" (see above).</para>
816                </listitem>
817              </varlistentry>
818    
819              <varlistentry>
820                <term>directory <filename>TESTDIR/input/</></term>
821                <listitem>
822                  <para>contains the input and parameter files
823                    used to run the primary forward test of this test-experiment.
824                    </para>
825                  <para>It can also contain specific parameter files with the suffix
826                    "<filename>.mpi</>" to be used
827                    <!--
828                    in the <filename>TESTDIR/run/</> directory
829                    -->
830                    in place of the corresponding file (without suffix) for MPI
831                    test, or with suffix "<filename>.mth</>" to be used for
832                    multi-threaded test (see <xref linkend="testreport">).
833                    The presence or absence of <filename>eedata.mth</>
834                    determines whether or not a multi-threaded test on this
835                    test-experiment is performed or skipped.</para>
836                  <para>To save disk space and reduce downloading time, multiple
837                    copies of the same input file is avoided by using a shell
838                    script <filename>prepare_run</>.
839                    When such a script is found in <filename>TESTDIR/input/ </>,
840                    <filename>testreport</> run this script in directory
841                    <filename>TESTDIR/run/ </> after linking all the input file
842                    from <filename>TESTDIR/input/ </>.
843                    </para>
844                </listitem>
845              </varlistentry>
846    
847              <varlistentry>
848                <term>directory <filename>TESTDIR/input_ad/</></term>
849                <listitem>
850                  <para>contains the input and parameter files
851                    used to run the primary adjoint test of this test-experiment.
852                    It can also contain specific parameter files with the suffix
853                    "<filename>.mpi</>" and shell script <filename>prepare_run</>
854                    as described above.</para>
855                </listitem>
856              </varlistentry>
857    
858              <varlistentry>
859                <term>directory <filename>TESTDIR/input.OTHER/</></term>
860                <listitem>
861                  <para>contains the input and parameter files
862                    used to run the secondary OTHER forward test of this test-experiment.
863                    It can also contain specific parameter files with suffix
864                    "<filename>.mpi</>" or "<filename>.mth</>" and shell script
865                    <filename>prepare_run</> (see above).</para>
866                    <para> The presence or absence the file <filename>eedata.mth</>
867                    determines whether or not a secondary multi-threaded test on this
868                    test-experiment is performed or skipped.</para>
869                </listitem>
870              </varlistentry>
871    
872              <varlistentry>
873                <term>directory <filename>TESTDIR/input_ad.OTHER/</></term>
874                <listitem>
875                  <para>contains the input and parameter files
876                    used to run the secondary OTHER adjoint test of this test-experiment.
877                    It can also contain specific parameter files with the suffix
878                    "<filename>.mpi</>" and shell script <filename>prepare_run</>
879                    (see above).</para>
880                </listitem>
881              </varlistentry>
882                    <!--
883                    -->
884              <varlistentry>
885                <term>directory <filename>TESTDIR/run/</></term>
886                <listitem>
887                  <para> initially empty directory where <filename>testreport</>
888                    will run the MITgcm executable for primary forward and adjoint
889                    test.</para>
890                  <para>Symbolic links (using command "<filename>ln -s</>") are made
891                    for input and parameter files (from <filename>../input/ </>
892                    or from <filename>../input_ad/ </>) and for MITgcm executable
893                    (from <filename>../build/ </>) before the run proceeds.
894                    The sequence of links (function <filename>linkdata</> within shell
895                    script <filename>testreport</>) for a forward test is:</para>
896    <screen>
897    * link+rename or remove links
898           to special files with suffix ".mpi" or ".mth" from ../input/
899    * link files from ../input/
900    * execute ../input/prepare_run (if it exists)
901    </screen>
902                  <para>The sequence for an ajoint test is similar, with
903                    <filename>../input_ad/ </> replacing <filename>../input/ </>.
904                    </para>
905                </listitem>
906              </varlistentry>
907    
908              <varlistentry>
909                <term>directory <filename>TESTDIR/tr_run.OTHER/</></term>
910                <listitem>
911                  <para> directory created by <filename>testreport</>
912                    to run the MITgcm executable for secondary "OTHER" forward
913                    or adjoint test.</para>
914                  <para> The sequence of links for a forward secondary test is:</para>
915    <screen>
916    * link+rename or remove links
917           to special files with suffix ".mpi" or ".mth" from ../input.OTHER/
918    * link files from ../input.OTHER/
919    * execute ../input.OTHER/prepare_run (if it exists)
920    * link files from ../input/
921    * execute ../input/prepare_run (if it exists)
922    </screen>
923                  <para>The sequence for an ajoint test is similar, with
924                    <filename>../input_ad.OTHER/ </> and <filename>../input_ad/ </>
925                    replacing <filename>../input.OTHER/ </> and <filename>../input/ </>.
926                    </para>
927                </listitem>
928              </varlistentry>
929    
930            </variablelist>
931          </sect3>
932    
933        <sect3 id="testreport">        <sect3 id="testreport">
934          <title>The <filename>testreport</> Utility</title>          <title>The <filename>testreport</> Utility</title>
935    
936          <para>Also included in <filename>$ROOTDIR/verification/</> are          <para> The shell script  <filename>testreport</> (in
937          shell scripts for automated testing.  The newest script (which            <filename>$ROOTDIR/verification/</>), which was written to work with
938          was written to work with <filename>genmake2</>) is called            <filename>genmake2</>, can be used to build different versions
939          <filename>testreport</>.  Ths script can be used to build the            of the MITgcm code, run the various examples, compare the output,
940          different versions of the MITgcm code, run the various            and (if specified) email the results of each one of these tests to a
941          examples, compare the output, and (if specified) email the            central repository.</para>
942          results of each one of these tests to a central  
943          repository.</para>          <para>On some systems, the testreport script can be run with a command
944            line as simple as:</para>
945    
946    <screen>
947      $ cd verification
948      $ ./testreport
949    </screen>
950    
951            <para>However, some systems (those lacking or wiht a broken "/bin/sh")
952              may require an explicit shell invocation such as:</para>
953    
954    <screen>
955      $ sh ./testreport -t 'exp2 exp4'
956      $ /some/path/to/bash ./testreport -t 'ideal_2D_oce lab_sea natl_box'
957    </screen>
958    
959          <para>The <filename>testreport</> script accepts a number of          <para>The <filename>testreport</> script accepts a number of
960          command-line options which can be listed using the            command-line options which can be listed using the <filename>-help</>
961          <filename>-help</> option.  The most important ones are:</para>            option.  The most important ones are:</para>
962    
963          <variablelist>          <variablelist>
964    
965            <varlistentry>            <varlistentry>
966              <term><filename>-tdir TESTDIR</></term>              <term><filename>-ieee</> (default) / <filename>-noieee</></term>
             <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>  
967              <listitem>              <listitem>
968                <para>This option specifies the test directory or list                <para>If allowed by the compiler (as defined in the "optfile"),
969                of test directories that should be used.  Each of these                  use IEEE arithmetic (<filename>genmake2 -ieee</>).
970                entries should exactly (note: they're case sensitive!)                  This option, along with the gfortran / gcc compiler,
971                match the names of directries in                  is how the standard results are produced.</para>
               <filename>$ROOTDIR/verification/</>.  If this option is  
               omitted, then all directories that are properly  
               formatted (that is, containing an <filename>input</>  
               sub-directory and example output) will be used.</para>  
972              </listitem>              </listitem>
973            </varlistentry>            </varlistentry>
974    
# Line 660  $ make Line 976  $ make
976              <term><filename>-optfile=/PATH/FILENAME</></term>              <term><filename>-optfile=/PATH/FILENAME</></term>
977              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
978              <listitem>              <listitem>
979                <para>This specifies a list of "options files" that will                <para>This specifies a list of "options files" that will be passed
980                be passed to <filename>genmake2</>.  If multiple options                  to <filename>genmake2</>.  If multiple options files are used
981                files are used (say, to test different compilers or                  (say, to test different compilers or different sets of options
982                different sets of options for the same compiler), then                  for the same compiler), then each options file will be used with
983                each options file will be used with each of the test                  each of the test directories.</para>
984                directories.</para>              </listitem>
985              </varlistentry>
986    
987              <varlistentry>
988                <term><filename>-tdir TESTDIR</></term>
989                <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
990                <listitem>
991                  <para>This option specifies the test directory or list of test
992                    directories that should be used.  Each of these entries should
993                    exactly (note: they are case sensitive!) match the names of
994                    directories in <filename>$ROOTDIR/verification/</>.  If this
995                    option is omitted, then all directories that are properly
996                    formatted (that is, containing an <filename>input</>
997                    sub-directory and a <filename>results/output.txt</> file) will
998                    be used.</para>
999              </listitem>              </listitem>
1000            </varlistentry>            </varlistentry>
1001    
# Line 674  $ make Line 1004  $ make
1004              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
1005              <listitem>              <listitem>
1006                <para>Send the results (namely, <filename>output.txt</>,                <para>Send the results (namely, <filename>output.txt</>,
1007                <filename>gm_local</>, <filename>gm_state</>, and                  <filename>genmake_local</>, <filename>genmake_state</>, and
1008                <filename>Makefile</>) to the specified email addresses.                  <filename>Makefile</>) to the specified email addresses.  The
1009                The results are gzipped, placed in a tar file, MIME                  results are gzipped, placed in a tar file, MIME encoded, and
1010                encoded, and sent to an @mitgcm.org address.  If no                  sent to the specified address.  If no email addresses are
1011                email addresses are specified, no mail is sent.</para>                  specified, no mail is sent.</para>
1012                </listitem>
1013              </varlistentry>
1014    
1015              <varlistentry>
1016                <term><filename>-MPI NUMBER_OF_PROCS</></term>
1017                <term><filename>-mpi</></term>
1018                <listitem>
1019                  <para>If the necessary file (<filename>TESTDIR/code/SIZE.h_mpi</>)
1020                  exists, then use it (and all <filename>TESTDIR/code/*_mpi</> files)
1021                  for an MPI--enabled run.  The new option (<filename>-MPI</> followed
1022                  by the maximum number of processors) enable to build and run each
1023                  test-experiment using variable number of MPI processors (multiple
1024                  of <filename>nPx*nPy</> from <filename>TESTDIR/code/SIZE.h_mpi</>
1025                  and not larger than <filename>NUMBER_OF_PROCS</>).
1026                  The short option ("-mpi") can only be used to build and run on 2 MPI
1027                  processors (equivalent to "<filename>-MPI 2</>").</para>
1028                  <para>Note that the use of MPI typically requires a
1029                  special command option (see "-command" below) to invoke the MPI
1030                  executable.  Examples of PBS scripts using testreport with MPI can be
1031                  found in the <ulink
1032                  url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
1033                  tools/example_scripts directory</ulink>.</para>
1034                </listitem>
1035              </varlistentry>
1036    
1037              <varlistentry>
1038                <term><filename>-command='some command to run'</></term>
1039                <listitem>
1040                  <para>For some tests, particularly MPI runs, a specific command
1041                  might be needed to run the executable. This option allows a more general
1042                  command (or shell script) to be invoked.  Examples of PBS scripts
1043                  using testreport with MPI can be found in the <ulink
1044                  url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
1045                  tools/example_scripts directory</ulink>.</para>
1046                  <para>
1047                    For the case where the number of MPI processors varies according
1048                    to each test-experiment, some key-words within the command-to-run
1049                    argument will be replaced by their effective value:</para>
1050                  <para>
1051                    <filename>TR_NPROC </> will be replaced by the actual number
1052                    of MPI processors needed to run the current test-experiment.</para>
1053                  <para>
1054                    <filename>TR_MFILE </> will be replaced by the name of local-file
1055                    that testreport creates from the full list of machines which
1056                    "<filename>testreport -mf MACHINE_FILE</>" provides, but truncated
1057                    to the exact number of machines.</para>
1058                </listitem>
1059              </varlistentry>
1060    
1061              <varlistentry>
1062                <term><filename>-mf MACHINE_FILE</></term>
1063                <listitem>
1064                  <para>
1065                    To use with <filename>-MPI NUMBER_OF_PROCS</> option, to specify
1066                    the file containing the full list of <filename>NUMBER_OF_PROCS</>
1067                    machines to use for the MPI runs.</para>
1068                </listitem>
1069              </varlistentry>
1070    
1071              <varlistentry>
1072                <term><filename>-mth</></term>
1073                <listitem>
1074                  <para>compile (with <filename>genmake2 -omp</>) and run with
1075                    multiple threads (using eedata.mth).</para>
1076              </listitem>              </listitem>
1077            </varlistentry>            </varlistentry>
1078    
1079          </variablelist>          </variablelist>
1080    
1081          <para>The <filename>testreport</> script will write progress          <para>The <filename>testreport</> script will create an output directory
1082          to the screen (stdout) as it runs.  In addition, it will            <filename>tr_NAME_DATE_N/ </>, with <filename>hostname</> as default
1083          create a <filename>summary.txt</> file that contains a brief            <filename>NAME</>, <filename>DATE</> the current date followed by
1084          comparison of the current output with the "known-good"            a suffix number "N" to distinguish from previous
1085          output.</para>            <filename>testreport</> output directories.
1086              <filename>testreport</> writes progress to the screen (stdout)
1087              and reports into the ouput directory as it runs.
1088              In particular, one can find, in the ouput directory,
1089              the <filename>summary.txt</> file that contains a brief comparison
1090              of the current output with the "known-good" output.
1091              At the end of the testing process, the <filename>tr_out.txt</> file
1092              is generated in <filename>$ROOTDIR/verification/ </>
1093              as a compact version of <filename>summry.txt</> file.</para>
1094    
1095        </sect3>        </sect3>
1096    
1097          <sect3 id="tst_2plus2">
1098            <title>The <filename>do_tst_2+2</> Utility</title>
1099            <para> The shell script  <filename>do_tst_2+2</> (in
1100              <filename>$ROOTDIR/tools/ </>)
1101              can be used to check the accuracy of the restart procedure.
1102            </para>
1103          </sect3>
1104    
1105      </sect2>      </sect2>
1106    
1107    
1108      <sect2 id="packages">      <sect2 id="packages">
1109        <title>Creating MITgcm Packages</title>        <title>Creating MITgcm Packages</title>
1110    
1111        <para>Optional parts of code have been separated from the MITgcmUV        <para>Optional parts of code have been separated from the MITgcmUV core
1112        core driver code and organised into packages. The packaging          driver code and organised into packages.  The packaging structure
1113        structure provides a mechanism for maintaining suites of code,          provides a mechanism for maintaining suites of code, specific to
1114        specific to particular classes of problems, in a way that is          particular classes of problems, in a way that is cleanly separated from
1115        cleanly separated from the generic fluid dynamical          the generic fluid dynamical engine.</para>
1116        engine.</para>  
1117          <para>The MITgcmUV packaging structure is described below using generic
1118        <para>The MITgcmUV packaging structure is described below using          package names ${pkg}. A concrete examples of a package is the code for
1119        generic package names ${pkg}.  A concrete examples of a package          implementing GM/Redi mixing. This code uses the package name</para>
       is the code for implementing GM/Redi mixing. This code uses the  
       package name</para>  
1120    
1121      </sect2>      </sect2>
1122    
# Line 731  separated from the generic fluid dynamic Line 1140  separated from the generic fluid dynamic
1140  below using generic package names ${pkg}.  below using generic package names ${pkg}.
1141  A concrete examples of a package is the code  A concrete examples of a package is the code
1142  for implementing GM/Redi mixing. This code uses  for implementing GM/Redi mixing. This code uses
1143  the package name  the package name
1144  *   ${PKG} = GMREDI  *   ${PKG} = GMREDI
1145  *   ${pkg} = gmredi  *   ${pkg} = gmredi
1146  *   ${Pkg} = gmRedi  *   ${Pkg} = gmRedi
# Line 766  o  Each package gets its runtime configu Line 1175  o  Each package gets its runtime configu
1175     Package runtime config. options are imported     Package runtime config. options are imported
1176     into a common block held in a header file     into a common block held in a header file
1177     called "${PKG}.h".     called "${PKG}.h".
1178       Note: In some packages, the header file "${PKG}.h" is splitted
1179       into "${PKG}_PARAMS.h" that contains the package parameters and
1180       ${PKG}_VARS.h" for the field arrays.
1181    
1182  o  The core driver part of the model can check  o  The core driver part of the model can check
1183     for runtime enabling or disabling of individual packages     for runtime enabling or disabling of individual packages
# Line 788  CPP Flags Line 1200  CPP Flags
1200      1. Within the core driver code flags of the form      1. Within the core driver code flags of the form
1201         ALLOW_${PKG} are used to include or exclude         ALLOW_${PKG} are used to include or exclude
1202         whole packages. The ALLOW_${PKG} flags are included         whole packages. The ALLOW_${PKG} flags are included
1203         from a PKG_CPP_OPTIONS block which is currently         from a PACKAGES_CONFIG.h file that is automatically
1204           generated by genmake2 (see genmake2 section).
1205         held in-line in the CPP_OPTIONS.h header file.         held in-line in the CPP_OPTIONS.h header file.
1206         e.g.         e.g.
1207    
1208         Core model code .....         Core model code .....
1209    
1210           #include "PACKAGES_CONFIG.h"
1211         #include "CPP_OPTIONS.h"         #include "CPP_OPTIONS.h"
1212           :           :
1213           :           :
# Line 805  CPP Flags Line 1219  CPP Flags
1219    
1220      2. Within an individual package a header file,      2. Within an individual package a header file,
1221         "${PKG}_OPTIONS.h", is used to set CPP flags         "${PKG}_OPTIONS.h", is used to set CPP flags
1222         specific to that package. It is not recommended         specific to that package. It also includes
1223         to include this file in "CPP_OPTIONS.h".         "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
1224    
1225    
1226  Package Boot Sequence  Package Boot Sequence
# Line 819  Package Boot Sequence Line 1233  Package Boot Sequence
1233      1. S/R PACKAGES_BOOT()      1. S/R PACKAGES_BOOT()
1234              :              :
1235          CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )          CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
1236    
1237    
1238      2. S/R PACKAGES_READPARMS()      2. S/R PACKAGES_READPARMS()
1239              :              :
# Line 828  Package Boot Sequence Line 1242  Package Boot Sequence
1242       &       CALL ${PKG}_READPARMS( retCode )       &       CALL ${PKG}_READPARMS( retCode )
1243          #endif          #endif
1244    
1245      2. S/R PACKAGES_CHECK()      3. S/R PACKAGES_INIT_FIXED()
1246                :
1247            #ifdef ALLOW_${PKG}
1248              if ( use${Pkg} )
1249         &       CALL ${PKG}_INIT_FIXED( retCode )
1250            #endif
1251    
1252        4. S/R PACKAGES_CHECK()
1253              :              :
1254          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
1255            if ( use${Pkg} )            if ( use${Pkg} )
# Line 838  Package Boot Sequence Line 1259  Package Boot Sequence
1259       &       CALL PACKAGES_CHECK_ERROR('${PKG}')       &       CALL PACKAGES_CHECK_ERROR('${PKG}')
1260          #endif          #endif
1261    
1262      3. S/R PACKAGES_INIT()      5. S/R PACKAGES_INIT_VARIABLES()
1263              :              :
1264          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
1265            if ( use${Pkg} )            if ( use${Pkg} )
1266       &       CALL ${PKG}_INIT( retCode )       &       CALL ${PKG}_INIT_VARIA( )
1267            #endif
1268    
1269    Package Output
1270    ==============
1271         6. S/R DO_THE_MODEL_IO
1272    
1273            #ifdef ALLOW_${PKG}
1274              if ( use${Pkg} )
1275         &       CALL ${PKG}_OUTPUT( )
1276          #endif          #endif
1277    
1278         7. S/R PACKAGES_WRITE_PICKUP()
1279    
1280            #ifdef ALLOW_${PKG}
1281              if ( use${Pkg} )
1282         &       CALL ${PKG}_WRITE_PICKUP( )
1283            #endif
1284    
1285  Description  Description
1286  ===========  ===========
1287    
1288        - ${PKG}_READPARMS()        - ${PKG}_READPARMS()
1289      is responsible for reading      is responsible for reading
1290      in the package parameters file data.${pkg}, and storing      in the package parameters file data.${pkg}, and storing
1291      the package parameters in "${PKG}.h".      the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
1292      -> called in INITIALISE_FIXED      -> called from INITIALISE_FIXED in PACKAGES_READPARMS
1293    
1294         - ${PKG}_INIT_FIXED()
1295        is responsible for completing the internal setup of a package.
1296        -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
1297        note: 1) some pkg use instead:
1298                 CALL ${PKG}_INITIALISE  ( or the old form CALL ${PKG}_INIT )
1299              2) for simple pkg setup, this part is done inside ${PKG}_READPARMS
1300    
1301       - ${PKG}_CHECK()       - ${PKG}_CHECK()
1302      is responsible for validating      is responsible for validating
1303      basic package setup and inter-package dependencies.      basic package setup and inter-package dependencies.
1304      ${PKG}_CHECK can import other package parameters it may      ${PKG}_CHECK can import other package parameters it may
1305      need to check. This is done through header files "${PKG}.h".      need to check. This is done through header files "${PKG}.h".
1306      It is assumed that parameters owned by other packages      It is assumed that parameters owned by other packages
1307      will not be reset during ${PKG}_CHECK().      will not be reset during ${PKG}_CHECK().
1308      -> called in INITIALISE_FIXED      -> called from INITIALISE_FIXED in PACKAGES_CHECK
1309    
1310       - ${PKG}_INIT()       - ${PKG}_INIT_VARIA()
1311      is responsible for completing the      is responsible for fill-in all package variables with an initial value.
1312      internal setup of a package. This routine is called after      Contains eventually a call to ${PKG}_READ_PICKUP that will read
1313      the core model state has been completely initialised      from a pickup file the package variables required to restart the model.
1314      but before the core model timestepping starts.      This routine is called after the core model state has been completely
1315      -> called in INITIALISE_VARIA      initialised but before the core model timestepping starts.
1316        -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
1317        note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
1318         use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
1319         form ${PKG}_INIT
1320    
1321         - ${PKG}_OUTPUT( )
1322         is responsible for writing time-average fields to output files
1323         (but the cumulating step is done within the package main S/R).
1324         Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1325         and write snap-shot fields that are hold in common blocks. Other
1326         temporary fields are directly dump to file where they are available.
1327         NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
1328                  but is beeing replaced by ${PKG}_OUTPUT
1329                  to avoid confusion with pkg/diagnostics functionality.
1330               2) the output part is not yet in a standard form and might still
1331                  evolve a lot.
1332        -> called within DO_THE_MODEL_IO
1333    
1334         - ${PKG}_WRITE_PICKUP()
1335         is responsible for writing a package pickup file when necessary for
1336         a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1337        -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1338    
1339  Summary  Summary
1340  =======  =======
# Line 890  Summary Line 1355  Summary
1355    -----------------------    -----------------------
1356    * ${PKG}_OPTIONS.h     has further package-specific CPP options    * ${PKG}_OPTIONS.h     has further package-specific CPP options
1357    * ${PKG}.h             package-specific common block variables, fields    * ${PKG}.h             package-specific common block variables, fields
1358       or  ${PKG}_PARAMS.h   package-specific common block parameters
1359       and ${PKG}_VARS.h     package-specific common block fields
1360    
1361  - FORTRAN source files  - FORTRAN source files
1362    -----------------------    -----------------------
1363    * ${pkg}_readparms.F   reads parameters from file data.${pkg}    * ${pkg}_readparms.F    reads parameters from file data.${pkg}
1364    * ${pkg}_check.F       checks package dependencies and consistencies    * ${pkg}_init_fixed.F   complete the package setup
1365    * ${pkg}_init.F        initialises package-related fields    * ${pkg}_check.F        checks package dependencies and consistencies
1366    * ${pkg}_... .F        package source code    * ${pkg}_init_varia.F   initialises package-related fields
1367      * ${pkg}_... .F         package source code
1368      * ${pkg}_output.F       write output to file.
1369      * ${pkg}_write_pickup.F write a package pickup file to restart the model
1370    
1371      New: Subroutine in one package (pkgA) that only contains code which
1372           is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
1373           will be named: pkgA_pkgB_something.F
1374    
1375  - parameter file  - parameter file
1376    -----------------------    -----------------------
# Line 906  Summary Line 1380  Summary
1380    </sect1>    </sect1>
1381    
1382    
1383      <sect1 id="documentation">
1384        <title>Editing the Documentation</title>
1385    
1386        <sect2 id="documentation_getting">
1387          <title>Getting the Docs and Code</title>
1388    
1389          <para>The first step towards editing the documentation is to checkout a
1390          copy of code, docs, and build scripts from the CVS server using:</para>
1391    
1392    <screen>
1393      $ export CVS_RSH=ssh
1394      $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
1395      $ mkdir scratch
1396      $ cvs co -P MITgcm manual mitgcm.org
1397    </screen>
1398    
1399          <para>These commands extract the necessary information from the CVS server
1400          and create a temporary (called <filename>scratch</filename>) directory for
1401          the storage of the HTML and other files that will be created.  Please note
1402          that you must either create <filename>scratch</filename> as shown or edit
1403          the various <filename>Makefile</filename>s and scripts used to create the
1404          documentation.</para>
1405        </sect2>
1406    
1407        <sect2>
1408          <title>Editing the Documentation</title>
1409    
1410          <para>The documentation is contained in the <filename>manual</filename>
1411          directory in a raw LaTeX format.  The main document is
1412          <filename>manual.tex</filename> and it uses <command>\input{}</command>s
1413          to include the chapters and subsections.</para>
1414    
1415          <para>Since the same LaTeX source is used to produce PostScript, PDF, and
1416          HTML output, care should be taken to follow certain conventions.  Two of
1417          the most important are the usage of the <command>\filelink{}{}</command>
1418          and <command>\varlink{}{}</command> commands.  Both of these commands have
1419          been defined to simplify the connection between the automatically
1420          generated ("code browser") HTML and the HTML version of the manual
1421          produced by LaTeX2HTML.  They each take two arguments (corresponding to
1422          the contents of the two sets of curly braces) which are the text that the
1423          author wishes to be "wrapped" within the link, and a specially formatted
1424          link thats relative to the <filename>MITgcm</filename> directory within
1425          the CVS tree.</para>
1426    
1427          <para>The result is a command that resembles either</para>
1428    
1429          <orderedlist>
1430            <listitem>
1431              <para>a reference to a variable or subroutine name such as
1432              <command>\varlink{tRef}{tRef}</command>, or </para>
1433            </listitem>
1434    
1435            <listitem>
1436              <para>a reference to a file such as
1437                  <command>\varlink{tRef}{path-to-the-file_name.F}</command>
1438                  where the absolute path to the file is of the form
1439                  <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>
1440                  <para>(please note how the leading "/foo/MITgcm"
1441                  component of the path is dropped leaving the path
1442                  <emphasis>relative</emphasis> to the head of the code
1443                  directory and each directory separator "/" is turned
1444                  into a "-")</para>
1445            </listitem>
1446          </orderedlist>
1447            
1448    
1449    
1450        </sect2>
1451    
1452        <sect2>
1453          <title>Building the Documentation</title>
1454    
1455          <para>Given the directory structure of <xref
1456          linkend="documentation_getting">, the entire documentation for the web
1457          site can be built using:</para>
1458    
1459    <screen>
1460      $ cd mitgcm.org/devel/buildweb
1461      $ make All
1462    </screen>
1463    
1464          <para>Which builds the PDF from the LaTeX source, creates the HTML output
1465          from the LaTeX source, parses the FORTRAN code base to produce a
1466          hyperlinked HTML version of the source, and then determines the
1467          cross-linking between the various HTML components.</para>
1468    
1469          <para>If there are no errors, the result of the build process (which can
1470          take 30+ minutes on a P4/2.5Ghz) will be contained within a single
1471          directory called <filename>scratch/dev_docs</filename>.  This is a freshly
1472          built version of the entire on-line users manual.  If you have the correct
1473          permissions, it can be directly copied to the web server area:</para>
1474    
1475    <screen>
1476      $ mv scratch/dev_docs /u/u0/httpd/html
1477    </screen>
1478    
1479          <para>and the update is complete.</para>
1480    
1481        </sect2>
1482    
1483      </sect1>
1484    
1485  </article>  </article>
1486    
1487    
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.16
  ViewVC Help
Powered by ViewVC 1.1.22