/[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.6 by jmc,
Tue Dec 23 22:42:20 2003 UTC
+revision 1.10 by jmc,
Thu Jan 21 23:59:17 2010 UTC
 Line 22
            Initial version.
          </revremark>
        </revision>
+       <revision>
+         <revnumber>0.02</revnumber>
+         <date>2010-01-21</date>
+         <authorinitials>jmc</authorinitials>
+         <revremark>
+           update links.
+         </revremark>
+       </revision>
      </revhistory>
      <abstract>
-Line 37
+Line 45
      <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 56
+Line 64
        <title>User Manual</title>
        <para>Before jumping into development, please familiarize yourself with
-         the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual
+         the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
          </ulink>.  This document contains volumes of useful information and is
          included here by reference.</para>
-Line 130
+Line 138
     e|- tools
     ?|  tutorial_examples        documented tests
      |                             only populated on release1 branch
-     |                             and not validated during "testscript"
+     |                             and not validated during "testreport"
      '- utils
         verification             std tests
-Line 182
+Line 190
        <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/doc/tag-index?view=graph">
-       tree</ulink>, the MITgcm codebase is split into to two branches
+       ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two
-       or "lines" under which development proceeds.  These two lines
+       branches or "lines" under which development proceeds.  These two lines are
-       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
-       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
-       composed of files from the same codebase.
+       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
+       relese 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 and ecco lines.</para>
-       allowed to continue along the MAIN and ecco lines.</para>
      </sect2>
      <sect2>
        <title>Tagging</title>
-       <para>The intent of tagging is to create "known-good"
+       <para>The intent of tagging is to create "known-good" checkpoints that
-       checkpoints that developers can use as references.
+       developers can use as references.  Traditionally, MITgcm tagging has
-       Traditionally, MITgcm tagging has maintained the following
+       maintained the following conventions:</para>
-       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 233
+Line 238
            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 271 
 o fix small problem with in ptracers_wri
+Line 276 
 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>
-Line 287 
 checkpoint50d_pre
+Line 291 
 checkpoint50d_pre
      <sect2 id="documentation_getting">
        <title>Getting the Docs and Code</title>
-       <para>The first step towards editing the documentation is to
+       <para>The first step towards editing the documentation is to checkout a
-       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>
  <screen>
    $ export CVS_RSH=ssh
-   $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'
+   $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
    $ mkdir scratch
-   $ cvs co MITgcm manual mitgcm.org
+   $ cvs co -P MITgcm manual mitgcm.org
  </screen>
-       <para>These commands extract the necessary information from the
+       <para>These commands extract the necessary information from the CVS server
-       CVS server and create a temporary (called
+       and create a temporary (called <filename>scratch</filename>) directory for
-       <filename>scratch</filename>) directory for the storage of the
+       the storage of the HTML and other files that will be created.  Please note
-       HTML and other files that will be created.  Please note that you
+       that you must either create <filename>scratch</filename> as shown or edit
-       must either create <filename>scratch</filename> as shown or edit
+       the various <filename>Makefile</filename>s and scripts used to create the
-       the various <filename>Makefile</filename>s and scripts used to
+       documentation.</para>
-       create the documentation.</para>
      </sect2>
      <sect2>
        <title>Editing the Documentation</title>
-       <para>The documentation is contained in the
+       <para>The documentation is contained in the <filename>manual</filename>
-       <filename>manual</filename> directory in a raw LaTeX format.
+       directory in a raw LaTeX format.  The main document is
-       The main document is <filename>manual.tex</filename> and it uses
+       <filename>manual.tex</filename> and it uses <command>\input{}</command>s
-       <command>\input{}</command>s to include the chapters and
+       to include the chapters and subsections.</para>
-       subsections.</para>
+       <para>Since the same LaTeX source is used to produce PostScript, PDF, and
-       <para>Since the same LaTeX source is used to produce PostScript,
+       HTML output, care should be taken to follow certain conventions.  Two of
-       PDF, and HTML output, care should be taken to follow certain
+       the most important are the usage of the <command>\filelink{}{}</command>
-       conventions.  Two of the most important are the usage of the
+       and <command>\varlink{}{}</command> commands.  Both of these commands have
-       <command>\filelink{}{}</command> and
+       been defined to simplify the connection between the automatically
-       <command>\varlink{}{}</command> commands.  Both of these
+       generated ("code browser") HTML and the HTML version of the manual
-       commands have been defined to simplify the connection between
+       produced by LaTeX2HTML.  They each take two arguments (corresponding to
-       the automatically generated ("code browser") HTML and the HTML
+       the contents of the two sets of curly braces) which are the text that the
-       version of the manual produced by LaTeX2HTML.  They each take
+       author wishes to be "wrapped" within the link, and a specially formatted
-       two arguments (corresponding to the contents of the two sets of
+       link thats relative to the <filename>MITgcm</filename> directory within
-       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>
        <para>The result is a command that resembles either</para>
-Line 367 
 checkpoint50d_pre
+Line 366 
 checkpoint50d_pre
    $ make All
  </screen>
-       <para>Which builds the PDF from the LaTeX source, creates the
+       <para>Which builds the PDF from the LaTeX source, creates the HTML output
-       HTML output from the LaTeX source, parses the FORTRAN code base
+       from the LaTeX source, parses the FORTRAN code base to produce a
-       to produce a hyperlinked HTML version of the source, and then
+       hyperlinked HTML version of the source, and then determines the
-       determines the cross-linking between the various HTML
+       cross-linking between the various HTML components.</para>
-       components.</para>
+       <para>If there are no errors, the result of the build process (which can
-       <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
-       (which can take 30+ minutes on a P4/2.5Ghz) will be contained
+       directory called <filename>scratch/dev_docs</filename>.  This is a freshly
-       within a single directory called
+       built version of the entire on-line users manual.  If you have the correct
-       <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>
  <screen>
    $ mv scratch/dev_docs /u/u0/httpd/html
-Line 799 
 checkpoint50d_pre
+Line 795 
 checkpoint50d_pre
                special command option (see "-command" below) to invoke the MPI
                executable.  Examples of PBS scripts using MPI with testreport 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_contrib/test_scripts/">
                MITgcm-contrib area</ulink></para>
              </listitem>
            </varlistentry>
-Line 811 
 checkpoint50d_pre
+Line 807 
 checkpoint50d_pre
                output.txt" is not sufficient.  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
-               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
+               url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
                MITgcm-contrib area</ulink></para>
              </listitem>
            </varlistentry>
-Line 898 
 o  Each package gets its runtime configu
+Line 894 
 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 920 
 CPP Flags
+Line 919 
 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 937 
 CPP Flags
+Line 938 
 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 990 
 Package Output
+Line 991 
 Package Output
          #ifdef ALLOW_${PKG}
            if ( use${Pkg} )
-      &       CALL ${PKG}_DIAGS( )
+      &       CALL ${PKG}_OUTPUT( )
          #endif
 . S/R PACKAGES_WRITE_PICKUP()
-Line 1006 
 Description
+Line 1007 
 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 from INITIALISE_FIXED in PACKAGES_READPARMS
       - ${PKG}_INIT_FIXED()
-Line 1036 
 Description
+Line 1037 
 Description
       use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
       form ${PKG}_INIT
-      - ${PKG}_DIAGS()
+      - ${PKG}_OUTPUT( )
-      is responsible for writing time-average diagnostics to output
+      is responsible for writing time-average fields to output files
-      files (but the cumulating step is done within the package main S/R).
+      (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: this part does not yet have a standard form and should be called
+      NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
-        from a package dedicated S/R such as PACKAGE_WRITE_DIAGS
+               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()
-Line 1070 
 Summary
+Line 1074 
 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
    -----------------------
-Line 1078 
 Summary
+Line 1084 
 Summary
    * ${pkg}_check.F        checks package dependencies and consistencies
    * ${pkg}_init_varia.F   initialises package-related fields
    * ${pkg}_... .F         package source code
-   * ${pkg}_diags.F        write diagnostics to file.
+   * ${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
    -----------------------
    * data.${pkg}          parameter file

 Legend:



Removed from v.1.6
 


changed lines


 
Added in v.1.10
 Legend:



Removed from v.1.6
 


changed lines


 
Added in v.1.10
-Removed from v.1.6
+Added in v.1.10

	ViewVC Help
Powered by ViewVC 1.1.22