SRT and CVS Background for Software Contributors
The developer's perspective on SRT, and what one needs to know to
write and modify code without screwing up the repository.
For new users, and those who want only to USE (not develop)
BaBar code, the Workbook's Packages
and Releases and SRT and CVS commands sections should have all of the information you need.
However, you may still find it useful to browse this section to find
out more about how SRT and CVS work. It's up to you.
Quick links:
Web SRT Administration Release Management Page
SRT homepage
The basic unit of software is referred to as a package, with many
packages being combined into a release. The whole release system is
often referred to as SRT, referring to SoftRelTools (Software Release
Tools) which is itself a package used to install and maintain
releases. The SRT are based on the Concurrent Versions System (CVS).
You use this system to run and develop BaBar code.
CVS is a widely used public domain tool for maintaining software. CVS
allows (several) people to modify software, keeping track of the
modifications and allowing specific copies to be "tagged."
(For those interested, CVS is a front end for the Revision Control
System, RCS, common for many years on UNIX systems.) These tagged
versions can then easily be accessed at any later time, even though
many changes may have been implemented since the original tag. The
released package versions referred to above correspond to CVS tags of
the appropriate files. CVS can maintain more than simple files,
including hierarchical collections of directories consisting of
revision controlled files. These collections of directories and
files, called modules, are maintained as a coherent whole.
Thus the files and subdirectories of a BaBar package can be maintained
as a whole, with new versions tagged as required.
CVS keeps a single copy of the master sources. This copy is called
the source repository; it contains all the information to permit
extracting previous software releases at any time based on either a
symbolic revision tag, or a date in the past. For BaBar this
repository is $BFROOT/repo.
Related documents:
- The full documentation for CVS can be found in
/afs/slac.stanford.edu/package/legacy/doc/cvs
on the SLAC UNIX system.
- CVS - Concurrent Versions System (Cederqvist):
Mirror 1,
Mirror 2
IMPORTANT: Contact your Package Coordinator before making any changes to an existing BaBar package.
Package tags are static. Once a package is tagged, it cannot
be changed by anyone.
The sole exception to this rule is the HEAD tag of a package.
HEAD is the most up-to-date version of the package. It is
constantly being edited by developers. So it is always changing.
Of course, if everyone were editing HEAD at the same time,
things would get very confusing and mixed up. So instead
of editing HEAD code directly, developers check out their
own private copies of HEAD and edit those. Then, once they
are done editing, they use CVS commands to commit
their changes to CVS.
Even then, there can be conflicts. For example,
suppose Alexander and Flora both check out the same version
of HEAD, and edit their own private copies. Alexander
gets done first, and commits his code to CVS. Then Flora
finishes editing, but when she goes to commit her code, she
finds that her changes are incompatible with
Alexander's.
CVS cannot prevent such conflicts, but it provides a
number of useful tools to help to manage them. The following
sections explain how to use CVS to follow the basic steps
involved in editing package code and commiting it to CVS:
- Check out the package with the addpkg command, as usual.
- Edit package code.
- Check to make sure your changes are compatible with HEAD.
- Commit your changes. When you commit a package, it
becomes the new HEAD.
If you are developing code, then the version of the package that you will
want to check out is the HEAD version. To check out HEAD, use the command:
addpkg -h <Package>
or the command
addpkg <Package> HEAD
Note: You do not have to use the HEAD tag of
the package. You can check out and edit your own private copy of
whatever tag you want. But if you want to commit your code,
your changes will have to be compatible with HEAD. This is more
likely to happen if you begin with HEAD.
Before you commit changes to the repository, you will want to
review the changes that you have made, and make sure they are
compatible with any changes that others have made. For this, you
need to use the "cvs diff" command.
First, to review your changes, issue:
> cvs diff <package name>
from your test release, or
> cvs diff
from your package.
This command will then list all the differences between your code and
the version that you originally checked out. This is exactly the list
of changes that cvs will assume that you then want to commit.
Also, before you commit your code, you will want to see if anyone
else has made any changes since you checked out the package:
> cvs diff -r HEAD
This command lists the differentces between your code (including
any changes you made) and the HEAD. If issued from a package,
it compares the package to the package HEAD. If issued from a
test release, the command is applied to each package in the
test release, one by one.
There are two uses for this:
- To see changes a colleague might have checked in since the last
time you updated your checked-out version
- To see the changes you have put in yourself since you checked out
the package
Don't be surprised if HEAD has changed since you last checked out
a file. That just means someone else has checked in some changes.
CVS does not ``lock'' files which are checked out. CVS only provides
the tools to help manage the development of software, it does not do
the management. This is the responsibility of the package coordinator
and other developers.
Other useful cvs diff commands include:
cvs diff -r TAG1 -r TAG2
Looks at the difference between TAG1 and TAG2.
cvs diff -D <date>
Looks at the difference between your currently
checked-out (and possibly modified) version of a package and the
version that was in CVS on the date specified.
You have already met the cvs update command and its important
"-n" option in the SRT and CVS commands section. An important variant of cvs update for developers is:
cvs update -A <package name>
This update command will bring your code up to date with the HEAD.
This is in contrast to the default cvs update, which looks only for changes to the
tagged version, and does not bring your code completely up to date with the HEAD.
As usual with cvs update, you should ALWAYS issue the command with the "-n" flag first:
cvs -n update <package name> -A
The -n command-line option causes cvs update to report what changes
it would do, without actually performing them.
If there are any
conflicts between the head and your version, you will need to resolve
them. Once this is done, a cvs update -A command will 'merge'
your version with the head. This means that you will have the latest
version with all the recent changes, including your own, and are now
ready to commit the updated package to the repository.
Just to be clear: The cvs update -A command affects only your
private copy of the package, not the HEAD. Your changes will not
go into HEAD until you commit your code.
CVS maintains its own list of the files in a package.
So if as part of your editing, you add or remove a file from
the package, you need to let CVS know, so that it can add or
remove the package from its list. Otherwise, the file will not
be added/removed when you commit your changes.
The command to add a file to CVS's list is:
cvs add <filename>
This schedules to be added with the next commit call to CVS.
(See the next section.)
Similarly, if you wish to remove files from a package, you need to do
cvs rm <filename>
to schedule the unwanted file for removal. (Simply deleting the file
from your checked-out release will not remove the correspoding file in HEAD
when you commit your code.)
Before you commit your code, you must test your package
on both Sun and Linux machines.
Linux machines include yakut and noric.
Sun machines include shire and tersk.
So far, you have been making all of your code changes in your private copy of
the release. The cvs update commands also affect your private copy only.
Your changes affect nobody but you. In order for your changes to
be incorporated into the HEAD, you have to use the cvs commit
command.
Before you commit your code, you should follow all the steps described in
the previous sections to make sure your new code is acceptable and compatible
with the HEAD.
To commit your files, do
Package> cvs commit
A window will appear where you should clearly detail
your changes, the contents of this will be sent to at least the
package coordinator and possibly to others too. After you have
described your changes, save the file.
Next, you need to tag your version of the package. You should ask the
Package Coordinator
what tag number to use.
Then, to tag the new version of the package, use the command:
Package> cvs tag [version number]
If the package coordinator decides not to specify an official tag for your version, then you should give your package a private tag (for example, "your_initials-date").
For more information about tags and how to keep track of them, the reader is strongly recommended to refer to the Workbook's general SRT and CVS commands section, in particular the Keeping track of tags section.
The final step in commiting a new version of a package is to go to the Release Management Page:
Web SRT Administration Release Management Page
This page contains detailed instructions on how to update a tag. You will need to login with your usual (hypernews) username and password, and click on the "Package Publication" link in the left column. Then you will fill out a form with information about your package tag.
Note that package publication should be done only by the package coordinator or people authorized by the package coordinator.
Related Documents:
Page maintained by Adam Edwards
Last modified: January 2008
| 