Using the CVS repository for FMS

Version control is a necessary element in a large software project. It allows an institution to freeze stages in the development of code, in order to recreate prior states when required or desired, and to allow the easy coexistence of project components at varying levels of maturity. This document describes a version-controlled repository of the source code for FMS, the Flexible Modeling System.

1. Introduction to CVS

   CVS is the Concurrent Versions System, a set of tools for management of source codes with multiple users and developers distributed across a wide-area network. It is a central pillar of the open source community and is maintained by GNU. It is locally available at GFDL at /usr/local/bin/cvs.

   I don't propose a detailed write-up of CVS here, but point you to a CVS reference manual by Per Cederqvist et al, and to the CVS support page, that describes CVS at various levels of detail. There is also a newsgroup of the CVS community at gnu.cvs.help, where I've found people to be generous with their time and expertise. There is also a manpage (type man cvs).

   Useful features of CVS include:

   1. There is a single repository for a model code. Users make a private copy of the source tree (retaining the tree structure and date information as-is).

   2. Read ("checkout") and write ("commit") access to files can be precisely controlled by standard unix file permissions. Commit access can be further refined through scripts that can for instance: accept or reject code based on standards; inform users that a particular file has been updated; etc. This can all be done on a per-file basis or a per-module basis, where a module is the CVS term for a set of files that are grouped together for any reason.

   3. Users have control over when they acquire changes made to the repository, i.e you can continue to work with out-of-date code to continue a particular experiment if you wish, and update your code when you choose.

   4. A particular instantiation of a module can be identified by date or an author-supplied tag. (A tag is just a string used as an ID). This allows users very easily to recreate a particular prior state of the code long after the repository has been updated.

2. The FMS repository

   The FMS repository has been set up at /home/fms/cvs. A document describing the design of the FMS repository is available at /net/vb/tex/reports/cvs.ps.

   If this is the primary repository you will be using, you can make all cvs commands use it by setting the environment variable CVSROOT in your .cshrc:

   % setenv CVSROOT /home/fms/cvs
   

   External users need to use the client-server mechanism of cvs, called pserver:

   % setenv CVSROOT :pserver:cvs@cvs.gfdl.gov:/home/fms/cvs
   % cvs login
   

   This is password-protected, you will need to send mail to fms@gfdl.gov to get a password.

   You can override the value of CVSROOT with cvs -d if you want to use another repository. Subsequent discussion assumes that this variable has been set.

3. CVS commands

   1. Checking out (i.e acquiring) files from the repository.

      When you check files out of the repository, you get a private copy of the source tree. You will need to refer back to the repository only when you need to update your working copy with updates that were subsequently made to the repository.

      % mkdir -p ~/src # where your working copy sits.
      % cd ~/src
      % cvs checkout mpp
      % cd ~/src/mpp
      % ls -l
      

      Any user can point to the CVS repository and check out files. This will check out the latest version of the files in the mpp module into your directory ~/src/mpp. The dates on your checked out files will be the dates they were checked in (so you can use Makefiles, etc).

   2. Check repository for updates.

      % cvs status mpp
      

      If you've been working in the directory ~/src/mpp and want to know if I've modified the repository, you use the cvs status command. You can then decide if you actually want to update any files, and issue cvs update on those.

      The output of cvs status is rather verbose, so be sure to pipe it to your pager (e.g more).

   3. Compare files against repository.

      % cvs diff mpp
      

   4. Update working files.

      % cvs update mpp
      

      This updates your working directory with any updates to the repository. If there are files that have been changed in the repository, as well as by you to your working copy, cvs will automatically attempt to merge the changes. If unable to merge, it will report a conflict, and create a merged file with highlighted conflicts for you to edit. Your working copy is preserved with the string '.#' prepended to the name.

      By default cvs update updates from the latest versions in the repository. Other files in the repository may be identified by tag information, or by date, or by revision number (all retrievable by cvs status). To retrieve a non-default version with the tag tag, use:

      % cvs update -r tag mpp
      

      See the documentation for more details, for checkout by date, etc. Your original checkout could also have been controlled the same way.

   5. Return your changes to CVS-controlled files to the repository. Any subsequent changes to the checked out files can be checked in to the repository as follows:

      % emacs mpp.F90 #and hack away
      % cvs commit mpp.F90
      

      This will check in a new version of mpp.F90 into the repository. You will be prompted for information to be placed in the version log. If you do not have write access to the repository $CVSROOT/mpp the commit will fail.

      The current FMS policy calls for write access to be restricted to user fms. When you are ready to commit changes, fms will temporarily assign you write permission to certain relevant directories, and revoke the permissions when you are done.

   6. Committing new files to the repository. The FMS file creation policies, and the directory structure of FMS, are explained in the CVS policy document. You must first ask user fms to create the appropriate (empty) directory tree for you, and set you up with write permissions.

      # these can only be executed by fms
      % mkdir -p FMS/shared/mpp
      % chmod 775 FMS/shared/mpp
      

      Checkout the new directory.

      % cvs checkout FMS/shared/mpp
      

      This will create an empty directory for you under CVS control.

      Copy your source into this directory, and then inform CVS of your additions.

      % cd FMS/shared/mpp
      % cp /net/vb/src/mpp/mpp*.F90 .
      % cvs add *.F90
      

      Finally, commit your source back to the repository following the normal commit instructions.

4. CVS modules

   CVS modules (not be confused with f90 modules) are a convenient way of creating sets of source that are to be used together. Modules have been set up for each component of FMS, as well as for experiments. An experiment is a source module that can be used to run a particular FMS configuration, either a solo component model, or a particular ensemble of component models coupled. For example:

   % cvs checkout fms_spectral_amip
   

   will checkout an experiment coupling a spectral atmosphere to AMIP datasets for ocean, ice and land. A list of the available modules can be obtained by:

   % cvs checkout -c
   

5. Compiling FMS

   When a module is checked out, you will see a message near the end:

   A list of the files you checked out is in the file path_names ...
   

   (External users using the pserver mechanism will not get the path_names file, since CVS does not permit the server to run scripts on the client. They will need to checkout bin/list_paths from $CVSROOT and run it themselves in the current working directory).

   The file path_names contains a list of the source files that have been checked out. A Makefile to compile this FMS configuration can be created using mkmf, a script for analyzing source file dependencies, particularly for f90, simply by typing:

   % mkmf path_names
   

   You will probably need to set some additional mkmf flags, though.

   The file path_names can also be useful if you want to perform other actions (e.g grep) on the source.

   The Makefile generated by mkmf can also be used to create "tags" files that allow you easily to navigate the source tree. (These editing tags are not to be confused with CVS tags).

   % make TAGS
   % make tags
   

   The first form produces a file TAGS (used by emacs) and the second form produces a file tags (used by vi). Please consult your editor's documentation for instructions on the use of editing tags.

6. FMS documentation

   Full FMS documentation is available from the FMS home page. Documentation is also stored in the FMS repository and will be checked out along with the source. If lines similar to the following appear at the end of a checkout:

   Documentation on the files you checked out is accessible on the web at
   file://localhost/tmp/FMS/path_names.html ...
   

   you can use this URL in your browser to get links to the documentation specific to your experiment.