--- MITgcm/doc/devel_HOWTO.sgml 2003/12/23 22:42:20 1.6
+++ MITgcm/doc/devel_HOWTO.sgml 2010/01/21 23:59:17 1.10
@@ -22,6 +22,14 @@
Initial version.
+
+ 0.02
+ 2010-01-21
+ jmc
+
+ update links.
+
+
@@ -37,7 +45,7 @@
New Versions of This Document You can
obtain the latest version of this document online in
+ url="http://mitgcm.org/public/docs.html">online in
various formats.
@@ -56,7 +64,7 @@
User Manual
Before jumping into development, please familiarize yourself with
- the MITgcm user manual
+ the MITgcm user manual
. This document contains volumes of useful information and is
included here by reference.
@@ -130,7 +138,7 @@
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
@@ -182,48 +190,45 @@
Branches
As shown in the online ViewCVS-generated
- tree, the MITgcm codebase is split into to two branches
- or "lines" under which development proceeds. These two lines
- are referred to as the "MAIN" and "ecco" versions of the code.
- While not identical, the bulk of the MAIN and ecco lines are
- composed of files from the same codebase.
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index?view=graph">
+ ViewCVS-generated tree, the MITgcm codebase is split into to two
+ branches or "lines" under which development proceeds. These two lines are
+ referred to as the "MAIN" and "ecco" versions of the code. While not
+ identical, the bulk of the MAIN and ecco lines are composed of files from
+ the same codebase.
Periodically, a "Release" branch is formed from the "MAIN"
- development branch. This is done in order to create a
- relatively stable reference point for both users and developers.
- The intent is that once a relese branch has been created, only
- bug-fixes will be added to it. Meanwhile, development (which
- might "break" or otherwise render invalid the documentation,
- tutorials, and/or examples contained within a release branch) is
- allowed to continue along the MAIN and ecco lines.
+ development branch. This is done in order to create a relatively stable
+ reference point for both users and developers. The intent is that once a
+ relese branch has been created, only bug-fixes will be added to it.
+ Meanwhile, development (which might "break" or otherwise render invalid
+ the documentation, tutorials, and/or examples contained within a release
+ branch) is allowed to continue along the MAIN and ecco lines.
Tagging
- The intent of tagging is to create "known-good"
- checkpoints that developers can use as references.
- Traditionally, MITgcm tagging has maintained the following
- conventions:
+ The intent of tagging is to create "known-good" checkpoints that
+ developers can use as references. Traditionally, MITgcm tagging has
+ maintained the following conventions:
- Developer checks out code into a local CVS-managed
- directory, makes various changes/additions, tests these
- edits, and eventually reaches a point where (s)he is
- satisfied that the changes form a new "useful" point in the
- evolution of the code.
+ Developer checks out code into a local CVS-managed directory,
+ makes various changes/additions, tests these edits, and eventually
+ reaches a point where (s)he is satisfied that the changes form a new
+ "useful" point in the evolution of the code.
The developer then runs the testscript
- shell script to see if any problems are introduced. While
- not intended to be exhaustive, the test cases within the
- verification directory do provide some indication whether
- gross errors have been introduced.
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
+ testreport shell script to see if any problems are introduced.
+ While not intended to be exhaustive, the test cases within the
+ verification directory do provide some indication whether gross errors
+ have been introduced.
@@ -233,23 +238,23 @@
then:
- adds a "checkpointXY_pre" comment (where X is a
- checkpoint number and Y is a letter) to the tag-index
- file and checks it into the CVS repository
+ adds a "checkpointXY_pre" comment (where X is a checkpoint
+ number and Y is a letter) to the
+ tag-index file and checks it into the CVS
+ repository
- submits the set of changes to the CVS repository
- and adds comments to tag-index
- describing what the changes are along with a matching
- "checkpointXY_post" entry
+ submits the set of changes to the CVS repository and adds
+ comments to tag-index describing what the
+ changes are along with a matching "checkpointXY_post" entry
- The result of this tagging procedure is a sequence of
- development checkpoints with comments which resembles:
+ The result of this tagging procedure is a sequence of development
+ checkpoints with comments which resembles:
checkpoint50e_post
@@ -271,11 +276,10 @@
checkpoint50d_pre
- This information can be used to refer to various stages of
- the code development. For example, bugs can be traced to
- individual sets of CVS checkins based upon their first
- appearance when comparing the results from different
- checkpoints.
+ This information can be used to refer to various stages of the code
+ development. For example, bugs can be traced to individual sets of CVS
+ checkins based upon their first appearance when comparing the results from
+ different checkpoints.
@@ -287,48 +291,43 @@
Getting the Docs and Code
- The first step towards editing the documentation is to
- checkout a copy of code, docs, and build scripts from the CVS
- server using:
+ The first step towards editing the documentation is to checkout a
+ copy of code, docs, and build scripts from the CVS server using:
$ 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
- These commands extract the necessary information from the
- CVS server and create a temporary (called
- scratch) directory for the storage of the
- HTML and other files that will be created. Please note that you
- must either create scratch as shown or edit
- the various Makefiles and scripts used to
- create the documentation.
+ These commands extract the necessary information from the CVS server
+ and create a temporary (called scratch) directory for
+ the storage of the HTML and other files that will be created. Please note
+ that you must either create scratch as shown or edit
+ the various Makefiles and scripts used to create the
+ documentation.
Editing the Documentation
- The documentation is contained in the
- manual directory in a raw LaTeX format.
- The main document is manual.tex and it uses
- \input{}s to include the chapters and
- subsections.
-
- 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
- \filelink{}{} and
- \varlink{}{} 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 MITgcm directory within the
- CVS tree.
+ The documentation is contained in the manual
+ directory in a raw LaTeX format. The main document is
+ manual.tex and it uses \input{}s
+ to include the chapters and subsections.
+
+ 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 \filelink{}{}
+ and \varlink{}{} 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 MITgcm directory within
+ the CVS tree.
The result is a command that resembles either
@@ -367,19 +366,16 @@
$ make All
- 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.
-
- 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
- scratch/dev_docs. 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:
+ 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.
+
+ 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 scratch/dev_docs. 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:
$ mv scratch/dev_docs /u/u0/httpd/html
@@ -799,7 +795,7 @@
special command option (see "-command" below) to invoke the MPI
executable. Examples of PBS scripts using MPI with testreport can be
found in the
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
MITgcm-contrib area
@@ -811,7 +807,7 @@
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
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
MITgcm-contrib area
@@ -898,6 +894,9 @@
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
@@ -920,12 +919,14 @@
1. 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"
:
:
@@ -937,8 +938,8 @@
2. Within an individual package a header file,
"${PKG}_OPTIONS.h", is used to set CPP flags
- specific to that package. It is not recommended
- to include this file in "CPP_OPTIONS.h".
+ specific to that package. It also includes
+ "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
Package Boot Sequence
@@ -990,7 +991,7 @@
#ifdef ALLOW_${PKG}
if ( use${Pkg} )
- & CALL ${PKG}_DIAGS( )
+ & CALL ${PKG}_OUTPUT( )
#endif
7. S/R PACKAGES_WRITE_PICKUP()
@@ -1006,7 +1007,7 @@
- ${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()
@@ -1036,14 +1037,17 @@
use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
form ${PKG}_INIT
- - ${PKG}_DIAGS()
- is responsible for writing time-average diagnostics to output
- files (but the cumulating step is done within the package main S/R).
+ - ${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: this part does not yet have a standard form and should be called
- from a package dedicated S/R such as PACKAGE_WRITE_DIAGS
+ 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.
+ 2) 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()
@@ -1070,6 +1074,8 @@
-----------------------
* ${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
-----------------------
@@ -1078,9 +1084,13 @@
* ${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