Obtaining the MITgcm Source using CVS
Using CVS "pserver" for Anonymous Access
The most convenient way to get local copies of the MITgcm source code is
to use the CVS "pserver" mechanism. This method only allows you to "check
out" (or obtain a local copy) of the source. It does not provide a
mechanism for "committing" or "checking in" changes (please see below).
Using CVS pserver from the command line requires just a three commands.
Using a Bourne, "bash", or "sh-compatible" shell they are:
$ export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
$ cvs login
( enter the CVS password: "cvsanon" )
$ cvs co -P MITgcm
Using a "C", "csh", or "tcsh" shell the commands are:
$ setenv CVSROOT ':pserver:cvsanon@mitgcm.org:/u/gcmpack'
$ cvs login
( enter the CVS password: "cvsanon" )
$ cvs co -P MITgcm
using the "-P" option to check-out ("cvs co -P") prevents
to download unnecessary empty directories.
A large amount of additional (optional!) content is available
from the MITgcm_contrib directory; much of it is specific to certain
setups (eg. high-res setups, in-development material that is not yet part
of the "main" code, etc ...).
But rather than checking out the full content of MITgcm_contrib
("cvs co -P MITgcm_contrib"), which takes a long time to download
(particularly from remote locations), we recommend to download only the
specific part of interest, e.g.: "submesoscale" directory,
which can be checked out using:
$ cvs co -P MITgcm_contrib/submesoscale
Note that you will only need to perform the "cvs login" once. And for
convenience, you may want to add the CVSROOT variable to your shell's
environment (that is, define it within your "~/.bashrc" or "~/.chsrc"
files).
Also note that it is possible to checkout code without "cvs login" and
without setting any shell environment variables by specifying the
pserver name and password in one line, for example:
$ cvs -d :pserver:cvsanon:cvsanon@mitgcm.org:/u/gcmpack co -P MITgcm
Getting Parts of the Source "Tree"
The above commands demonstrate how to check out all of the MITgcm code
and the "contributed" (that is, unsupported but occasionally useful)
information within the "MITgcm_contrib" directory. In many cases,
this is overkill and can result in long download times.
To reduce the volume of information downloaded and thereby speedup the
download times, one can select one of the following pre-defined "aliases"
that will provide a sub-set of the entire MITgcm source "tree":
Alias Name |
Information (directories) Contained |
MITgcm_code |
Only the source code -- none of the verification examples. |
MITgcm_verif_basic |
Source code plus a small set of the verification examples
("aim.5l_cs", "hs94.128x64x5", "ideal_2D_oce", "lab_sea",
"tutorial_baroclinic_gyre", "tutorial_global_oce_latlon"
and "tutorial_plume_on_slope"). |
MITgcm_tutorials |
Source code plus all of the tutorials examples. |
MITgcm_verif_all |
Source code plus all of the verification examples. |
It is important to note that the CVS aliases above cannot be used in
conjunction with the CVS -d DIRNAME option. However, the MITgcm
directories they create can be changed to a different name following the
check-out:
$ cvs co -P MITgcm_verif_basic
$ mv MITgcm MITgcm_verif_basic
Getting Specific Releases or "Checkpoints"
As shown within the
CVS Code Browser
, the MITgcm code is continuously undergoing updates. At
points during the development (typically, after work has been done and the
source code has passed the verification
tests), a release or checkpoint "tag" is created. These tags are a
convenient mechanism for referring to different times or points within the
development. One can check out these versions using the "-r TAG_NAME" CVS
option such as:
$ cvs co -P -r release1_p5 MITgcm
$ cvs co -P -r checkpoint52a_post MITgcm
By default (that is, when no tag is specified), CVS will retrieve the
latest version of all files. To download an older version corresponding
to a specific time, e.g., May 1rst, 2008, at 5pm, one can use the "-D"
CVS option as follows:
$ cvs co -P -D "2008-05-01 17:00" MITgcm
Show changes that YOU have made
If you are running into difficulties it is very useful to see the changes
that you yourself have made since obtaining the code. From within
your working directory:
cvs diff
will show the differences between your version and the version that you
checked out. It acts recursively on all directories below your current
directory. You can limit the operation to just one file or directory by
specifying those as arguments:
cvs diff file
Show changes to the repository that you don't have
The source code evolves continuously and you should try to stay up to
date. To see what needs to be updated:
cvs -n update
behaves just as "cvs update" but doesn't actually change anything. This
is a useful way of summarizing the state of your code. The meaning of the
output is summarized in the next topic.
Getting updates from the repository
You can download and merge updates from the repository to bring you
working code up to date:
cvs update -d -P
will work recursively on all files in the current directory and below.
To update just a specific file or directory:
cvs update file
You can also update to a specific version, just as you could check out
a specific version.
cvs update -d -P -r release1_p5
If you checked out a specific version and want to update to the very
latest use the -A option will remove associated with a specific version as
follows:
cvs update -d -P -A
"cvs update" produces output to the terminal with the following
meanings:
Return Code |
Description |
U file |
indicates that file was brought up to date with the
repository or that it exists in the repository but not in your work
space |
P file |
does exactly as above but uses the "patch" method |
M file |
means the file was modified in your work space. Any
additional changes from the repository were merged in
successfully |
C file |
means a merge is necessary because both the your copy and the
repository have changed but there is a conflict between the
changes |
? file |
means the file exists in your work space but not on the
repository |
When conflicts arise, the sections of code are both kept and surrounded
by <<<<<, ===== and >>>>> indicators. You need to examine
these lines of the files and resolve the conflict.
Wow! CVS is so good, where can I learn more?
The basic
manual is a good reference.
For those who prefer the good old fashioned book there's
"Open Source Development With CVS".
|