Configuration Control Procedures for ABLE
All of the ABLE source code and documentation files are managed using
CVS (Concurrent Version System). CVS is a front-end to an older tool
called RCS and provides a higher level interface to that program and some
features not supported directly by it. In a nutshell, it
is a revision control
system that allows multiple developers to work concurrently on the
same code. It has mechanisms to resolve conflicting changes and also
automatically tracks changes and maintains a database of revisions.
With CVS it is possible to mark different versions of the code as
checkpoints so that it's easy to revert back to an older version of
the system or some subset of the system. These versions might correspond
to released versions of the system or simply checkpoints before large
changes so that if need be one can revert back to old code for
whatever reason. There are also some mechanisms for supporting
multiple development paths.
This document describes some of the basics of CVS as well as
outlining our particular setup. Some details still need to
be worked out in terms of how we'll be managing revisions
but the basics will be the same.
All of the files for the able project live in a central CVS
repository. This is simply a central location which contains
incremental versions of the system and the information that
CVS needs to manage those files. For the most part only the
repository maintainer needs to anything about details. You do
need to set an environment variable to point toward the
repository. If you're using a csh derivative that's
setenv CVSROOT /afs/cs/project/able/sunos/cvs.
which is what you should be doing anyway since this will
have other useful setup goodies in it.
This should probably be done in your
In repository code is organized into modules which
are really just top-level directories of files. A listing of
all of the current modules and their contents will
also be maintained (with a link here eventually). Currently,
the major modules for ABLE are:
- This contains the main user interface code and defines the generic
style. New styles are derived from the code in this directory.
- This is the code that defines FCL. It includes C sources that
provide persistent database access and the Tcl code which defines
the higher level object system.
- Currently, most of the documentation for the project is here but
I believe that there is documentation that is not currently
in the repository.
- The additional code for the Unix Pipe Filter style. Includes
a main.tcl for starting the pipe filter environment.
- Some code used by unix-pf. I think that unix-pf is derived from
classes here. Currently, this is not a stand-alone style.
- The code for yet another style.
- The code for the change request tool.
Checking out and working with system
Working with repository involves a number of steps. First you need to
checkout a copy of the modules which you'll be working with.
You'll then periodically commit your version. In general you'll
want to commit when you reach stable points in development and before
you undertake something new that might break the system. The other thing
you'll need do is periodically update from the repository --
incorporate others changes into your code.
Create a directory for yourself to work in:
% mkdir /afs/cs/project/able/sunos/me
You can now check out a copy of the module with:
% cvs checkout <module name>
This will create a directory called me/<module name>
Once you make a change you can commit it back to the repository with
% cvs commit [module or filename in module]
At this point CVS will pop an editor for you (the editor is defined
in the environment variable
EDITOR) to type in a log message,
such as "broke the system beyond repair." Then you'll get
several messages that just mean everything is going OK.
Note that a commit will only effect files that have been added using cvs add. This is handy because it allows you to keep temporary files around your local collection without being bothered about them when you commit.
In order to add a new file to the repository after creating the
file in the directory use:
% cvs add <somefile>
You then commit this file to make it part of the repository
To update from the repository use:
% cvs update
Without a file name argument, this command lists the files in the
local collection that you have modified, and also checks for files in
the master collection that others have modified, but you have not. It
it finds any of these, it updates your local copy. Each file that has
changed in some way is listed with a single character marker. If you've
given it an argument this will only occur for your file. The
markers have the following meanings:
These messages will also occur if you commit without having
done an update.
- The file was updated in the master collection and your local copy has been updated.
- You added the file to your local collection, but have not yet committed the change to the master collection.
- You have removed the file from your local collection, but have not committed the change.
- You have updated the file in your local collection, but have not yet committed the change.
- The file has been updated both by you and in the master
collection, and the updates conflict. CVS will ask you to take steps
to figure out how to merge the two sets of changes. The regions of
conflict will be marked as text added to the file that contains
- The file is unknown which means it isn't in the repository.
Tagging and CVS Releases
The explanation above assumes you're working with what amounts to
to the most recent, main development version of the system.
CVS lets you maintain different versions with a mechanism
There is also a way to explicitly mark a certain version of the
repository -- that is mark all the files you've currently checked
either collectively or some subset. These give you an easy
way to refer back.
This will be text based upon Pete Psu's writeup and incorporate our
new scheme for version management -- i.e., what the branching.
Should start a picture like Pete's of how branching works in general.
Also explanation of revision numbers needs to be here..
I may also create some aliases that take care of the tagging
automatically if this looks like it will make things easier to
Also talk about the "build version" that we'll maintain on AFS...
still need to work out the details here.
Adding a module
At some point you may want to create a new module. In order to
keep track of big development decisions, I think it's probably a good
idea to let me (kompanek@cs) know you want a new module and I'll create
it so that you can check it. I think this will reduce the
chaos somewhat. If you realy want to know how this works there's
info. in Pete's old page.
about how to do other things, such as checking change logs, reverting
to the version of a module stored in the master collection and
aborting all your current changes, and other things, look at the CVS
man page. Summary information can also be found by typing cvs
There is a also a html'ized CVS Information page that's full of stuff you might want to
take a look at and has neat fish icons to boot. I'll stick a more official
pointer to the FAQ here (which I'll grab so we have it around), too.