Stanford Digital Library Testbed: CVS instructions

Stanford Digital Library Testbed Development

Department of Computer Science
Stanford University
Stanford, CA

CVS Version Management

We are using CVS to manage our testbed software development. Manuals and papers are available below. This page gives you the basics you need to get a copy of the source tree, add new code, and update your copy if others made and committed changes. It's very important to keep all files under the source tree, otherwise managing the code very, very quickly grows into a nightmare! Believe me, even if you think you're only going to deal with a couple of files.

CVS is installed on most of the InfoLab machines including the SUNs, DEC Alphas and HP's. It is also installed the pcd group machines on thames, oi, mjosa, and xingu. At the end of this file are special instructions for CVS on PCs.

CVS HTML 1.3 manual

CVS HTML 1.7 manual

CVS postscript manual

CVS II: Parallelizing Software Development postscript paper

Steps to use the testbed CVS repository

Our CVS repository is located on sole.stanford.edu in /u/testbed/CVSROOT. The following are the steps need to set your account up to use the repository.

Setting up your account.

1. Type:

	ls /u/testbed/CVSROOT

1a. If a list of files appears, then go on to step 2. If not, you don't have sole.stanford.edu NFS mounted, try another machine or contact Andy Kacsmar to work this out.

2. Type:

	groups

2a. Check to see if diglib is listed. If not, then you are not a member of the diglib group. Contact Marianne Siroker to get added to this group. Make sure that "diglib" is your first group, so files you add to the repository are accessible to all those fine DL folks. Hint for whoever takes care of fixing this for you: 'diglib' needs to be the group listed in your entry of the pwd file.

3. Check to see if cvs and rcs is installed and in your search path:

	which cvs rcs

3a. It should return with:

	/usr/local/bin/cvs
	/usr/local/bin/rcs

3b. Check your path for /usr/local/bin. If /usr/local/bin is not in your path, then added it and try #3 again. 3c. If /usr/local/bin is in your path and #3 is still not returning what is should, then your machine probably doesn't have cvs or rcs installed. You will need to get cvs, rcs, and diff installed on your machine. Contact Arturo Crespo for help.

4a. Add this to your ~/.cshrc file using your favorite editor:

setenv OSNAME `uname -s`
setenv OSTYPE `uname -s | tr "[A-Z]" "[a-z]"`

if(-r /usr/local/ilu20/ilu20a9/ilu.cshrc) then
        source /usr/local/ilu20/ilu20a9/ilu.cshrc
else if(-r /usr/local/ilu20a7/ilu.cshrc) then
        source /usr/local/ilu20a7/ilu.cshrc
endif

setenv DLHOME ~/dli2
setenv DLPATH ${DLHOME}/lib/c/${OSNAME}/:${DLHOME}/lib/python
if ($?PYTHONPATH) then
  setenv PYTHONPATH ${PYTHONPATH}:${DLPATH}
else
  setenv PYTHONPATH ${DLPATH}
endif

if ($?ILUPATH) then
  setenv ILUPATH ${ILUPATH}:${DLHOME}/interfaces
else
  setenv ILUPATH ${DLHOME}/interfaces
endif

setenv CVSROOT /u/testbed/CVSROOT

# If you are a vi user, keep the following line, else discard it:
setenv CVSEDITOR "vi"    
setenv CVSUMASK 002

You can substitute "emacs -nw -q" or some such for the editor, if you want to be snooty.

4b. You will also need to create a file in your directory called .cvsrc. You can copy it out of ~schirmer/.cvsrc if you want. It should contain a single line:

        update -d -P

4c. You will need to make your changes to your ~/.cshrc active, type:

	source ~/.cshrc

Time to checkout the source tree.

Find a spot to place to entire source tree. For most of us, this is our home directory. CD to it and type:

	cvs checkout dli2

This could take some time so get a cup of coffee.

When it finishes you should have a complete copy of the testbed code in a directory called 'dli2'.

Now you will need to create all of the symbolic links (since CVS does not currently keep track of them.) 'cd' to the dli2 directory and type:

	restorelinks

This will unpack a tar file called 'Links.tar'. You might see a lot of error messages fly by. Ignore them. The restorelinks script and its dual, savelinks, are a life saver in that they allow us to make symbolic links throughout the testbed code. The scripts ensure that we can re-create that web of links in every copy of the code. Links.tar is in essence the data structure on which the two scripts operate.

Time to commit changes to the source tree.

Let's say you have made changes in the source tree and everyone is begging for them. You need to commit the changes to the repository so that others can update their copies from the repository.

Often, you'll just have changed some file that is already in the repository. In that case, simply cd to the directory that contains the modified file and type:

     cvs commit -m '[comment describing your change]' [fileName]

You can commit multiple files by using wildcards. If you don't give any file name, this will commit all changes you made in the current directory and the ones below that. The comment should just be a half line or so describing what you've done to the file.

If you added a new subdirectory, or a tree of directories, rather than just modifying an existing file, then cd to just above each new directory in turn and type:

       cvs add [dirName]

This will schedule the addition of these directories to the repository. It won't actually do it until you do a commit. Next, if you added new files, use the command:

       cvs add [fileName]

You can use wildcards for this, but you need to be in the files' directory. This command again will just schedule the additions.

If your changes involved making links, then you need to execute the following commands so that everyone will have those links recreated:

      cd [to your dli2 directory]
      cvs update Links.tar
      # If this produces a line: 'U Links.tar', do the following command.
      # If you only get a prompt, skip this next line:
      restorelinks

Finally, cd to the topmost directory that includes modified files and type:

     cvs commit

Time to update your source tree.

If someone else has made changes that you want to incorporate into your source tree, you need to update. You can 'cd' to the top most part of the tree and type:

	cvs update

This will compare your source tree to the repository and update any files with a newer version. Since we have a lot of code, this can be a lengthy operation (about 10 minutes or so). If you know which files you want to update, just cd to the directory that contains those files and issue the update command there.

Note: If you suspect any symbolic links have changed, then you will need to do a 'restorelinks':

      cd ~/dli2
      cvs update Links.tar
      # If you see 'U Links.tar', then someone has added new links. In
      # that case:
      restorelinks

There are a lot of other features to cvs but these three are the core set you will need most of the time.

CVS on PCs

Well, CVS on PCs is still a bit flakey as of this writing. But we hope to get it stable.

CVS for PCs is distributed and maintained for GNU FSF by http://www.cyclic.com. They make their money by selling support for it. One of their pages offers alternative downloads of CVS for different operating systems. Starting with version 1.9.28, there is only one file: cvs.exe. The earlier versions were a messy conglomerate of support files. Don't get a version earlier than 1.9.28. Here's what you do to get cvs to work once you downloaded it and put the .exe file where you want it in your file system. Cvs.exe is not a self-extracting file, but the real thing (at least that's true for version 1.9.28):

Put the following into your autoexec.bat and reboot:

rem *** For CVS:
set PATH=C:\users\paepcke\software\cvs;%PATH%
set CVSROOT=:local:t:\CVSROOT
set CVSUMASK=002
set CVSEDITOR=C:\Emacs\bin\runemacs.exe
set HOMEPATH=C:\users\paepcke

Explanations:

PATH should be where you unzipped CVS
CVSROOT tells cvs where the actual repository is. It lives on /u/testbed/CVSROOT in Unix land. So it needs to be accessed through Samba while you are operating on your PC. For myself, I decided to always mount this directory under the drive letter 'T' (for testbed). If you enjoy a different drive letter, replace the 't' in this line. Note that you'll want a drive letter you are unlikely to use for something else. So don't take 'D:'. The 'local' is there because under Samba, the Unix file system is like a local system.
CVSUMASK tells cvs something about the permissions when creating new files.
CVSEDITOR tells cvs which editor to start if you do a cvs commit without using the '-m' flag, as in:
commit -m 'Fixed divide-by-zero bug' myfile.cc
Without the -m flag, cvs will bring up an editor for you to enter a note in when you commit. Content of CVSEDITOR is used for this purpose.
HOMEPATH is only needed to tell CVS where you are putting the .cvsrc file (see next bullet). If you put it into C:\, just do "HOMEPATH=\", leave out the C: since it gets added automatically

Put file .cvsrc into $HOMEPATH:

The file should contain a single line:
update -d -P
It ensures that when you do a 'cvs update', any new directories are also created in your local tree.

To run:

Now all you have to remember is that before using any cvs commands, you need to mount \\bigeye\testbed on drive T: of your PC (or whatever drive you chose). To get started, go to wherever you want the dli2 tree to be on your PC, and checkout some portion of the source tree. For example:

cvs checkout dli2/src/PilotsDL
or
cvs checkout dli2/src/wallets

Once you've done a checkout, all you need to do later is updates. Like:

cvs update dli2/src/wallets

to get any changes committed to the repository. You can also add new files or directories. Assume you are in dli2/src/wallets and have added a new subdirectory on your PC, called 'instruments', and you added some files in that new subdirectory:

   cvs add instruments            // add the new dir to the repository
   cd instruments                 
   cvs add *                      // add all new files to the dir NOTE BELOW!!!
   cvs commit -m 'Added new instruments dir and files'

NOTE: if you add a binary file, such as a CodeWarrior project file (.mcp), CodeWarrior constructor file (.rsrc), or Java byte code (.class), add the file as like this:

cvs add -kb WalletTests.mcp

This will tell cvs not to stick its header files anywhere in the file, or do line ending conversion, etc.

The commit is necessary, because adding files and directory is only 'scheduled', not executed, till a commit. The 'cvs add' will tell you so, no need to remember.

Known Bugs

When adding files or directories from a PC, the permissions in the repository get screwed up. To fix them, go to:
~testbed/CVSROOT/dli2/...
in the Unix world and fix the permissions. Give RW to owner and group. R to other. For directories, make them searchable. To do this, you have to log into Sole where the repository resides. Login name 'testbed'. See Andreas Paepcke (paepcke@cs) for the password.
Occasionally, files coming from the PC will have incorrect capitalization of their names. But that's becoming more rare.
There tend to be nasty error messages at the end of running some commands. Like "bad command or file name", and "internal error: file t:/... does not begin with root 't:\...". The latter seems an artifact of our using Samba to mount Unix as PC volumes. But the commands seem to run fine anyway.

Digital Libraries Webmaster
dlwebmaster@db.stanford.edu