Source Control

Using CVS

Active projects are being migrated to a new directory structure using a common set of make files. Have Brad help you set up any new project. Students actively working on legacy projects can also begin to migrate to the new directory structure.

CVS keeps track of changes to every file, allows concurrent editing of source code by multiple people, and provides an easy means for copying source trees to new locations. Before working with CVS you should read some introductory web pages about it until you are comfortable with the basic concepts. In order to maintain the integrity of our code base it is imperative that you understand the effects of any CVS command you use.

Introduction to CVS

Setting up CVS

On Linux add the following to your ~/.environment file:

setenvvar CVSROOT /map/gfx0/cvsroot/

On Windows set CVSROOT to: Y:\map\gfx0\cvsroot\

The scripts in $G/common/build/setup/ can be used to perform common CVS operations. They simplify check ins and use integrity checks to avoid common mistakes.

CVS commands you might find handy

> cvs update -d <directory>                # Bring a new directory into your sandbox.
> cvs log <file>                           # List log messages for a file.
                                  
> cvs add -m "add directory" <directory>   # Create a new directory.

> cvs add -m "add file" <file>             # Create a new file.
> cvs commit -m "commit file" <file>

> cvs delete <file>                        # To delete first remove the file from your sandbox.
> cvs commit -m "gone" <file>

> cvs export -D NOW <directory>            # Snapshot without administative directories.
> tar cvf <project>.tar <directory>        # Make a tar ball.
> gzip <project>.tar                       # Compress it into: <project>.tar.gz

> cvs checkout -D yesterday <directory>    # Get previous versions of a directory.
> cvs checkout -D "<#> hour ago"
> cvs checkout -D "<month>/<day>/<year>"

How Not To Use CVS

• Avoid checking in entire directory trees with junk files.

Clear out edit backups, binaries, and irrelevant file first or do selective check-ins.

• Check in source files only.

Do not check in files generated by tools.

• Overwriting other people’s changes is bad.

Revision control is not a substitute for coordinating with your peers.

• Don’t trust automated CVS features.

They are primitive and not bulletproof.

• Don't Lock (Reserve) Files.

• Think Twice about Creating Directories.

CVS does not have a command for renaming or deleting directories.

Legacy Code in $G/src/

This page describes how the bulk of existing code in $G is organized. Active projects are being migrated to a new directory structure using a common set of make files. Until the procedures are in place have Brad help you set up any new project. Students actively working on projects can also begin to migrate to the new directory structure.

The $G tree is not intended for users to write to directly, and future IT plans for our group include enforcing this restriction. Instead, we use the revision control system CVS as an interface to the directory structure in $G. CVS keeps track of changes to every file, allows concurrent editing of source code by multiple people, and provides an easy means for copying source trees to new locations.

Ordinarily, the first steps of development for your own software project happens somewhere in your homedir. This doesn't allow other people to work with your code, though, so once your project is nontrivial you should add it to $G using the gfxprojinit script. This script creates a home for your project in $G/src, but not everything associated with a given project belongs there. To get everything into the right place, follow these steps:

1. Go to the directory that has your source in it.
2. Delete or move away anything you don't want to go into CVS. If you already have something compiled, do make clean to get rid of the object files --- you don't want to put them in CVS. In general, just leave the Makefile and the source files.
   • Note: even though non-source files are sometimes necessary for builds of complex projects, data and config files don't belong in $G/src! Carefully consider whether non-source files belong in the $G/src; they most likely do not and belong in $G/lib (or $G/data for example data on which your program runs) instead. Move these out of the directory temporarily; we'll check them into the appropriate locations later.
3. If you have any binary files, like images, that you want to go in CVS, move them out of this directory temporarily. We will add them later because CVS requires non-text files to be added with a special flag. Once again, keep in mind that most binary files are program resources and belong in $G/lib rather than $G/src.
4. Run the following command, replacing <projectname> with the name you want your project to have --- that will become a new directory under $G/src:

   gfxprojinit <projectname> .

   • Note the period at the end of that command. It might be hard to see, but it is important.
   • It's worth knowing, for those familiar with CVS, that gfxprojinit is essentially a fancy wrapper around cvs import. Please be sure to use gfxprojinit anyway, as it maintains important metadata and may do even more in the future.
5. If you had some extra files you wanted to add to CVS, like build components, config files, program resources, or example data, you now want to check them into the relevant directories, which will be among $G/src/<projectname>, $G/lib/<projectname>, and $G/doc/<projectname>. For each relevant directory, which we'll call $X, do the following:
   1. Create $X, import it into CVS, then delete it and check it back out.
   2. Copy each appropriate file into $X, and for each one run the command:

      cvs add -kb <filename>

   3. After adding all the files, run:

      cvs commit -m "<commit message>"

6. Your project should have been automatically added to the $G/src directory on the filesystem you are on now. To get it in the $G/src directory somewhere else, like at the Cave, run this command from within $G/src:

   cvs update -d <projectname>

   You may also need to use the same command in $G/lib and $G/doc.