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

Diff of /MITgcm/doc/devel_HOWTO.sgml

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

-revision 1.4 by edhill,
Thu Nov 20 00:01:42 2003 UTC
+revision 1.15 by jmc,
Tue Mar  1 01:33:19 2011 UTC
 Line 1
  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
- <article id="MITgcm-Development-HOWTO">
  <!--
- Build commands:
+  $Header$
-   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
  -->
+ <article id="MITgcm-Development-HOWTO">
    <articleinfo>
      <title>MITgcm Development HOWTO</title>
-Line 30 
 Build commands:
+Line 26 
 Build commands:
            Initial version.
          </revremark>
        </revision>
+       <revision>
+         <revnumber>0.02</revnumber>
+         <date>2010-01-21</date>
+         <authorinitials>jmc</authorinitials>
+         <revremark>
+           update links.
+         </revremark>
+       </revision>
+       <revision>
+         <revnumber>0.03</revnumber>
+         <date>2010-04-25</date>
+         <authorinitials>jmc</authorinitials>
+         <revremark>
+           Add subsection "Developer settings" (under CVS Repository).
+         </revremark>
+       </revision>
      </revhistory>
      <abstract>
-Line 45 
 Build commands:
+Line 57 
 Build commands:
      <sect2>
        <title>New Versions of This Document</title> <para>You can
        obtain the latest version of this document <ulink
-       url="http://mitgcm.org/dev_docs/devel_HOWTO/">online</ulink> in
+       url="http://mitgcm.org/public/docs.html">online</ulink> in
        various formats.</para>
      </sect2>
      <sect2>
-Line 63 
 Build commands:
+Line 75 
 Build commands:
      <sect2>
        <title>User Manual</title>
-       <para>Before jumping into
+       <para>Before jumping into development, please familiarize yourself with
-       development, please familiarize yourself with the MITgcm user
+         the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
-       manual which is available <ulink
+         </ulink>.  This document contains volumes of useful information and is
-       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>
-       <para>Also, a "snapshot" or<ulink
+       <!--
+       <para>Also, a "snapshot" or <ulink
        url="http://mitgcm.org/dev_docs/">development version</ulink> of
        the user manual may be available, though this is only put on the
        web for testing purposes.</para>
+       -->
      </sect2>
      <sect2>
-Line 102 
 Build commands:
+Line 114 
 Build commands:
    <sect1 id="cvs">
      <title>CVS Repository</title>
      <sect2>
        <title>Layout</title>
-Line 112 
 Build commands:
+Line 125 
 Build commands:
        others.  The tree currently resembles:</para>
  <programlisting>gcmpack/
-   MITgcm-contrib        contributed code
+   CVSROOT               -hidden-
-   CS-regrid             goes into utils
-   cvspolicy.html        -save-
-   CVSROOT               -save-
-   development           experimental stuff
-   manual                -save-
-   misc                  -?-
    MITgcm                code
-        adjoint                  fold into genmake
+        bin                      empty
-        bin                      stub for ecco build
+        doc                      basic developpment documentation
-        compare01                old from 20th century
+        eesupp                   execution environment support code (wrapper)
-        diags                    timeave f77 in pkgs now
+        exe                      empty
-        doc                      tags -- connect to real docs?
+        jobs                     runtime shell scripts for
-        eesupp                   cnh?
+                                   various platforms (not maintained)
-        exe                      ecco user build
+        lsopt                    line search
-     ,- jobs                     runtime shell scripts for
+        model                    main dynamics (core)
-     |                             various platforms
+        optim                    line search interface
-     |  lsopt                    line search
+        pkg                      alternate and optional numerics, etc.
-    m|  model                    main dynamics (core)
+        tools                    scripts to build (and test)
-    e|    optimization_drivers   ?
+        utils                    pre/post processing tools (matlab, ..)
-    r|  optim                    line search interface
+        verification             standard regression tests + examples
-    g|  pkg                      alternate and optional numerics, etc.
+                                       + documented examples (tutorials)
-    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
+   MITgcm_contrib        contributed code
-   mitgcmdoc -> manual   -remove-
+   acesgrid.org          build acesgrid web site
+   development           experimental stuff
+   gfd_lab               -?-
+   manual                source of MITgcm documentation
    mitgcm.org            build web site
-   models                -?-
+   old_develop           old and early development source
-   packages              -?-
+        misc                 -?-
-   preprocess            -?-
+        models               -?-
-   tmp                   -?-
+        packages             -?-
+        preprocess           -?-
+   pdfs                  some pdfs
+   planetinabottle.org   unfinished web site
+   www.ecco-group.org    build ecco web site ?
  </programlisting>
+  <!--
        <para>Efforts are underway to reduce the complexity.</para>
+ -->
      </sect2>
-Line 190 
 Build commands:
+Line 202 
 Build commands:
        <title>Branches</title>
        <para>As shown in the online <ulink
-       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">
-       tree</ulink>, the MITgcm codebase is split into to two branches
+       ViewCVS-generated tree</ulink>, the MITgcm codebase is split into
-       or "lines" under which development proceeds.  These two lines
+       branches or "lines" under which development proceeds.  The main line
-       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.
        </para>
        <para>Periodically, a "Release" branch is formed from the "MAIN"
-       development branch.  This is done in order to create a
+       development branch.  This is done in order to create a relatively stable
-       relatively stable reference point for both users and developers.
+       reference point for both users and developers.  The intent is that once a
-       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.
-       bug-fixes will be added to it.  Meanwhile, development (which
+       Meanwhile, development (which might "break" or otherwise render invalid
-       might "break" or otherwise render invalid the documentation,
+       the documentation, tutorials, and/or examples contained within a release
-       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>
+     </sect2>
+     <sect2>
+       <title> Developer settings </title>
+       <para>CVS is a convenient tool to keep up-to-date a personal copy of the
+       MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html">
+       using CVS </ulink>). The same tool is used by developers to
+       incorporate any change into the repository. However, this later
+       function requires specific settings, as detailed here after:</para>
+       <orderedlist>
+         <listitem>
+           <para> You will need an account (loggin access) to the server
+            "mitgcm.org" with the proper group setting (e.g.,
+             group "gcmctrb" to add/modify code into MITgcm_contrib).
+             This kind of account is granted only upon well motivated request.
+             The access to the server mitgcm.org is through ssh-key authorization
+             which will need to be set properly on both side (on your local machine
+             and on your server account). You need to be able to
+             to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename>
+             in case of different user-name on both sides) to proceed further.</para>
+         </listitem>
+         <listitem>
+           <para> You need to register to the
+         <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs">
+       mitgcm-cvs </ulink> mailing list.
+           This ensures that other developers will receive email notification
+            when you make changes; you will also receive as well such email
+            when others make changes to the repository.
+           </para>
+         </listitem>
+         <listitem>
+           <para> It is highly recommended that you register also to the
+         <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel">
+       mitgcm-devel </ulink> mailing list (expect a short delay for
+        this request to be processed).
+           This list is intended for developer discussions.
+           </para>
+         </listitem>
+         <listitem>
+           <para> The standard anonymous mode (using "cvsanon", as mentionned
+         <ulink url="http://mitgcm.org/public/source_code.html">
+       here </ulink>) does not allow check-in ("cvs commit") permission.
+          Instead, you will need to set our CVS environment as follow:</para>
+ <screen>
+   $ export CVS_RSH=ssh
+   $ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
+ </screen>
+           <para> After downloading a directory, e.g.: <filename>myCopy</filename>,
+            from the CVS repository (e.g.,
+             <filename>MITgcm_contrib/thisPart</filename>) using the command:</para>
+ <screen>
+   $ cvs co -P -d myCopy MITgcm_contrib/thisPart
+ </screen>
+           <para> the type of CVS environment which has been used
+            is stored in the file <filename>myCopy/CVS/Root</filename>
+            and makes it difficult to re-use, for cvs-commit purpose,
+            a cvs local copy (<filename>myCopy</filename>) which was obtained
+            using the CVS anonymous mode.</para>
+         </listitem>
+         <listitem>
+           <para> At this stage, you should be able to send your modified source
+           file (e.g., <filename>src_file</filename>) from your local copy directory
+           (<filename>myCopy</filename>) to the CVS repository
+           (<filename>MITgcm_contrib/thisPart</filename>) using the command
+           "cvs commit":</para>
+ <screen>
+   $ cd myCopy
+   $ cvs -n update        (optional; check if new changes have been made)
+   $ cvs diff src_file    (optional; list your changes)
+   $ cvs commit src_file
+ </screen>
+           <para> It is essential that you provide a short description of the
+           changes you made to <filename>src_file</filename> as you check-in
+           this file (the "cvs commit" command automatically opens your standard
+           editor for this purpose).</para>
+         </listitem>
+       </orderedlist>
      </sect2>
      <sect2>
-       <title>Tagging</title>
+       <title>Main code development</title>
+       <para><emphasis>(formerly named "Tagging" ; this section needs an update)
-       <para>The intent of tagging is to create "known-good"
+         </emphasis></para>
-       checkpoints that developers can use as references.
-       Traditionally, MITgcm tagging has maintained the following
+       <para>The intent of tagging is to create "known-good" checkpoints that
-       conventions:</para>
+       developers can use as references.  Traditionally, MITgcm tagging has
+       maintained the following conventions:</para>
        <orderedlist>
          <listitem>
-           <para>Developer checks out code into a local CVS-managed
+           <para>Developer checks out code into a local CVS-managed directory,
-           directory, makes various changes/additions, tests these
+           makes various changes/additions, tests these edits, and eventually
-           edits, and eventually reaches a point where (s)he is
+           reaches a point where (s)he is satisfied that the changes form a new
-           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>
          </listitem>
          <listitem>
            <para>The developer then runs the <ulink
-           url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">testscript</ulink>
+           url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
-           shell script to see if any problems are introduced.  While
+           testreport</ulink> shell script to see if any problems are introduced.
-           not intended to be exhaustive, the test cases within the
+           While not intended to be exhaustive, the test cases within the
-           verification directory do provide some indication whether
+           verification directory do provide some indication whether gross errors
-           gross errors have been introduced.
+           have been introduced.
            </para>
          </listitem>
-Line 241 
 Build commands:
+Line 334 
 Build commands:
            then:</para>
            <orderedlist>
              <listitem>
-               <para>adds a "checkpointXY_pre" comment (where X is a
+               <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
-               checkpoint number and Y is a letter) to the <ulink
+               number and Y is a letter) to the <ulink
-               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">
-               file and checks it into the CVS repository</para>
+               tag-index</ulink> file and checks it into the CVS
+               repository</para>
              </listitem>
              <listitem>
-               <para>submits the set of changes to the CVS repository
+               <para>submits the set of changes to the CVS repository and adds
-               and adds comments to <filename>tag-index</filename>
+               comments to <filename>tag-index</filename> describing what the
-               describing what the changes are along with a matching
+               changes are along with a matching "checkpointXY_post" entry</para>
-               "checkpointXY_post" entry</para>
              </listitem>
            </orderedlist>
          </listitem>
        </orderedlist>
-       <para>The result of this tagging procedure is a sequence of
+       <para>The result of this tagging procedure is a sequence of development
-       development checkpoints with comments which resembles:</para>
+       checkpoints with comments which resembles:</para>
  <programlisting>
  checkpoint50e_post
-Line 279 
 o fix small problem with in ptracers_wri
+Line 372 
 o fix small problem with in ptracers_wri
  checkpoint50d_pre
  </programlisting>
-       <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
-       the code development.  For example, bugs can be traced to
+       development.  For example, bugs can be traced to individual sets of CVS
-       individual sets of CVS checkins based upon their first
+       checkins based upon their first appearance when comparing the results from
-       appearance when comparing the results from different
+       different checkpoints.</para>
-       checkpoints.</para>
      </sect2>
    </sect1>
-   <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 the Documentation</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 the Documentation</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>
    <sect1 id="coding">
      <title>Coding for MITgcm</title>
-Line 412 
 $ mv scratch/dev_docs /u/u0/httpd/html
+Line 394 
 $ mv scratch/dev_docs /u/u0/httpd/html
          For MITgcm, the process is similar.  Typical commands are:</para>
  <screen>
- $ genmake -mods=../code
+   $ genmake2 -mods=../code
- $ make depend
+   $ make depend
- $ make
+   $ make
  </screen>
        <para>The following sections describe the individual steps in the build
-Line 423 
 $ make
+Line 405 
 $ make
        <sect3 id="genmake">
          <title>The <filename>genmake2</> Utility</title>
-         <para><emphasis>Please note that the older <filename>genmake</> is
+         <para><emphasis>(Note: the older <filename>genmake</>
-             deprecated and will eventually be replaced by <filename>genmake2</>.
+             has been replaced by <filename>genmake2</>)</emphasis></para>
-             This HOWTO only describes the newer tool.</emphasis></para>
          <para>The first step in any MITgcm build is to create a Unix-style
            <filename>Makefile</filename> which will be parsed by
-Line 448 
 $ make
+Line 429 
 $ make
          simple as:</para>
  <screen>
- $ genmake2 -mods=../code
+   $ genmake2 -mods=../code
  </screen>
          <para>However, some systems (particularly commercial Unixes that lack a
-Line 457 
 $ genmake2 -mods=../code
+Line 438 
 $ genmake2 -mods=../code
            the following: </para>
  <screen>
- $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
+   $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
- $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
+   $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
  </screen>
          <para>The genmake2 code has been written in a Bourne and BASH (v1)
-Line 471 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
+Line 452 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
          <orderedlist>
            <listitem>
-             <para>a <filename>gm_local</filename> file in the current
+             <para>a <filename>gemake_local</filename> file in the current
                directory</para>
            </listitem>
            <listitem>
-Line 481 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
+Line 462 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
              <para>an "options file" as specified by the command-line option
                <filename>-optfile='FILENAME'</filename></para>
            </listitem>
+           <listitem>
+             <para> a <filename>packages.conf</filename> file (in the current
+               directory or in one of the "MODS" directories, see below)
+               which contains the specific list of packages to compile
+             </para>
+           </listitem>
          </orderedlist>
          <para>then checking certain dependency rules (the package dependencies),
-Line 491 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
+Line 478 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
            from:</para>
  <screen>
- $ genmake2 -help
+   $ genmake2 -help
  </screen>
          <para>The most important options for <filename>genmake2</> are:</para>
-Line 534 
 $ genmake2 -help
+Line 521 
 $ genmake2 -help
            </varlistentry>
            <varlistentry>
-             <term><filename>-pdepend=/PATH/FILENAME</></term>
+             <term><filename>-adof=/path/to/file</></term>
+             <term><filename>-adoptfile=/path/to/file</></term>
-             <listitem>
-               <para>This specifies the dependency file used for packages.  If
-               not specified, the default dependency file is
-               <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
-               parsed on a line-by-line basis where each line containes either a
-               comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
-               where the "+" or "-" symbol specifies a "must be used with" or a
-               "must not be used with" relationship, respectively.  If no rule is
-               specified, then it is assumed that the two packages are compatible
-               and will function either with or without each other.</para>
-             </listitem>
-           </varlistentry>
-           <varlistentry>
-             <term><filename>-pdefault=PKG</></term>
-             <term><filename>-pdefault='PKG1 [PKG2 PKG3 ...]'</></term>
              <listitem>
-               <para>This option specifies the default set of packages
+               <para>This option specifies the "adjoint" or automatic
-               to be used.  If not set, the default package list will
+                 differentiation options file to be used.  The file is analogous
-               be read from
+                 to the "optfile" defined above but it specifies information for
-               <filename>$ROOTDIR/pkg/pkg_default</>.</para>
+                 the AD build process.  The default file is located in <filename>
+                 $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
+                 defines the "TAF" and "TAMC" compilers.  An alternate version is
+                 also available at <filename>
+                 $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
+                 newer "STAF" compiler.  As with any compilers, it is helpful to
+                 have their directories listed in your $PATH environment
+                 variable.</para>
              </listitem>
            </varlistentry>
-Line 571 
 $ genmake2 -help
+Line 548 
 $ genmake2 -help
                  will be overridden by any identically-named sources within the
                  "MODS" directories.  The order of precedence for this
                  "name-hiding" is as follows:</para>
                <itemizedlist>
                  <listitem><para>"MODS" directories (in the order given)
                    </para></listitem>
-Line 583 
 $ genmake2 -help
+Line 559 
 $ genmake2 -help
                  <listitem><para>The "standard dirs" (which may have been
                      specified by the "-standarddirs" option)</para></listitem>
                </itemizedlist>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-pgroups=/PATH/FILENAME</></term>
+             <listitem>
+               <para>This option specifies the file where package groups are
+               defined.  If not set, the package-groups definition will
+               be read from
+               <filename>$ROOTDIR/pkg/pkg_groups</>.</para>
+               <para>
+               It also contains the default list of packages (defined
+               as the group <filename>"default_pkg_list"</>) which is used
+               when no specific package list (file: <filename>packages.conf</>)
+               is found in current directory or in any "MODS" directory.
+               </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-pdepend=/PATH/FILENAME</></term>
+             <listitem>
+               <para>This specifies the dependency file used for packages.  If
+               not specified, the default dependency file is
+               <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
+               parsed on a line-by-line basis where each line containes either a
+               comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
+               where the "+" or "-" symbol specifies a "must be used with" or a
+               "must not be used with" relationship, respectively.  If no rule is
+               specified, then it is assumed that the two packages are compatible
+               and will function either with or without each other.</para>
              </listitem>
            </varlistentry>
-Line 609 
 $ genmake2 -help
+Line 616 
 $ genmake2 -help
          <para>In general, it is best to use <filename>genmake2</> on a "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
+           "un-clean" directory by running "make Clean" followed by "make
            makefile".</para>
        </sect3>
        <sect3 id="makefile_use">
-         <title>Using <filename>Makefile</></title>
+         <title>Using the <filename>Makefile</></title>
-         <para>Once a <filename>Makefile</> has been created, one can
+         <para>Once a <filename>Makefile</> has been created using
-         build an executable using:</para>
+           <filename>genmake2</>, one can build a "standard" (forward
+           simulator) executable using:</para>
  <screen>
- $ make CLEAN
+   $ make Clean
- $ make depend
+   $ make depend
- $ make
+   $ make
  </screen>
-         <para>The "make CLEAN" step will remove any stale source files, include
+         <para>The "make Clean" step will remove any stale source files, include
            files, and links.  It is strongly recommended for "un-clean"
            directories which may contain the (perhaps partial) results of
-           previous builds.  Such "debris" can interfere with the next stage of
+           previous builds. Such "debris" can interfere with the next stage of
-           the build.</para>
+           the build.
+           A more agressive cleaning option, "make CLEAN", can be used to also
+           remove the executable and output files from a previous run.</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
-Line 647 
 $ make
+Line 657 
 $ make
            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>
+           different compilers. The result of the build process is an executable
+           with the name <filename>mitgcmuv</>.</para>
-         <para>Please report compilation failures or other problems to
+         <para>In addition to the forward simulator described above, the
-           <email>MITgcm-support@mitgcm.org</email>.</para>
+           <filename>Makefile</> also has a number of targets that can be used to
+           produce various adjoint and tangent-linear builds for optimization and
+           other parameter-sensitivity problems.  The additional targets within
+           the <filename>Makefile</> are:</para>
+         <variablelist>
+           <varlistentry>
+             <term><filename>make adall</></term>
+             <listitem>
+               <para>This target produces an <filename>mitgcmuv_ad</> executable
+                 using the <filename>taf</> or <filename>staf</> adjoint
+                 compiler.  See the <filename>genmake2</> "-adof" option for
+                 compiler selection.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>make ftlall</></term>
+             <listitem>
+               <para>Similar to <filename>make adall</> above, this
+                 produces...</para>
+             </listitem>
+           </varlistentry>
+         </variablelist>
+         <para>Please report any compilation failures or other build problems to
+           the <email>MITgcm-support@mitgcm.org</email> list.</para>
        </sect3>
-Line 660 
 $ make
+Line 699 
 $ make
        <title>The Verification Suite</title>
        <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
-         directory) includes more than a dozen examples intended for regression
+         directory) includes many (> 90) examples intended for regression
          testing.  Each one of these example directories contains "known-good"
          output files along with all the input (including both code and data
          files) required for their re-calculation.  These example directories are
-Line 672 
 $ make
+Line 711 
 $ make
          <title>The <filename>testreport</> Utility</title>
          <para>Also included in <filename>$ROOTDIR/verification/</> are shell
-           scripts for automated testing.  The newest script (which was written
+           scripts for automated testing.  The script (which was written
            to work with <filename>genmake2</>) is called <filename>testreport</>.
            This script can be used to build different versions of the MITgcm
            code, run the various examples, compare the output, and (if specified)
-Line 683 
 $ make
+Line 722 
 $ make
          line as simple as:</para>
  <screen>
- $ cd verification
+   $ cd verification
- $ ./testreport -ieee
+   $ ./testreport
  </screen>
          <para>However, some systems (those lacking or wiht a broken "/bin/sh")
            may require an explicit shell invocation such as:</para>
  <screen>
- $ sh ./testreport -ieee -t 'exp0 exp4'
+   $ sh ./testreport -t 'exp2 exp4'
- $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
+   $ /some/path/to/bash ./testreport -t 'ideal_2D_oce lab_sea natl_box'
  </screen>
          <para>The <filename>testreport</> script accepts a number of
-Line 702 
 $ /some/path/to/bash ./testreport -ieee
+Line 741 
 $ /some/path/to/bash ./testreport -ieee
          <variablelist>
            <varlistentry>
-             <term><filename>-ieee</></term>
+             <term><filename>-ieee</> (default) / <filename>-noieee</></term>
              <listitem>
                <para>If allowed by the compiler (as defined in the "optfile"),
-                 use IEEE arithmetic.  This option, along with the GCC compiler,
+                 use IEEE arithmetic (<filename>genmake2 -ieee</>).
-                 is how the standard results were produced.</para>
+                 This option, along with the gfortran / gcc compiler,
+                 is how the standard results are produced.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-optfile=/PATH/FILENAME</></term>
+             <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
+             <listitem>
+               <para>This specifies a list of "options files" that will be passed
+                 to <filename>genmake2</>.  If multiple options files are used
+                 (say, to test different compilers or different sets of options
+                 for the same compiler), then each options file will be used with
+                 each of the test directories.</para>
              </listitem>
            </varlistentry>
-Line 717 
 $ /some/path/to/bash ./testreport -ieee
+Line 769 
 $ /some/path/to/bash ./testreport -ieee
                <para>This option specifies the test directory or list of test
                  directories that should be used.  Each of these entries should
                  exactly (note: they are case sensitive!) match the names of
-                 directries in <filename>$ROOTDIR/verification/</>.  If this
+                 directories in <filename>$ROOTDIR/verification/</>.  If this
                  option is omitted, then all directories that are properly
                  formatted (that is, containing an <filename>input</>
                  sub-directory and a <filename>results/output.txt</> file) will
-Line 726 
 $ /some/path/to/bash ./testreport -ieee
+Line 778 
 $ /some/path/to/bash ./testreport -ieee
            </varlistentry>
            <varlistentry>
-             <term><filename>-optfile=/PATH/FILENAME</></term>
-             <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
-             <listitem>
-               <para>This specifies a list of "options files" that will be passed
-                 to <filename>genmake2</>.  If multiple options files are used
-                 (say, to test different compilers or different sets of options
-                 for the same compiler), then each options file will be used with
-                 each of the test directories.</para>
-             </listitem>
-           </varlistentry>
-           <varlistentry>
              <term><filename>-addr EMAIL</></term>
              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
              <listitem>
-Line 751 
 $ /some/path/to/bash ./testreport -ieee
+Line 791 
 $ /some/path/to/bash ./testreport -ieee
            </varlistentry>
            <varlistentry>
+             <term><filename>-MPI NUMBER_OF_PROCS</></term>
              <term><filename>-mpi</></term>
              <listitem>
-               <para>If the necessary files
+               <para>If the necessary file (<filename>TESTDIR/code/SIZE.h_mpi</>)
-               (<filename>TESTDIR/code/CPP_EEOPTIONS.h_mpi</> and
+               exists, then use it (and all <filename>TESTDIR/code/*_mpi</> files)
-               <filename>TESTDIR/code/SIZE.h_mpi</>) exist, then use them for an
+               for an MPI--enabled run.  The new option (<filename>-MPI</> followed
-               MPI--enabled run.  Note that the use of MPI typically requires a
+               by the maximum number of processors) enable to build and run each
+               test-experiment using variable number of MPI processors (multiple
+               of <filename>nPx*nPy</> from <filename>TESTDIR/code/SIZE.h_mpi</>
+               and not larger than <filename>NUMBER_OF_PROCS</>).
+               The short option ("-mpi") can only be used to build and run on 2 MPI
+               processors (equivalent to "<filename>-MPI 2</>").</para>
+               <para>Note that the use of MPI typically requires a
                special command option (see "-command" below) to invoke the MPI
-               executable.  Examples of PBS scripts using MPI with testreport can be
+               executable.  Examples of PBS scripts using testreport with MPI can be
                found in the <ulink
-               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
+               url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
-               MITgcm-contrib area</ulink></para>
+               tools/example_scripts directory</ulink>.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>-command='some command to run'</></term>
              <listitem>
-               <para>For some tests, particularly MPI runs, the default "make
+               <para>For some tests, particularly MPI runs, a specific command
-               output.txt" is not sufficient.  This option allows a more general
+               might be needed to run the executable. This option allows a more general
                command (or shell script) to be invoked.  Examples of PBS scripts
-               using MPI with testreport can be found in the <ulink
+               using testreport with MPI can be found in the <ulink
-               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
+               url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
-               MITgcm-contrib area</ulink></para>
+               tools/example_scripts directory</ulink>.</para>
              </listitem>
            </varlistentry>
-Line 799 
 $ /some/path/to/bash ./testreport -ieee
+Line 846 
 $ /some/path/to/bash ./testreport -ieee
          the generic fluid dynamical engine.</para>
        <para>The MITgcmUV packaging structure is described below using generic
-         package names ${pkg}.  A concrete examples of a package is the code for
+         package names ${pkg}. A concrete examples of a package is the code for
          implementing GM/Redi mixing. This code uses the package name</para>
      </sect2>
-Line 859 
 o  Each package gets its runtime configu
+Line 906 
 o  Each package gets its runtime configu
     Package runtime config. options are imported
     into a common block held in a header file
     called "${PKG}.h".
+    Note: In some packages, the header file "${PKG}.h" is splitted
+    into "${PKG}_PARAMS.h" that contains the package parameters and
+    ${PKG}_VARS.h" for the field arrays.
  o  The core driver part of the model can check
     for runtime enabling or disabling of individual packages
-Line 881 
 CPP Flags
+Line 931 
 CPP Flags
 . Within the core driver code flags of the form
         ALLOW_${PKG} are used to include or exclude
         whole packages. The ALLOW_${PKG} flags are included
-        from a PKG_CPP_OPTIONS block which is currently
+        from a PACKAGES_CONFIG.h file that is automatically
+        generated by genmake2 (see genmake2 section).
         held in-line in the CPP_OPTIONS.h header file.
         e.g.
         Core model code .....
+        #include "PACKAGES_CONFIG.h"
         #include "CPP_OPTIONS.h"
           :
           :
-Line 898 
 CPP Flags
+Line 950 
 CPP Flags
 . Within an individual package a header file,
         "${PKG}_OPTIONS.h", is used to set CPP flags
-        specific to that package. It is not recommended
+        specific to that package. It also includes
-        to include this file in "CPP_OPTIONS.h".
+        "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
  Package Boot Sequence
-Line 921 
 Package Boot Sequence
+Line 973 
 Package Boot Sequence
       &       CALL ${PKG}_READPARMS( retCode )
          #endif
-. S/R PACKAGES_CHECK()
+. S/R PACKAGES_INIT_FIXED()
+             :
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_INIT_FIXED( retCode )
+         #endif
+. S/R PACKAGES_CHECK()
              :
          #ifdef ALLOW_${PKG}
            if ( use${Pkg} )
-Line 931 
 Package Boot Sequence
+Line 990 
 Package Boot Sequence
       &       CALL PACKAGES_CHECK_ERROR('${PKG}')
          #endif
-. S/R PACKAGES_INIT()
+. S/R PACKAGES_INIT_VARIABLES()
              :
          #ifdef ALLOW_${PKG}
            if ( use${Pkg} )
-      &       CALL ${PKG}_INIT( retCode )
+      &       CALL ${PKG}_INIT_VARIA( )
+         #endif
+ Package Output
+ ==============
+. S/R DO_THE_MODEL_IO
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_OUTPUT( )
          #endif
+. S/R PACKAGES_WRITE_PICKUP()
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_WRITE_PICKUP( )
+         #endif
  Description
  ===========
-Line 945 
 Description
+Line 1019 
 Description
        - ${PKG}_READPARMS()
      is responsible for reading
      in the package parameters file data.${pkg}, and storing
-     the package parameters in "${PKG}.h".
+     the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
-     -> called in INITIALISE_FIXED
+     -> called from INITIALISE_FIXED in PACKAGES_READPARMS
+      - ${PKG}_INIT_FIXED()
+     is responsible for completing the internal setup of a package.
+     -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
+     note: 1) some pkg use instead:
+              CALL ${PKG}_INITIALISE  ( or the old form CALL ${PKG}_INIT )
+) for simple pkg setup, this part is done inside ${PKG}_READPARMS
       - ${PKG}_CHECK()
      is responsible for validating
-Line 955 
 Description
+Line 1036 
 Description
      need to check. This is done through header files "${PKG}.h".
      It is assumed that parameters owned by other packages
      will not be reset during ${PKG}_CHECK().
-     -> called in INITIALISE_FIXED
+     -> called from INITIALISE_FIXED in PACKAGES_CHECK
-      - ${PKG}_INIT()
+      - ${PKG}_INIT_VARIA()
-     is responsible for completing the
+     is responsible for fill-in all package variables with an initial value.
-     internal setup of a package. This routine is called after
+     Contains eventually a call to ${PKG}_READ_PICKUP that will read
-     the core model state has been completely initialised
+     from a pickup file the package variables required to restart the model.
-     but before the core model timestepping starts.
+     This routine is called after the core model state has been completely
-     -> called in INITIALISE_VARIA
+     initialised but before the core model timestepping starts.
+     -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
+     note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
+      use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
+      form ${PKG}_INIT
+      - ${PKG}_OUTPUT( )
+      is responsible for writing time-average fields to output files
+      (but the cumulating step is done within the package main S/R).
+      Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
+      and write snap-shot fields that are hold in common blocks. Other
+      temporary fields are directly dump to file where they are available.
+      NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
+               but is beeing replaced by ${PKG}_OUTPUT
+               to avoid confusion with pkg/diagnostics functionality.
+) the output part is not yet in a standard form and might still
+               evolve a lot.
+     -> called within DO_THE_MODEL_IO
+      - ${PKG}_WRITE_PICKUP()
+      is responsible for writing a package pickup file when necessary for
+      a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
+     -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
  Summary
  =======
-Line 983 
 Summary
+Line 1086 
 Summary
    -----------------------
    * ${PKG}_OPTIONS.h     has further package-specific CPP options
    * ${PKG}.h             package-specific common block variables, fields
+    or  ${PKG}_PARAMS.h   package-specific common block parameters
+    and ${PKG}_VARS.h     package-specific common block fields
  - FORTRAN source files
    -----------------------
-   * ${pkg}_readparms.F   reads parameters from file data.${pkg}
+   * ${pkg}_readparms.F    reads parameters from file data.${pkg}
-   * ${pkg}_check.F       checks package dependencies and consistencies
+   * ${pkg}_init_fixed.F   complete the package setup
-   * ${pkg}_init.F        initialises package-related fields
+   * ${pkg}_check.F        checks package dependencies and consistencies
-   * ${pkg}_... .F        package source code
+   * ${pkg}_init_varia.F   initialises package-related fields
+   * ${pkg}_... .F         package source code
+   * ${pkg}_output.F       write output to file.
+   * ${pkg}_write_pickup.F write a package pickup file to restart the model
+   New: Subroutine in one package (pkgA) that only contains code which
+        is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
+        will be named: pkgA_pkgB_something.F
  - parameter file
    -----------------------
-Line 999 
 Summary
+Line 1111 
 Summary
    </sect1>
+   <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:NAME@mitgcm.org:/u/gcmpack'
+   $ mkdir scratch
+   $ cvs co -P 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 the Documentation</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 the Documentation</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>
  </article>

 Legend:



Removed from v.1.4
 


changed lines


 
Added in v.1.15
 Legend:



Removed from v.1.4
 


changed lines


 
Added in v.1.15
-Removed from v.1.4
+Added in v.1.15

	ViewVC Help
Powered by ViewVC 1.1.22