Unlike many open source projects, the MITgcm CVS tree does not follow a simple "src", "docs", "share", and "test" directory layout. Instead, there are multiple higher-level directories that each, to some extent, depend upon the presence of the others. The tree currently resembles:
gcmpack/
CVSROOT -hidden-
MITgcm code
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
acesgrid.org build acesgrid web site
development experimental stuff
gfd_lab -?-
manual source of MITgcm documentation
mitgcm.org build web site
old_develop old and early development source
misc -?-
models -?-
packages -?-
preprocess -?-
pdfs some pdfs
planetinabottle.org unfinished web site
www.ecco-group.org build ecco web site ?As shown in the online ViewCVS-generated tree, the MITgcm codebase is split into branches or "lines" under which development proceeds. The main line of development is referred to as the "MAIN" version of the code.
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 release 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 line.
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 (login access) to the server "mitgcm.org" (curently: mitgcmcvs.mit.edu) 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 (we recommend to ask your senior MITgcm-collaborator to send such request to marshall-admin at techsquare.com with Cc to Chris Hill for approval).
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 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 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 CVS-anonymous mode (using "cvsanon", as mentionned here ) does not provide 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'
The reason for such limitation is that when 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. This prevent 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).
Note: Please ignore the following warnings that the "cvs commit" command produces if you are not part of the "gcmpack" group:
cvs commit: failed to create lock directory for `/u/gcmpack/CVSROOT' (/u/gcmpack/CVSROOT/#cvs.history.lock): Permission denied cvs commit: failed to obtain history lock in repository `/u/gcmpack'These warnings are not affecting the changes you made to the CVS repository.
(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 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.
The developer then runs the 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.
Having satisfied him- or herself that the changes are ready to be committed to the CVS repository, the developer 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
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:
checkpoint50e_post o make KPP work with PTRACERS - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is nearly a copy of kpp_transport_s - there is no analogue to SurfaceTendencyS, so I have to use gPtr(of the surface layer) instead o add a new platform SunFire+mpi (SunFire 15000) to genmake checkpoint50e_pre checkpoint50d_post o change kpp output from multiple-record state files to single-record state files analogous to write_state.F o reduce the output frequency of cg3d-related stuff to the monitor frequency, analogous to the cg2d-related output. o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512, so that writing to internal file fn (with length 512) fails. 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.