SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
HEPIC E,S & H Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Workbook Home Introduction Account Setup QuickTour Packages Modules Unwrap page!
Event Information Tcl Commands Editing Compile and Link Run the Job Debugging
Check this page with the
W3C Validator
(More checks...)
Parameters Tcl Files Find Data Batch Analysis ROOT Tutorial

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.


SRT: A Software Release System Based on CVS

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:


Working with the Package Coordinator

IMPORTANT: Contact your Package Coordinator before making any changes to an existing BaBar package.

CVS for developers: The HEAD of a 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 HEAD of a package

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.

Tracking your changes: cvs diff commands

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:

  1. To see changes a colleague might have checked in since the last time you updated your checked-out version
  2. 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.

Updating to HEAD: cvs update -A

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.

Putting your files on the "add" list: cvs add

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.)

Test your code in Sun and Linux

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.

Commiting your code: cvs commit

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.

Tagging your package

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.

Using WebSrtAdmin to publish your package tag

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:


Back to Workbook Front Page