|
||||||
|
|
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.
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:
/afs/slac.stanford.edu/package/legacy/doc/cvs
on the SLAC UNIX system.
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:
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 difffrom 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:
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.
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 commitA 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.
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: