/[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.8 by jmc, Wed Jan 5 03:45:24 2005 UTC
# Line 2  Line 2 
2    
3  <article id="MITgcm-Development-HOWTO">  <article id="MITgcm-Development-HOWTO">
4    
 <!--  
 Build commands:  
   db2ps -d ldp.dsl devel_HOWTO.sgml  
   db2pdf -d ldp.dsl devel_HOWTO.sgml  
   db2html -d ./ldp.dsl devel_HOWTO.sgml  
   db2html -u -d ./ldp.dsl devel_HOWTO.sgml  
 -->  
   
5    <articleinfo>    <articleinfo>
6      <title>MITgcm Development HOWTO</title>      <title>MITgcm Development HOWTO</title>
7    
# Line 63  Build commands: Line 55  Build commands:
55      <sect2>      <sect2>
56        <title>User Manual</title>        <title>User Manual</title>
57    
58        <para>Before jumping into        <para>Before jumping into development, please familiarize yourself with
59        development, please familiarize yourself with the MITgcm user          the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual
60        manual which is available <ulink          </ulink>.  This document contains volumes of useful information and is
61        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>  
62    
63        <para>Also, a "snapshot" or<ulink        <!--
64          <para>Also, a "snapshot" or <ulink
65        url="http://mitgcm.org/dev_docs/">development version</ulink> of        url="http://mitgcm.org/dev_docs/">development version</ulink> of
66        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
67        web for testing purposes.</para>        web for testing purposes.</para>
68          -->
69      </sect2>      </sect2>
70    
71      <sect2>      <sect2>
# Line 128  Build commands: Line 120  Build commands:
120         doc                      tags -- connect to real docs?         doc                      tags -- connect to real docs?
121         eesupp                   cnh?         eesupp                   cnh?
122         exe                      ecco user build         exe                      ecco user build
123      *- jobs                     runtime shell scripts for      ,- jobs                     runtime shell scripts for
124      |                             various platforms      |                             various platforms
125      |  lsopt                    line search      |  lsopt                    line search
126     m|  model                    main dynamics (core)     m|  model                    main dynamics (core)
127     e|    optimization_drivers   ?     e|    optimization_drivers   ?
128     r|  optim                    line search interface     r|  optim                    line search interface
129     g|  pkg                      alternate and optional numerics, etc.     g|  pkg                      alternate and optional numerics, etc.
130     e*- tools     e|- tools
131     ?|  tutorial_examples        documented tests     ?|  tutorial_examples        documented tests
132      |                             only populated on release1 branch      |                             only populated on release1 branch
133      |                             and not validated during "testscript"      |                             and not validated during "testscript"
134      *- utils      '- utils
135         verification             std tests         verification             std tests
136    
137    
# Line 190  Build commands: Line 182  Build commands:
182        <title>Branches</title>        <title>Branches</title>
183    
184        <para>As shown in the online <ulink        <para>As shown in the online <ulink
185        url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">ViewCVS-generated        url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">
186        tree</ulink>, the MITgcm codebase is split into to two branches        ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two
187        or "lines" under which development proceeds.  These two lines        branches or "lines" under which development proceeds.  These two lines are
188        are referred to as the "MAIN" and "ecco" versions of the code.        referred to as the "MAIN" and "ecco" versions of the code.  While not
189        While not identical, the bulk of the MAIN and ecco lines are        identical, the bulk of the MAIN and ecco lines are composed of files from
190        composed of files from the same codebase.        the same codebase.
191        </para>        </para>
192    
193        <para>Periodically, a "Release" branch is formed from the "MAIN"        <para>Periodically, a "Release" branch is formed from the "MAIN"
194        development branch.  This is done in order to create a        development branch.  This is done in order to create a relatively stable
195        relatively stable reference point for both users and developers.        reference point for both users and developers.  The intent is that once a
196        The intent is that once a relese branch has been created, only        relese branch has been created, only bug-fixes will be added to it.
197        bug-fixes will be added to it.  Meanwhile, development (which        Meanwhile, development (which might "break" or otherwise render invalid
198        might "break" or otherwise render invalid the documentation,        the documentation, tutorials, and/or examples contained within a release
199        tutorials, and/or examples contained within a release branch) is        branch) is allowed to continue along the MAIN and ecco lines.</para>
       allowed to continue along the MAIN and ecco lines.</para>  
200      </sect2>      </sect2>
201    
202      <sect2>      <sect2>
203        <title>Tagging</title>        <title>Tagging</title>
204    
205        <para>The intent of tagging is to create "known-good"        <para>The intent of tagging is to create "known-good" checkpoints that
206        checkpoints that developers can use as references.        developers can use as references.  Traditionally, MITgcm tagging has
207        Traditionally, MITgcm tagging has maintained the following        maintained the following conventions:</para>
       conventions:</para>  
208    
209        <orderedlist>        <orderedlist>
210          <listitem>          <listitem>
211            <para>Developer checks out code into a local CVS-managed            <para>Developer checks out code into a local CVS-managed directory,
212            directory, makes various changes/additions, tests these            makes various changes/additions, tests these edits, and eventually
213            edits, and eventually reaches a point where (s)he is            reaches a point where (s)he is satisfied that the changes form a new
214            satisfied that the changes form a new "useful" point in the            "useful" point in the evolution of the code.</para>
           evolution of the code.</para>  
215          </listitem>          </listitem>
216    
217          <listitem>          <listitem>
218            <para>The developer then runs the <ulink            <para>The developer then runs the <ulink
219            url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">testscript</ulink>            url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">
220            shell script to see if any problems are introduced.  While            testscript</ulink> shell script to see if any problems are introduced.
221            not intended to be exhaustive, the test cases within the            While not intended to be exhaustive, the test cases within the
222            verification directory do provide some indication whether            verification directory do provide some indication whether gross errors
223            gross errors have been introduced.            have been introduced.
224            </para>            </para>
225          </listitem>          </listitem>
226    
# Line 241  Build commands: Line 230  Build commands:
230            then:</para>            then:</para>
231            <orderedlist>            <orderedlist>
232              <listitem>              <listitem>
233                <para>adds a "checkpointXY_pre" comment (where X is a                <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
234                checkpoint number and Y is a letter) to the <ulink                number and Y is a letter) to the <ulink
235                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">tag-index</ulink>                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">
236                file and checks it into the CVS repository</para>                tag-index</ulink> file and checks it into the CVS
237                  repository</para>
238              </listitem>              </listitem>
239              <listitem>              <listitem>
240                <para>submits the set of changes to the CVS repository                <para>submits the set of changes to the CVS repository and adds
241                and adds comments to <filename>tag-index</filename>                comments to <filename>tag-index</filename> describing what the
242                describing what the changes are along with a matching                changes are along with a matching "checkpointXY_post" entry</para>
               "checkpointXY_post" entry</para>  
243              </listitem>              </listitem>
244            </orderedlist>            </orderedlist>
245          </listitem>          </listitem>
246        </orderedlist>        </orderedlist>
247    
248        <para>The result of this tagging procedure is a sequence of        <para>The result of this tagging procedure is a sequence of development
249        development checkpoints with comments which resembles:</para>        checkpoints with comments which resembles:</para>
250    
251  <programlisting>  <programlisting>
252  checkpoint50e_post  checkpoint50e_post
# Line 279  o fix small problem with in ptracers_wri Line 268  o fix small problem with in ptracers_wri
268  checkpoint50d_pre  checkpoint50d_pre
269  </programlisting>  </programlisting>
270    
271        <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
272        the code development.  For example, bugs can be traced to        development.  For example, bugs can be traced to individual sets of CVS
273        individual sets of CVS checkins based upon their first        checkins based upon their first appearance when comparing the results from
274        appearance when comparing the results from different        different checkpoints.</para>
       checkpoints.</para>  
275    
276      </sect2>      </sect2>
277    </sect1>    </sect1>
# Line 295  checkpoint50d_pre Line 283  checkpoint50d_pre
283      <sect2 id="documentation_getting">      <sect2 id="documentation_getting">
284        <title>Getting the Docs and Code</title>        <title>Getting the Docs and Code</title>
285    
286        <para>The first step towards editing the documentation is to        <para>The first step towards editing the documentation is to checkout a
287        checkout a copy of code, docs, and build scripts from the CVS        copy of code, docs, and build scripts from the CVS server using:</para>
       server using:</para>  
288    
289  <screen>  <screen>
290  $ export CVS_RSH=ssh    $ export CVS_RSH=ssh
291  $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'    $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
292  $ mkdir scratch    $ mkdir scratch
293  $ cvs co MITgcm manual mitgcm.org    $ cvs co MITgcm manual mitgcm.org
294  </screen>  </screen>
295    
296        <para>These commands extract the necessary information from the        <para>These commands extract the necessary information from the CVS server
297        CVS server and create a temporary (called        and create a temporary (called <filename>scratch</filename>) directory for
298        <filename>scratch</filename>) directory for the storage of the        the storage of the HTML and other files that will be created.  Please note
299        HTML and other files that will be created.  Please note that you        that you must either create <filename>scratch</filename> as shown or edit
300        must either create <filename>scratch</filename> as shown or edit        the various <filename>Makefile</filename>s and scripts used to create the
301        the various <filename>Makefile</filename>s and scripts used to        documentation.</para>
       create the documentation.</para>  
302      </sect2>      </sect2>
303    
304      <sect2>      <sect2>
305        <title>Editing</title>        <title>Editing the Documentation</title>
306    
307        <para>The documentation is contained in the        <para>The documentation is contained in the <filename>manual</filename>
308        <filename>manual</filename> directory in a raw LaTeX format.        directory in a raw LaTeX format.  The main document is
309        The main document is <filename>manual.tex</filename> and it uses        <filename>manual.tex</filename> and it uses <command>\input{}</command>s
310        <command>\input{}</command>s to include the chapters and        to include the chapters and subsections.</para>
311        subsections.</para>  
312          <para>Since the same LaTeX source is used to produce PostScript, PDF, and
313        <para>Since the same LaTeX source is used to produce PostScript,        HTML output, care should be taken to follow certain conventions.  Two of
314        PDF, and HTML output, care should be taken to follow certain        the most important are the usage of the <command>\filelink{}{}</command>
315        conventions.  Two of the most important are the usage of the        and <command>\varlink{}{}</command> commands.  Both of these commands have
316        <command>\filelink{}{}</command> and        been defined to simplify the connection between the automatically
317        <command>\varlink{}{}</command> commands.  Both of these        generated ("code browser") HTML and the HTML version of the manual
318        commands have been defined to simplify the connection between        produced by LaTeX2HTML.  They each take two arguments (corresponding to
319        the automatically generated ("code browser") HTML and the HTML        the contents of the two sets of curly braces) which are the text that the
320        version of the manual produced by LaTeX2HTML.  They each take        author wishes to be "wrapped" within the link, and a specially formatted
321        two arguments (corresponding to the contents of the two sets of        link thats relative to the <filename>MITgcm</filename> directory within
322        curly braces) which are the text that the author wishes to be        the CVS tree.</para>
       "wrapped" within the link, and a specially formatted link thats  
       relative to the <filename>MITgcm</filename> directory within the  
       CVS tree.</para>  
323    
324        <para>The result is a command that resembles either</para>        <para>The result is a command that resembles either</para>
325                
# Line 364  $ cvs co MITgcm manual mitgcm.org Line 347  $ cvs co MITgcm manual mitgcm.org
347      </sect2>      </sect2>
348    
349      <sect2>      <sect2>
350        <title>Building</title> <para>Given the directory structure of        <title>Building the Documentation</title>
351        <xref linkend="documentation_getting">, the entire documentation        
352        for the web site can be built using:</para>        <para>Given the directory structure of <xref
353          linkend="documentation_getting">, the entire documentation for the web
354          site can be built using:</para>
355    
356  <screen>  <screen>
357  $ cd mitgcm.org/devel/buildweb    $ cd mitgcm.org/devel/buildweb
358  $ make All    $ make All
359  </screen>  </screen>
360    
361        <para>Which builds the PDF from the LaTeX source, creates the        <para>Which builds the PDF from the LaTeX source, creates the HTML output
362        HTML output from the LaTeX source, parses the FORTRAN code base        from the LaTeX source, parses the FORTRAN code base to produce a
363        to produce a hyperlinked HTML version of the source, and then        hyperlinked HTML version of the source, and then determines the
364        determines the cross-linking between the various HTML        cross-linking between the various HTML components.</para>
365        components.</para>  
366          <para>If there are no errors, the result of the build process (which can
367        <para>If there are no errors, the result of the build process        take 30+ minutes on a P4/2.5Ghz) will be contained within a single
368        (which can take 30+ minutes on a P4/2.5Ghz) will be contained        directory called <filename>scratch/dev_docs</filename>.  This is a freshly
369        within a single directory called        built version of the entire on-line users manual.  If you have the correct
370        <filename>scratch/dev_docs</filename>.  This is a freshly built        permissions, it can be directly copied to the web server area:</para>
       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>  
371    
372  <screen>  <screen>
373  $ mv scratch/dev_docs /u/u0/httpd/html    $ mv scratch/dev_docs /u/u0/httpd/html
374  </screen>  </screen>
375    
376        <para>and the update is complete.</para>        <para>and the update is complete.</para>
# Line 403  $ mv scratch/dev_docs /u/u0/httpd/html Line 385  $ mv scratch/dev_docs /u/u0/httpd/html
385      <sect2 id="build_tools">      <sect2 id="build_tools">
386        <title>Build Tools</title>        <title>Build Tools</title>
387    
388        <para>Many Open Source projects use the "GNU Autotools" to help        <para>Many Open Source projects use the "GNU Autotools" to help streamline
389        streamline the build process for various Unix and Unix-like          the build process for various Unix and Unix-like architectures.  For a
390        architectures.  For a user, the result is the common "configure"          user, the result is the common "configure" (that is,
391        (that is, "<filename>./configure && make && make          "<filename>./configure && make && make install</filename>") commands.
392        install</filename>") commands.  For MITgcm, the process is          For MITgcm, the process is similar.  Typical commands are:</para>
       similar.  Typical commands are:</para>  
393    
394  <screen>  <screen>
395  $ genmake -mods=../code    $ genmake -mods=../code
396  $ make depend    $ make depend
397  $ make    $ make
398  </screen>  </screen>
399    
400        <para>The following sections describe the individual steps in        <para>The following sections describe the individual steps in the build
401        the build process.</para>          process.</para>
402          
403        <sect3 id="genmake">        <sect3 id="genmake">
404          <title>The <filename>genmake2</> Utility</title>          <title>The <filename>genmake2</> Utility</title>
405    
406          <para><emphasis>Please note that the older          <para><emphasis>Please note that the older <filename>genmake</> is
407          <filename>genmake</> is deprecated and will eventually              deprecated and will eventually be replaced by <filename>genmake2</>.
408          be replaced by <filename>genmake2</>.  This HOWTO only              This HOWTO only describes the newer tool.</emphasis></para>
409          describes the newer tool.</emphasis></para>  
410            <para>The first step in any MITgcm build is to create a Unix-style
411          <para>The first step in any MITgcm build is to create a            <filename>Makefile</filename> which will be parsed by
412          Unix-style <filename>Makefile</filename> which will be parsed            <filename>make</filename> to specify how to compile the MITgcm source
413          by <filename>make</filename> to specify how to compile the            files.  For more detailed descriptions of what the make tools are and
414          MITgcm source files.  For more detailed descriptions of what            how they are used, please see:</para>
         the make tools are and how they are used, please see:</para>  
415    
416          <itemizedlist>          <itemizedlist>
417            <listitem>            <listitem>
418              <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">
419                    http://www.gnu.org/software/make/make.html</></para>
420            </listitem>            </listitem>
421            <listitem>            <listitem>
422              <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/">
423                    http://www.oreilly.com/catalog/make2/</></para>
424            </listitem>            </listitem>
425          </itemizedlist>          </itemizedlist>
426    
427          <para>Due to the poor handling of soft-links and other bugs          <para>Genmake can often be invoked successfully with a command line as
428          common with the <filename>make</filename> versions provided by          simple as:</para>
429          commercial Unix vendors, GNU <filename>make</filename>  
430          (sometimes called <filename>gmake</filename>) should be  <screen>
431          preferred.</para>    $ genmake2 -mods=../code
432    </screen>
433          <para>As the name implies, <filename>genmake2</filename>  
434          generates a <filename>Makefile</filename>.  It does so by          <para>However, some systems (particularly commercial Unixes that lack a
435          first parsing the information supplied from the following            more modern "/bin/sh" implementation or that have shells installed in
436          sources</para>            odd locations) may require an explicit shell invocation such as one of
437              the following: </para>
438    
439    <screen>
440      $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
441      $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
442    </screen>
443    
444            <para>The genmake2 code has been written in a Bourne and BASH (v1)
445            compatible syntax so it should work with most "sh" and all recent "bash"
446            implementations.</para>
447    
448            <para>As the name implies, <filename>genmake2</filename> generates a
449              <filename>Makefile</filename>.  It does so by first parsing the
450              information supplied from the following sources</para>
451    
452          <orderedlist>          <orderedlist>
453            <listitem>            <listitem>
454              <para>a <filename>gm_local</filename> file in the current              <para>a <filename>gemake_local</filename> file in the current
455              directory</para>                directory</para>
456            </listitem>            </listitem>
457            <listitem>            <listitem>
458              <para>directly from command-line options</para>              <para>directly from command-line options</para>
459            </listitem>            </listitem>
460            <listitem>            <listitem>
461              <para>an "options file" as specified by the command-line              <para>an "options file" as specified by the command-line option
462              option <filename>-optfile='FILENAME'</filename></para>                <filename>-optfile='FILENAME'</filename></para>
463            </listitem>            </listitem>
464          </orderedlist>          </orderedlist>
465    
466          <para>then checking certain dependency rules (the package          <para>then checking certain dependency rules (the package dependencies),
467          dependencies), and then writing a            and finally writing a <filename>Makefile</filename> based upon the
468          <filename>Makefile</filename> based upon the source code that            source code that it finds.  For convenience within various Unix
469          it finds.  For convenience with the various Unix shells,            shells, <filename>genmake2</> supports both "long"- and "short"-style
470          <filename>genmake2</> supports both "long"- and "shor"-style            options.  A complete list of the available options can be obtained
471          options.  A complete list of the available options can be            from:</para>
         obtained from:</para>  
472    
473  <screen>  <screen>
474  $ genmake2 -help    $ genmake2 -help
475  </screen>  </screen>
476    
477          <para>The most important options for <filename>genmake2</>          <para>The most important options for <filename>genmake2</> are:</para>
         are:</para>  
478    
479          <variablelist>          <variablelist>
480    
481            <varlistentry>            <varlistentry>
482              <term><filename>--optfile=/PATH/FILENAME</></term>              <term><filename>--optfile=/PATH/FILENAME</></term>
483    
484              <listitem>              <listitem>
485                <para>This specifies the "options file" that should be                <para>This specifies the "options file" that should be used for a
486                used for a particular build.  The options file is a                  particular build.  The options file is a convenient and
487                convenient and machine-indepenent way of specifying                  machine-indepenent way of specifying parameters such as the
488                parameters such as the FORTRAN compiler                  FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
489                (<filename>FC=</>), FORTRAN compiler optimization flags                  optimization flags (<filename>FFLAGS=</>), and the locations of
490                (<filename>FFLAGS=</>), and the locations of various                  various platform- and/or machine-specific tools
491                platform- and/or machine-specific tools                  (eg. <filename>MAKEDEPEND=</>).  As with <filename>genmake2</>,
492                (eg. <filename>MAKEDEPEND=</>).  As with                  all options files should be written to be compatible with
493                <filename>genmake2</>, all options files should be                  Bourne--shell ("sh" or "BASH v1") syntax.  Examples of various
494                written a BASH v1-compatible syntax.  Examples of                  options files can be found in
495                various options files can be found in                  <filename>$ROOTDIR/tools/build_options</>.</para>
496                <filename>$ROOTDIR/tools/build_options</>.  Everyone is  
497                encouraged to submit their options files to the MITgcm                <para>If no "optfile" is specified (either through the command lin
498                project for inclusion (please send to                  or the environment variable), genmake2 will try to make a
499                <email>MITgcm-support@mitgcm.org</email>).  We are                  reasonable guess from the list provided in
500                particularly grateful for options files tested on new or                  <filename>$ROOTDIR/tools/build_options</>.  The method used for
501                unique platforms!</para>                  making this guess is to first determine the combination of
502                    operating system and hardware (eg. "linux_ia32") and then find a
503                    working Fortran compiler within the user's path.  When these
504                    three items have been identified, genmake2 will try to find an
505                    optfile that has a matching name. </para>
506    
507                  <para>Everyone is encouraged to submit their options files to the
508                    MITgcm project for inclusion (please send to
509                    <email>MITgcm-support@mitgcm.org</email>).  We are particularly
510                    grateful for options files tested on new or unique
511                    platforms!</para>
512              </listitem>              </listitem>
513    
514            </varlistentry>            </varlistentry>
515    
516            <varlistentry>            <varlistentry>
517              <term><filename>-pdepend=/PATH/FILENAME</></term>              <term><filename>-pdepend=/PATH/FILENAME</></term>
518    
519              <listitem>              <listitem>
520                <para>This specifies the dependency file used for                <para>This specifies the dependency file used for packages.  If
521                packages.  If not specified, the default dependency file                not specified, the default dependency file is
522                is <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for                <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
523                this file is parsed on a line-by-line basis where each                parsed on a line-by-line basis where each line containes either a
524                line containes either a comment ("#") or a simple                comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
525                "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or                where the "+" or "-" symbol specifies a "must be used with" or a
526                "-" symbol specifies a "must be used with" or a "must                "must not be used with" relationship, respectively.  If no rule is
527                not be used with" relationship, respectively.  If no                specified, then it is assumed that the two packages are compatible
528                rule is specified, then it is assumed that the two                and will function either with or without each other.</para>
               packages are compatible and will function either with or  
               without each other.</para>  
529              </listitem>              </listitem>
530            </varlistentry>            </varlistentry>
531    
# Line 536  $ genmake2 -help Line 541  $ genmake2 -help
541            </varlistentry>            </varlistentry>
542    
543            <varlistentry>            <varlistentry>
544              <term><filename></>-mods=DIR</term>              <term><filename>-adof=/path/to/file</></term>
545              <term><filename></>-mods='DIR1 [DIR2 ...]'</term>              <term><filename>-adoptfile=/path/to/file</></term>
546              <listitem>              <listitem>
547                <para>This option specifies a list of directories                <para>This option specifies the "adjoint" or automatic
548                containing "modifications".  These are files that may                  differentiation options file to be used.  The file is analogous
549                (or may not) exist in the main MITgcm source tree but                  to the "optfile" defined above but it specifies information for
550                will be overridden by any identically-named sources                  the AD build process.  The default file is located in <filename>
551                within the "MODS" directories.</para>                  $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
552                    defines the "TAF" and "TAMC" compilers.  An alternate version is
553                    also available at <filename>
554                    $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
555                    newer "STAF" compiler.  As with any compilers, it is helpful to
556                    have their directories listed in your $PATH environment
557                    variable.</para>
558                </listitem>
559              </varlistentry>
560    
561              <varlistentry>
562                <term><filename>-mods=DIR</></term>
563                <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
564                <listitem>
565                  <para>This option specifies a list of directories containing
566                    "modifications".  These directories contain files with names
567                    that may (or may not) exist in the main MITgcm source tree but
568                    will be overridden by any identically-named sources within the
569                    "MODS" directories.  The order of precedence for this
570                    "name-hiding" is as follows:</para>
571                  
572                  <itemizedlist>
573                    <listitem><para>"MODS" directories (in the order given)
574                      </para></listitem>
575                    <listitem><para>Packages either explicitly specified or
576                        provided by default (in the order given)</para></listitem>
577                    <listitem><para>Packages included due to package dependencies
578                        (in the order that that package dependencies are
579                        parsed)</para></listitem>
580                    <listitem><para>The "standard dirs" (which may have been
581                        specified by the "-standarddirs" option)</para></listitem>
582                  </itemizedlist>
583    
584                </listitem>
585              </varlistentry>
586    
587              <varlistentry>
588                <term><filename>-make=/path/to/gmake</></term>
589                <listitem>
590                  <para>Due to the poor handling of soft-links and other bugs common
591                    with the <filename>make</> versions provided by commercial Unix
592                    vendors, GNU <filename>make</filename> (sometimes called
593                    <filename>gmake</filename>) should be preferred.  This option
594                    provides a means for specifying the make program to be
595                    used.</para>
596              </listitem>              </listitem>
597            </varlistentry>            </varlistentry>
598    
599          </variablelist>          </variablelist>
600                    
601          <para>A successful run of <filename>genmake2</> will produce          <para>A successful run of <filename>genmake2</> will produce a
602          both a <filename>Makefile</> and a locally modified copy of            <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
603          the specified <filename>CPP_OPTIONS.h</> file.  The local copy            various convenience files used for the automatic differentiation
604          of <filename>CPP_OPTIONS.h</> will contain a list of            process.</para>
605          <filename>genmake2</>-created #DEFINE and #UNDEF statements  
606          that reflect the list of packages that will be compiled into          <para>In general, it is best to use <filename>genmake2</> on a "clean"
607          the code (either directly through enable/disable/defaults            directory that is free of all source (*.[F,f],*.[F,f]90) and header
608          options or indirectly through dependencies).</para>            (*.h,*.inc) files.  Generally, this can be accomplished in an
609              "un-clean" directory by running "make CLEAN" followed by "make
610          <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>  
611    
612        </sect3>        </sect3>
613    
614        <sect3 id="makefile_use">        <sect3 id="makefile_use">
615          <title>Using <filename>Makefile</></title>          <title>Using the <filename>Makefile</></title>
616    
617          <para>Once a <filename>Makefile</> has been created, one can          <para>Once a <filename>Makefile</> has been created using
618          build the executable using:</para>            <filename>genmake2</>, one can build a "standard" (forward
619              simulator) executable using:</para>
620    
621  <screen>  <screen>
622  $ make CLEAN    $ make CLEAN
623  $ make depend    $ make depend
624  $ make    $ make
625  </screen>  </screen>
626    
627          <para>The "make CLEAN" step will remove any local source          <para>The "make CLEAN" step will remove any stale source files, include
628          files, include files, and links.  It is strongly recommended            files, and links.  It is strongly recommended for "un-clean"
629          for "un-clean" directories which may contain the (partial?)            directories which may contain the (perhaps partial) results of
630          results of previous builds.  Such "debris" can interfere with            previous builds.  Such "debris" can interfere with the next stage of
631          the next stage of the build.</para>            the build.</para>
632    
633          <para>The "make depend" step will create a large number of          <para>The "make depend" step will create a large number of symbolic
634          symbolic links from the local directory to the source file            links from the local directory to the source file locations.  It also
635          locations.  It also parses these files and creates an            parses these files and creates an extensive list of dependencies
636          extensive list of dependencies within the            within the <filename>Makefile</> itself.  The links that exist at this
637          <filename>Makefile</> itself.  The links that exist at this            stage are mostly "large F" files (*.F and *.F90) that need to be
638          stage are mostly "large F" files (*.F and *.F90) that need to            processed by a C preprocessor ("CPP").  Since "make depend" edits the
639          be processed by a C preprocessor ("CPP").            <filename>Makefile</>, it is important not to skip this step!</para>
640          </para>  
641            <para>The final "make" invokes the C preprocessor to produce the "little
642          <para>The final "make" invokes the C preprocessor to produce            f" files (*.f and *.f90) and then compiles them to object code using
643          the "little f" files (*.f and *.f90) and then compiles them to            the specified FORTRAN compiler and options.  An intermediate script is
644          object code using the specified FORTRAN compiler and options.            often used during this stage to further process (usually, make simple
645          An intermediate script is often used during this stage to            substitutions) custom definitions such as variable types within the
646          further process (usually, make simple substitutions) custom            source files.  This additional stage is necessary in order to overcome
647          definitions such as variable types within the source files.            some of the inconsistencies in the sizes of objects (bytes) between
648          This additional stage is necessary in order to overcome some            different compilers. The result of the build process is an executable
649          of the inconsistencies in the sizes of objects (bytes) between            with the name <filename>mitgcmuv</>.</para>
650          different compilers.</para>  
651            <para>In addition to the forward simulator described above, the
652              <filename>Makefile</> also has a number of targets that can be used to
653              produce various adjoint and tangent-linear builds for optimization and
654              other parameter-sensitivity problems.  The additional targets within
655              the <filename>Makefile</> are:</para>
656    
657            <variablelist>
658    
659              <varlistentry>
660                <term><filename>make adall</></term>
661                <listitem>
662                  <para>This target produces an <filename>mitgcmuv_ad</> executable
663                    using the <filename>taf</> or <filename>staf</> adjoint
664                    compiler.  See the <filename>genmake2</> "-adof" option for
665                    compiler selection.</para>
666                </listitem>
667              </varlistentry>
668    
669              <varlistentry>
670                <term><filename>make ftlall</></term>
671                <listitem>
672                  <para>Similar to <filename>make adall</> above, this
673                    produces...</para>
674                </listitem>
675              </varlistentry>
676    
677            </variablelist>
678    
679          <para>Please report compilation failures or other problems to          <para>Please report any compilation failures or other build problems to
680          <email>MITgcm-support@mitgcm.org</email>.</para>            the <email>MITgcm-support@mitgcm.org</email> list.</para>
681    
682        </sect3>        </sect3>
683    
# Line 613  $ make Line 686  $ make
686      <sect2 id="verification">      <sect2 id="verification">
687        <title>The Verification Suite</title>        <title>The Verification Suite</title>
688    
689        <para>The MITgcm CVS tree (within the        <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
690        <filename>$ROOTDIR/verification/</> directory) includes more          directory) includes more than a dozen examples intended for regression
691        than a dozen examples intended for regression testing.  Each one          testing.  Each one of these example directories contains "known-good"
692        of these example directories contains "known-good" output files          output files along with all the input (including both code and data
693        along with all the input (including both code and data files)          files) required for their re-calculation.  These example directories are
694        required for their re-calculation.  These example directories          further broken down into sets of subdirectories
695        are further broken down into sets of subdirectories          (eg. <filename>/input</>, <filename>/code</>) intended to expedite the
696        (eg. <filename>/input</>, <filename>/code</>) intended to          testing process.</para>
       expedite the testing process.</para>  
697    
698        <sect3 id="testreport">        <sect3 id="testreport">
699          <title>The <filename>testreport</> Utility</title>          <title>The <filename>testreport</> Utility</title>
700    
701          <para>Also included in <filename>$ROOTDIR/verification/</> are          <para>Also included in <filename>$ROOTDIR/verification/</> are shell
702          shell scripts for automated testing.  The newest script (which            scripts for automated testing.  The newest script (which was written
703          was written to work with <filename>genmake2</>) is called            to work with <filename>genmake2</>) is called <filename>testreport</>.
704          <filename>testreport</>.  Ths script can be used to build the            This script can be used to build different versions of the MITgcm
705          different versions of the MITgcm code, run the various            code, run the various examples, compare the output, and (if specified)
706          examples, compare the output, and (if specified) email the            email the results of each one of these tests to a central
707          results of each one of these tests to a central            repository.</para>
708          repository.</para>  
709            <para>On some systems, the testreport script can be run with a command
710            line as simple as:</para>
711    
712    <screen>
713      $ cd verification
714      $ ./testreport -ieee
715    </screen>
716    
717            <para>However, some systems (those lacking or wiht a broken "/bin/sh")
718              may require an explicit shell invocation such as:</para>
719    
720    <screen>
721      $ sh ./testreport -ieee -t 'exp0 exp4'
722      $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
723    </screen>
724    
725          <para>The <filename>testreport</> script accepts a number of          <para>The <filename>testreport</> script accepts a number of
726          command-line options which can be listed using the            command-line options which can be listed using the <filename>-help</>
727          <filename>-help</> option.  The most important ones are:</para>            option.  The most important ones are:</para>
728    
729          <variablelist>          <variablelist>
730    
731            <varlistentry>            <varlistentry>
732                <term><filename>-ieee</></term>
733                <listitem>
734                  <para>If allowed by the compiler (as defined in the "optfile"),
735                    use IEEE arithmetic.  This option, along with the GCC compiler,
736                    is how the standard results were produced.</para>
737                </listitem>
738              </varlistentry>
739    
740              <varlistentry>
741              <term><filename>-tdir TESTDIR</></term>              <term><filename>-tdir TESTDIR</></term>
742              <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>              <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
743              <listitem>              <listitem>
744                <para>This option specifies the test directory or list                <para>This option specifies the test directory or list of test
745                of test directories that should be used.  Each of these                  directories that should be used.  Each of these entries should
746                entries should exactly (note: they're case sensitive!)                  exactly (note: they are case sensitive!) match the names of
747                match the names of directries in                  directries in <filename>$ROOTDIR/verification/</>.  If this
748                <filename>$ROOTDIR/verification/</>.  If this option is                  option is omitted, then all directories that are properly
749                omitted, then all directories that are properly                  formatted (that is, containing an <filename>input</>
750                formatted (that is, containing an <filename>input</>                  sub-directory and a <filename>results/output.txt</> file) will
751                sub-directory and example output) will be used.</para>                  be used.</para>
752              </listitem>              </listitem>
753            </varlistentry>            </varlistentry>
754    
# Line 660  $ make Line 756  $ make
756              <term><filename>-optfile=/PATH/FILENAME</></term>              <term><filename>-optfile=/PATH/FILENAME</></term>
757              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
758              <listitem>              <listitem>
759                <para>This specifies a list of "options files" that will                <para>This specifies a list of "options files" that will be passed
760                be passed to <filename>genmake2</>.  If multiple options                  to <filename>genmake2</>.  If multiple options files are used
761                files are used (say, to test different compilers or                  (say, to test different compilers or different sets of options
762                different sets of options for the same compiler), then                  for the same compiler), then each options file will be used with
763                each options file will be used with each of the test                  each of the test directories.</para>
               directories.</para>  
764              </listitem>              </listitem>
765            </varlistentry>            </varlistentry>
766    
# Line 674  $ make Line 769  $ make
769              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
770              <listitem>              <listitem>
771                <para>Send the results (namely, <filename>output.txt</>,                <para>Send the results (namely, <filename>output.txt</>,
772                <filename>gm_local</>, <filename>gm_state</>, and                  <filename>genmake_local</>, <filename>genmake_state</>, and
773                <filename>Makefile</>) to the specified email addresses.                  <filename>Makefile</>) to the specified email addresses.  The
774                The results are gzipped, placed in a tar file, MIME                  results are gzipped, placed in a tar file, MIME encoded, and
775                encoded, and sent to an @mitgcm.org address.  If no                  sent to the specified address.  If no email addresses are
776                email addresses are specified, no mail is sent.</para>                  specified, no mail is sent.</para>
777                </listitem>
778              </varlistentry>
779    
780              <varlistentry>
781                <term><filename>-mpi</></term>
782                <listitem>
783                  <para>If the necessary files
784                  (<filename>TESTDIR/code/CPP_EEOPTIONS.h_mpi</> and
785                  <filename>TESTDIR/code/SIZE.h_mpi</>) exist, then use them for an
786                  MPI--enabled run.  Note that the use of MPI typically requires a
787                  special command option (see "-command" below) to invoke the MPI
788                  executable.  Examples of PBS scripts using MPI with testreport can be
789                  found in the <ulink
790                  url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
791                  MITgcm-contrib area</ulink></para>
792                </listitem>
793              </varlistentry>
794    
795              <varlistentry>
796                <term><filename>-command='some command to run'</></term>
797                <listitem>
798                  <para>For some tests, particularly MPI runs, the default "make
799                  output.txt" is not sufficient.  This option allows a more general
800                  command (or shell script) to be invoked.  Examples of PBS scripts
801                  using MPI with testreport can be found in the <ulink
802                  url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
803                  MITgcm-contrib area</ulink></para>
804              </listitem>              </listitem>
805            </varlistentry>            </varlistentry>
806    
807          </variablelist>          </variablelist>
808    
809          <para>The <filename>testreport</> script will write progress          <para>The <filename>testreport</> script will write progress to the
810          to the screen (stdout) as it runs.  In addition, it will            screen (stdout) as it runs.  In addition, it will create a
811          create a <filename>summary.txt</> file that contains a brief            <filename>tr_out.txt</> file that contains a brief comparison of the
812          comparison of the current output with the "known-good"            current output with the "known-good" output.</para>
         output.</para>  
813    
814        </sect3>        </sect3>
815    
816      </sect2>      </sect2>
817    
818    
819      <sect2 id="packages">      <sect2 id="packages">
820        <title>Creating MITgcm Packages</title>        <title>Creating MITgcm Packages</title>
821    
822        <para>Optional parts of code have been separated from the MITgcmUV        <para>Optional parts of code have been separated from the MITgcmUV core
823        core driver code and organised into packages. The packaging          driver code and organised into packages.  The packaging structure
824        structure provides a mechanism for maintaining suites of code,          provides a mechanism for maintaining suites of code, specific to
825        specific to particular classes of problems, in a way that is          particular classes of problems, in a way that is cleanly separated from
826        cleanly separated from the generic fluid dynamical          the generic fluid dynamical engine.</para>
827        engine.</para>  
828          <para>The MITgcmUV packaging structure is described below using generic
829        <para>The MITgcmUV packaging structure is described below using          package names ${pkg}.  A concrete examples of a package is the code for
830        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>  
831    
832      </sect2>      </sect2>
833    
# Line 766  o  Each package gets its runtime configu Line 886  o  Each package gets its runtime configu
886     Package runtime config. options are imported     Package runtime config. options are imported
887     into a common block held in a header file     into a common block held in a header file
888     called "${PKG}.h".     called "${PKG}.h".
889       Note: In some packages, the header file "${PKG}.h" is splitted
890       into "${PKG}_PARAMS.h" that contains the package parameters and
891       ${PKG}_VARS.h" for the field arrays.
892    
893  o  The core driver part of the model can check  o  The core driver part of the model can check
894     for runtime enabling or disabling of individual packages     for runtime enabling or disabling of individual packages
# Line 788  CPP Flags Line 911  CPP Flags
911      1. Within the core driver code flags of the form      1. Within the core driver code flags of the form
912         ALLOW_${PKG} are used to include or exclude         ALLOW_${PKG} are used to include or exclude
913         whole packages. The ALLOW_${PKG} flags are included         whole packages. The ALLOW_${PKG} flags are included
914         from a PKG_CPP_OPTIONS block which is currently         from a PACKAGES_CONFIG.h file that is automatically
915           generated by genmake2 (see genmake2 section).
916         held in-line in the CPP_OPTIONS.h header file.         held in-line in the CPP_OPTIONS.h header file.
917         e.g.         e.g.
918    
919         Core model code .....         Core model code .....
920    
921           #include "PACKAGES_CONFIG.h"
922         #include "CPP_OPTIONS.h"         #include "CPP_OPTIONS.h"
923           :           :
924           :           :
# Line 805  CPP Flags Line 930  CPP Flags
930    
931      2. Within an individual package a header file,      2. Within an individual package a header file,
932         "${PKG}_OPTIONS.h", is used to set CPP flags         "${PKG}_OPTIONS.h", is used to set CPP flags
933         specific to that package. It is not recommended         specific to that package. It also includes
934         to include this file in "CPP_OPTIONS.h".         "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
935    
936    
937  Package Boot Sequence  Package Boot Sequence
# Line 828  Package Boot Sequence Line 953  Package Boot Sequence
953       &       CALL ${PKG}_READPARMS( retCode )       &       CALL ${PKG}_READPARMS( retCode )
954          #endif          #endif
955    
956      2. S/R PACKAGES_CHECK()      3. S/R PACKAGES_INIT_FIXED()
957                :
958            #ifdef ALLOW_${PKG}
959              if ( use${Pkg} )
960         &       CALL ${PKG}_INIT_FIXED( retCode )
961            #endif
962    
963        4. S/R PACKAGES_CHECK()
964              :              :
965          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
966            if ( use${Pkg} )            if ( use${Pkg} )
# Line 838  Package Boot Sequence Line 970  Package Boot Sequence
970       &       CALL PACKAGES_CHECK_ERROR('${PKG}')       &       CALL PACKAGES_CHECK_ERROR('${PKG}')
971          #endif          #endif
972    
973      3. S/R PACKAGES_INIT()      5. S/R PACKAGES_INIT_VARIABLES()
974              :              :
975          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
976            if ( use${Pkg} )            if ( use${Pkg} )
977       &       CALL ${PKG}_INIT( retCode )       &       CALL ${PKG}_INIT_VARIA( )
978            #endif
979    
980    Package Output
981    ==============
982         6. S/R DO_THE_MODEL_IO
983    
984            #ifdef ALLOW_${PKG}
985              if ( use${Pkg} )
986         &       CALL ${PKG}_DIAGS( )     [ or CALL ${PKG}_OUTPUT( ) ]
987          #endif          #endif
988    
989         7. S/R PACKAGES_WRITE_PICKUP()
990    
991            #ifdef ALLOW_${PKG}
992              if ( use${Pkg} )
993         &       CALL ${PKG}_WRITE_PICKUP( )
994            #endif
995    
996  Description  Description
997  ===========  ===========
# Line 852  Description Line 999  Description
999        - ${PKG}_READPARMS()        - ${PKG}_READPARMS()
1000      is responsible for reading      is responsible for reading
1001      in the package parameters file data.${pkg}, and storing      in the package parameters file data.${pkg}, and storing
1002      the package parameters in "${PKG}.h".      the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
1003      -> called in INITIALISE_FIXED      -> called from INITIALISE_FIXED in PACKAGES_READPARMS
1004    
1005         - ${PKG}_INIT_FIXED()
1006        is responsible for completing the internal setup of a package.
1007        -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
1008        note: 1) some pkg use instead:
1009                 CALL ${PKG}_INITIALISE  ( or the old form CALL ${PKG}_INIT )
1010              2) for simple pkg setup, this part is done inside ${PKG}_READPARMS
1011    
1012       - ${PKG}_CHECK()       - ${PKG}_CHECK()
1013      is responsible for validating      is responsible for validating
# Line 862  Description Line 1016  Description
1016      need to check. This is done through header files "${PKG}.h".      need to check. This is done through header files "${PKG}.h".
1017      It is assumed that parameters owned by other packages      It is assumed that parameters owned by other packages
1018      will not be reset during ${PKG}_CHECK().      will not be reset during ${PKG}_CHECK().
1019      -> called in INITIALISE_FIXED      -> called from INITIALISE_FIXED in PACKAGES_CHECK
1020    
1021       - ${PKG}_INIT()       - ${PKG}_INIT_VARIA()
1022      is responsible for completing the      is responsible for fill-in all package variables with an initial value.
1023      internal setup of a package. This routine is called after      Contains eventually a call to ${PKG}_READ_PICKUP that will read
1024      the core model state has been completely initialised      from a pickup file the package variables required to restart the model.
1025      but before the core model timestepping starts.      This routine is called after the core model state has been completely
1026      -> called in INITIALISE_VARIA      initialised but before the core model timestepping starts.
1027        -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
1028        note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
1029         use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
1030         form ${PKG}_INIT
1031    
1032         - ${PKG}_DIAGS()      [or ${PKG}_OUTPUT( ) ]
1033         is responsible for writing time-average fields to output files
1034         (but the cumulating step is done within the package main S/R).
1035         Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1036         and write snap-shot fields that are hold in common blocks. Other
1037         temporary fields are directly dump to file where they are available.
1038         NOTE: 1) ${PKG}_OUTPUT is progressively replacing ${PKG}_DIAGS()
1039                  to avoid confusion with pkg/diagnostics functionality.
1040               2) the output part is not yet in a standard form and might still
1041                  evolve a lot.
1042        -> called within DO_THE_MODEL_IO
1043    
1044         - ${PKG}_WRITE_PICKUP()
1045         is responsible for writing a package pickup file when necessary for
1046         a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1047        -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1048    
1049  Summary  Summary
1050  =======  =======
# Line 890  Summary Line 1065  Summary
1065    -----------------------    -----------------------
1066    * ${PKG}_OPTIONS.h     has further package-specific CPP options    * ${PKG}_OPTIONS.h     has further package-specific CPP options
1067    * ${PKG}.h             package-specific common block variables, fields    * ${PKG}.h             package-specific common block variables, fields
1068       or  ${PKG}_PARAMS.h   package-specific common block parameters
1069       and ${PKG}_VARS.h     package-specific common block fields
1070    
1071  - FORTRAN source files  - FORTRAN source files
1072    -----------------------    -----------------------
1073    * ${pkg}_readparms.F   reads parameters from file data.${pkg}    * ${pkg}_readparms.F    reads parameters from file data.${pkg}
1074    * ${pkg}_check.F       checks package dependencies and consistencies    * ${pkg}_init_fixed.F   complete the package setup
1075    * ${pkg}_init.F        initialises package-related fields    * ${pkg}_check.F        checks package dependencies and consistencies
1076    * ${pkg}_... .F        package source code    * ${pkg}_init_varia.F   initialises package-related fields
1077      * ${pkg}_... .F         package source code
1078      * ${pkg}_diags.F        write output to file.
1079       or ${pkg}_output.F     write output to file.
1080      * ${pkg}_write_pickup.F write a package pickup file to restart the model
1081    
1082      New: Subroutine in one package (pkgA) that only contains code which
1083           is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
1084           will be named: pkgA_pkgB_something.F
1085    
1086  - parameter file  - parameter file
1087    -----------------------    -----------------------
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.8
  ViewVC Help
Powered by ViewVC 1.1.22