--- MITgcm/doc/devel_HOWTO.sgml 2006/05/09 21:10:19 1.9
+++ MITgcm/doc/devel_HOWTO.sgml 2010/04/25 20:04:45 1.11
@@ -22,6 +22,22 @@
Initial version.
+
+ 0.02
+ 2010-01-21
+ jmc
+
+ update links.
+
+
+
+ 0.03
+ 2010-04-25
+ jmc
+
+ Add subsection "Developer settings" (under CVS Repository).
+
+
@@ -37,7 +53,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 +72,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.
@@ -94,6 +110,7 @@
CVS Repository
+
Layout
@@ -104,46 +121,48 @@
others. The tree currently resembles:
gcmpack/
- MITgcm-contrib contributed code
CS-regrid goes into utils
- cvspolicy.html -save-
- CVSROOT -save-
- development experimental stuff
- manual -save-
- misc -?-
+ CVSROOT -hidden-
MITgcm code
- adjoint fold into genmake
- bin stub for ecco build
- compare01 old from 20th century
- diags timeave f77 in pkgs now
- doc tags -- connect to real docs?
- eesupp cnh?
- exe ecco user build
- ,- jobs runtime shell scripts for
- | various platforms
- | lsopt line search
- m| model main dynamics (core)
- e| optimization_drivers ?
- r| optim line search interface
- g| pkg alternate and optional numerics, etc.
- e|- tools
- ?| tutorial_examples documented tests
- | only populated on release1 branch
- | and not validated during "testscript"
- '- utils
- verification std tests
+ bin empty
+ doc basic developpment documentation
+ eesupp execution environment support code (wrapper)
+ exe empty
+ jobs runtime shell scripts for
+ various platforms (not maintained)
+ lsopt line search
+ model main dynamics (core)
+ optim line search interface
+ pkg alternate and optional numerics, etc.
+ tools scripts to build (and test)
+ utils pre/post processing tools (matlab, ..)
+ verification standard regression tests + examples
+ + documented examples (tutorials)
+ tutorial_examples (only in release1 branch)
+ MITgcm_contrib contributed code
- mitgcmdoc -> manual -remove-
+ acesgrid.org build acesgrid web site
+ development experimental stuff
+ gcmpack an old back-up copy ?
+ gfd_lab -?-
+ manual -save-
+ misc -?-
mitgcm.org build web site
+ mitgcmdoc -> manual -remove-
models -?-
packages -?-
+ pdfs some pdfs
+ planetinabottle.org unfinished web site
preprocess -?-
tmp -?-
+ www.ecco-group.org build ecco web site ?
+
@@ -182,7 +201,7 @@
Branches
As shown in the online
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?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
@@ -200,7 +219,92 @@
- Tagging
+ Developer settings
+
+ CVS is a convenient tool to keep up-to-date a personal copy of the
+ MITgcm code (see:
+ using CVS ). 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:
+
+
+ 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 ssh MY_USER_NAME@mitgcm.org
+ in case of different user-name on both sides) to proceed further.
+
+
+
+ You need to register to the
+
+ mitgcm-cvs 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.
+
+
+
+
+ It is highly recommended that you register also to the
+
+ mitgcm-devel mailing list (expect a short delay for
+ this request to be processed).
+ This list is intended for developer discussions.
+
+
+
+
+ The standard anonymous mode (using "cvsanon", as mentionned
+
+ here ) does not allow check-in ("cvs commit") permission.
+ Instead, you will need to set our CVS environment as follow:
+
+ $ export CVS_RSH=ssh
+ $ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
+
+ After downloading a directory, e.g.: myCopy,
+ from the CVS repository (e.g.,
+ MITgcm_contrib/thisPart) using the command:
+
+ $ cvs co -P -d myCopy MITgcm_contrib/thisPart
+
+ the type of CVS environment which has been used
+ is stored in the file myCopy/CVS/Root
+ and makes it difficult to re-use, for cvs-commit purpose,
+ a cvs local copy (myCopy) which was obtained
+ using the CVS anonymous mode.
+
+
+
+ At this stage, you should be able to send your modified source
+ file (e.g., src_file) from your local copy directory
+ (myCopy) to the CVS repository
+ (MITgcm_contrib/thisPart) using the command
+ "cvs commit":
+
+ $ 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
+
+ It is essential that you provide a short description of the
+ changes you made to src_file as you check-in
+ this file (the "cvs commit" command automatically opens your standard
+ editor for this purpose).
+
+
+
+
+
+
+
+ Main code development
+ (formerly named "Tagging" ; this section needs an update)
The intent of tagging is to create "known-good" checkpoints that
developers can use as references. Traditionally, MITgcm tagging has
@@ -216,8 +320,8 @@
The developer then runs the
- testscript shell script to see if any problems are 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.
@@ -232,7 +336,7 @@
adds a "checkpointXY_pre" comment (where X is a checkpoint
number and Y is a letter) to the
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">
tag-index file and checks it into the CVS
repository
@@ -277,108 +381,6 @@
-
- Editing the Documentation
-
-
- 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:
-
-
- $ export CVS_RSH=ssh
- $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
- $ mkdir scratch
- $ 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.
-
-
-
- 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 result is a command that resembles either
-
-
-
- a reference to a variable or subroutine name such as
- \varlink{tRef}{tRef}, or
-
-
-
- a reference to a file such as
- \varlink{tRef}{path-to-the-file_name.F}
- where the absolute path to the file is of the form
- /foo/MITgcm/path/to/the/file_name.F
- (please note how the leading "/foo/MITgcm"
- component of the path is dropped leaving the path
- relative to the head of the code
- directory and each directory separator "/" is turned
- into a "-")
-
-
-
-
-
-
-
-
- Building the Documentation
-
- Given the directory structure of , the entire documentation for the web
- site can be built using:
-
-
- $ cd mitgcm.org/devel/buildweb
- $ 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:
-
-
- $ mv scratch/dev_docs /u/u0/httpd/html
-
-
- and the update is complete.
-
-
-
-
-
Coding for MITgcm
@@ -787,7 +789,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
@@ -799,7 +801,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
@@ -826,7 +828,7 @@
the generic fluid dynamical engine.
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
@@ -1091,6 +1093,108 @@
+
+ Editing the Documentation
+
+
+ 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:
+
+
+ $ export CVS_RSH=ssh
+ $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
+ $ mkdir scratch
+ $ 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.
+
+
+
+ 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 result is a command that resembles either
+
+
+
+ a reference to a variable or subroutine name such as
+ \varlink{tRef}{tRef}, or
+
+
+
+ a reference to a file such as
+ \varlink{tRef}{path-to-the-file_name.F}
+ where the absolute path to the file is of the form
+ /foo/MITgcm/path/to/the/file_name.F
+ (please note how the leading "/foo/MITgcm"
+ component of the path is dropped leaving the path
+ relative to the head of the code
+ directory and each directory separator "/" is turned
+ into a "-")
+
+
+
+
+
+
+
+
+ Building the Documentation
+
+ Given the directory structure of , the entire documentation for the web
+ site can be built using:
+
+
+ $ cd mitgcm.org/devel/buildweb
+ $ 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:
+
+
+ $ mv scratch/dev_docs /u/u0/httpd/html
+
+
+ and the update is complete.
+
+
+
+
+