CVS Setup for the BYU Configurable Computing Lab

We now have a CVS (concurrent versions system) repository for the FPGA lab. This will give us source control for individual and group projects. It will, for example, merge changes that two people make to a single file as well as allow us to revert to any prior version of any file placed in CVS.

How to use CVS:

All of the UNIX machines in the lab have a CVS client program called, surprisingly enough, 'cvs'. People using other platforms can download a Java client, jcvs, from http://www.cyclic.com/jcvs/index.html. Most of the instructions I list below will use the syntax of the UNIX command-line version, but the equivalent commands in a graphical client should be fairly obvious.

Setup:

Anyone using CVS should point to the repository at /fpga3/cvsroot.

The easiest way to do this is to set the CVSROOT environment variable. Those who use csh/tcsh can add the following to their .cshrc file:

 setenv CVSROOT /fpga3/cvsroot

If you want to use CVS remotely, (ie. on a machine without direct access to /fpga3), you can use:

 setenv CVSROOT user@unix_machine:/fpga3/cvsroot

(Where 'user' is your username and 'unix_machine' is any unix machine with access to /fpga3 such as tick. This will only work if your .rhosts file on the unix machine allows you to connect from your machine)

Or, you can use the pserver mechanism. In the FPGA lab we currently have pserver running on itchy. You can use the following CVSROOT to access pserver on itchy:

 setenv CVSROOT :pserver:user@itchy.ee.byu.edu:/fpga3/cvsroot

NOTE: In order to use pserver, there is some adminstrative setup that needs to be done for each user. Pleas ask the local CVS guru to set you up to use pserver.

Adding a project to CVS:

The repository has the following directory structure:

$CVSROOT
   |----fpga
   |     |----sonar
   |     |----byucc
   |            |----jhdl
   |                  .
   |                  .
   |                  .
   |----users
         |
         |----ahlquist
         |----bellowsp
         |----brettw
         |----carl
         .
         .
         .
         |----snoop
         |----wheelert

So the repository is divided between lab-wide projects, (the fpga directory) and individual projects, (every user has a subdirectory under $CVSROOT/users)

If I had a project in ~carl/schematics that I wanted to add to the repository I would do the following. First I would go into that directory and clean out any files that I would not want in the repository. (This means any backup copies of files, object files, executables, Java .class files etc.). Then I could issue the following commands:

cd ~carl/schematics
cvs import -m "Initial import" users/carl/schematics fpga start

This would place every file from the directory ~carl/schematics as well as all subdirectories and files into the repository under $CVSROOT/users/carl/schematics. The -m flag gives a message that is added to log files, and the final two arguments to this command are the vendor_tag and release_tag. These two tags are not extremely important, but CVS does require them so it makes sense if we all use "fpga" and "start".

If all went well with the import I could now do the following:

cd ..
rm -rf schematics
cvs checkout carl/schematics

This would recreate a directory carl, a subdirectory schematics, and all of the files that were in that directory when I did the import (as well as any deeper subdirectories or files).

Using CVS after the import

As you may have noticed by now, all cvs commands are called with the following format:

cvs action arguments

The commonly used cvs commands are:

cvs checkout module

cvs co module (this is just a shortcut for checkout)

This will create a local copy of a project from the repository version. The module name should be a path relative to $CVSROOT or a module name defined in the $CVSROOT/CVSROOT/modules file.

cvs commit [-m log_message] module

This will merge any of the changes you have made locally into the repository. This makes changes available for other developers. The module name can be a single local directory name, or specific files. If it is left blank it will commit every modified file in the local directory. If you don't specify a log message with the -m switch, cvs will bring up your favorite editor (specified via $CVSEDITOR), so that you can type a message describing the changes you are committing.

cvs update module

This will merge any changes that are in the repository but not in local versions of files. This is done non-destructively, (ie it will not destroy un-committed changes that you have made to local files.) CVS requires an update before a commit can be performed.

cvs status module

This gives the current status of all files in the module specified. It will tell you whether a file is Up-To-Date, Locally Modified, or needing a Patch (that is an update), from the global repository.

cvs add file

This adds a new file to the repository that was not in the original import.

cvs remove file

This removes a file. (Of course, the file still exists in the repository so you can check out old versions -- it just will not be pulled out with a bare cvs checkout or update -- only if an old version is specifically requested).

cvs tag symbolic_tag module

This command place a symbolic revision tag on every file in the specified module. This is one of the most powerful features of cvs. The symbolic tag can be anything and previously tagged versions can be pulled out at later times. As a lab, we may want to standardize on some tagging conventions across all projects. (Perhaps version_1.0 or something like that)

CVS Resources on the web

There's a lot more to cvs than I can describe here. But this together with man pages, usage descriptions, and a slew of tutorials on the web should let you get started using CVS. Go ahead and try importing and checking out some files into your own section of the CVS repository. Feel free to talk to Carl if you have any questions.