SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Introduction
Non SLAC
HOWTO's
Introduction
Logging In
QuickTour
Detector
Info Resources
Software Infrastructure
CM2 Introduction
Unix
OO
SRT
Objectivity
Event Store
Framework
Beta
Modifying Code
Writing and Editing
Compiling
Debugging
Analysis
Framework II
Analysis
Find Data
Batch Processing
PAW
PAW II
ROOT I
ROOT II
ROOT III
Advanced Infrastructure
New Releases
Workdir
Main Packages
Event Displays
Gen/Sim/Reco
Contributing Software
SRT and CVS
Coding
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Java
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

Workbook for BaBar Offline Users - SRT: the Software Release Tools

Discusses just those parts of SRT and CVS that are necessary to run existing code. (Information on how to contribute new code to the BaBar software repository is covered in a later section.)

Software Structure

BaBar File Organization

BaBar software and other files are currently located on a NFS (Networked File System) or AFS (Andrew File System) file system which is mounted on all the public UNIX workstations at SLAC. Most references to the BaBar file system should be made through the environment variable BFROOT. In this way users are protected from changes in the physical location of the disks.

This directory is administered by the BaBar Tools and Utilities group and you should contact Terry Hung for further information. The following illustrates the $BFROOT directory and its subdirectories.

                                    $BFROOT/
  -------------------------------------|-------------------------------------
 |                                                                           |
bin data demo dist doc etc fonts include lib man package prod repo src www  ...

Quick guide to the subdirectories of $BFROOT.

The bulk of BaBar specific software is organised and maintained in a single, self consistent file system under $BFROOT/dist (for distribution). This directory may also be accessed through the BFDIST environment variable.

Packages

BaBar (reconstruction and simulation) software is organised in terms of packages. A package is a self-contained piece of software intended to perform a well-defined task. For example, a package might find calorimeter clusters, or simulate the drift chamber response. Each package has a unique name and its own library and include files. Some packages may not be usable on their own, but require integration with others. For example, the GEANT simulation of BaBar is made up of individual subsystem simulation packages that only work together.

Packages are maintained by a package coordinator, who is responsible for testing the code and releasing new versions when appropriate. The source code (plus documentation etc.) for stable, self consistent versions of all packages are found in their own subtrees under $BFROOT/dist/packages. Within each package subtree, there may be one or more "versions." This allows the package coordinator to "publish" code as needed and leaves the issues of naming, timing and quality control up to the relevant experts. All the files required for the package should then be contained within the single package directory which will also include a GNUmakefile which implements some standard targets and definitions. Older packages may exhibit some deviations from this convention.

Here is a list of packages as of 19 Janary 2006.

The HbkTuple package, for example, then had the following subdirectories

    > ls $BFDIST/packages/HbkTuple
V00-05-02  V00-05-08  V00-13-00  V00-17-00
V00-05-06  V00-10-03  V00-15-05  V00-18-00
Each version of the package code has been labelled with a version number and placed in a directory of the same name. The version number is the CVS tag for the package. Each version directory contains all the code that you would get if you checked out the package:
    >  ls $BFDIST/packages/HbkTuple/V00-18-00/
GNUmakefile      HbkReader.cc         HbkTColumnInt.cc     bin_HbkTuple.mk
HISTORY          HbkReader.hh         HbkTColumnInt.hh     example.cc
HbkExist.F       HbkTColumn.cc        HbkTColumnString.cc  link_HbkTuple.mk
HbkFile.cc       HbkTColumn.hh        HbkTColumnString.hh  testHbkHisto.cc
HbkFile.hh       HbkTColumnBool.cc    HbkTuple.cc          testHbkTM.cc
HbkHistogram.cc  HbkTColumnBool.hh    HbkTuple.hh          testHbkTM2.cc
HbkHistogram.hh  HbkTColumnDouble.cc  HbkUtils.cc          testHbkTM3.cc
HbkInit.F        HbkTColumnDouble.hh  HbkUtils.hh          testHbkTM4.cc
HbkProfile.cc    HbkTColumnFloat.cc   README
HbkProfile.hh    HbkTColumnFloat.hh   basic.t

Note that there are no binary files (executable or library) and that the files in these package directories are reference copies for the given version and should not be modified. The actual development code, from which the reference copies are taken is maintained using CVS which is detailed below.

Related documents:

Releases

A software release consists of a consistent set of packages together with the libraries and binaries created for various machine architectures. Within the $BFROOT/dist/releases subtree there is a subdirectory for each existing release. These are typically names with simply a number, e.g. $BFROOT/dist/releases/18.3.3/ will contain all the binaries and libraries for release 18.3.3. The release also contains pointers to the tagged reference versions of the packages (implemented using UNIX links to the relevant package subdirectories). The release coordinator can create releases of various quality levels. Given releases may then be retained for as long as required. Symbolic links within the releases directory can be used to provide useful default names for particular releases, for example, current will point to the release recommended for general use at any given time.

Once this dist tree has been installed on a user's machine, the source code, libraries and binaries of any particular versions can be directly accessed through the releases tree. The user can then stay with a particular release until it is appropriate to move to a newer one. In the meantime, package coordinators can be creating new versions of their code and integrating them into releases entirely asynchronously.

The $BFROOT/dist/releases tree's subdirectories, circa 19 January 2006, were:

    > ls $BFROOT/dist/releases/
10.0.1-physics-1.lst   16.0.5a                         analysis-11
10.0.3-online-1.lst    16.1.1                          analysis-12
10.1.0-physics-3.lst   16.1.1i                         analysis-12a
10.2.3-online-1.lst    16.1.1j                         analysis-12b
10.2.3.lst             16.1.3                          analysis-13
10.3.0.lst             16.1.3a                         analysis-13a
10.3.1.lst             16.1.5                          analysis-13b
10.3.1k                16.1.5b                         analysis-13c
10.4.0-physics-1.lst   16.1.5c                         analysis-13d
10.4.0-physics-1a.lst  17.1.0                          analysis-14
10.4.0-physics-1b      18.0.1a                         analysis-14a
10.4.0.lst             18.0.4                          analysis-20
10.4.1.lst             18.0.4d                         analysis-21
10.4.4-online-3        18.1.0                          analysis-22
10.4.4-physics-1b      18.1.0d                         analysis-23
10.4.4-physics-3       18.1.0e                         analysis-24
10.4.4.lst             18.1.2                          analysis-25
10.4.6                 18.1.2f                         analysis-26
12.4.0                 18.2.1                          analysis-30
12.5.2                 18.2.1b                         analysis-8
12.5.2-physics-1a      18.3.1                          current
12.6.0                 18.3.1a                         emcDev
12.6.0f                18.3.1b                         ifrDev
12.6.1                 18.3.1c                         log
14.3.2                 18.3.1d                         newest
14.3.2i                18.3.2                          nightly
14.4.3                 18.3.2a                         nightly-20060112
14.4.3g                18.3.2b                         nightly-20060113
14.4.5                 18.3.3                          nightly-20060114
14.4.6                 18.6.0                          nightly-20060115
14.4.7                 18.6.0a                         nightly-20060116
14.4.7a                18.6.0b                         nightly-20060117
14.4.7b                18.6.1                          nightly-20060118
14.5.2                 18.6.1a                         nightly-Friday
14.5.2a                18.6.1b                         nightly-Monday
14.5.2b                18.6.1c                         nightly-Saturday
14.5.2c                18.6.1d                         nightly-Sunday
14.5.2d                18.6.2                          nightly-Thursday
14.5.3                 18.6.2a                         nightly-Tuesday
14.5.4                 18.6.3                          nightly-Wednesday
14.5.5                 19.0.0                          online_use
14.5.5a                19.1.0                          simDev
16.0.2                 19.2.0                          test-SRT
16.0.2f                19.3.0                          test-SRT1
16.0.3-physics-1       19.3.1                          test-SRT2
16.0.3-physics-1a      19.4.0                          trkDev
16.0.3-physics-1b      AllEvents-Run3-OffPeak-R12.tcl
16.0.3a                ImportSun58_sparc_WS6U1

Most of the releases listed above are numbered releases, such as 14.3.2a, 15.8.0, 16.1.1d, 17.1.0, and 18.0.4b, The higher the number, the newer the release. Releases with the same first number (in the same series) are very similar. For example, releases 18.3.3 and 18.6.1 in both 18-series releases, so the differences between them are probably small. But releases in different series, like 14.5.5 and 16.1.3, are probably very different. Some of the releases listed above have names that are words, not numbers. These names are actually soft links to a numbered release. For example, the "current" release on January 19 was:

    > ls -l $BFDIST/releases/current
lrwxr-xr-x    1 drjohn   bfactory       17 Mar  3  2005 
/afs/slac.stanford.edu/g/babar/dist/releases/current -> 16.0.3-physics-1a
is actually a pointer to 16.0.3-physics-1a. The current release is the most stable release and should be the default choice for users. Meanwhile, the "newest" release,
    > ls -l $BFDIST/releases/newest
lrwxr-xr-x    1 drjohn   bfactory        6 Jan 12 08:23 /afs/slac.stanford.edu/g/babar/dist/releases/newest -> 19.4.0
is a pointer to 19.4.0. After a period of testing, if found to be stable and reliable, this release may become the current release. Some in-between release versions have presumably been deleted and never made it to current due to various bugs and features.

The release analysis-30, which you used in the Quicktour

    > ls -l $BFDIST/releases/analysis-30
lrwxr-xr-x    1 gpdf     bfactory        7 Dec 13 15:16 /afs/slac.stanford.edu/g/babar/dist/releases/analysis-30 -> 18.6.2a
is a actually a link to release 18.6.2a. Usually, a release with a special nickname like that is one that has been specifically tested for physics analysis jobs. Other 18-releases without nicknames, like 18.3.2, have not had the same special testing.

Take a look at directory analysis-30:

    > ls $BFDIST/releases/analysis-30
AbsBTagging              DrcOprMon           OepCommon
AbsCalo                  DrcPidUtils         OepConfigModules
AbsEnv                   DrcReco             OepConfigP
AbsEvent                 DrcSequence         OepDaemon
AbsEventTag              DrcSim              OepDaemonFramework
AbsParm                  DrcSimGeom          OepDaemonLink
AbsPid                   DrcSimGeomP         OepDataP
AdminScripts             EffTable            OepEvent
...
...
DrcGeom                  OdfCompression      tagFile
DrcGeomP                 OdfContainer        tags-18.6.2a
DrcMonTools              OdfContainerTools   tauola
DrcOep                   OdfDhpServer        test
DrcOepCalib              OdfDisplayCommon    tmp
DrcOepSequences          OdfFastMon          trgDC
DrcOfm                   OdfFileTransport    trgFrame
DrcOnline                OdfOffline          unt
DrcOnlineConfig          OdfServiceCommon    vcs
DrcOnlineInput           OdfZLib             workdir
DrcOnlineSim             OepAllSequences
DrcOpr                   OepBuffer
Each of the packages is included in the release via a symbolic link to the relevant subdirectory in the packages tree; for example:
    > ls -l $BFDIST/releases/analysis-26/workdir
lrwxr-xr-x    1 drjohn   root           32 Aug 17 17:07 /afs/slac.stanford.edu/g/babar/dist/releases/analysis-26/workdir -> ../../packages/workdir/V00-04-20
(This is all one line, but has been broken up here to fit on the page.) (Here analysis-26 has been used as an example, because analysis-30 is a special case, with an unusual soft link.) The include directory similarly contains links the include files for the packages:
    > ls -l $BFDIST/releases/analysis-30/include
total 983
lrwxr-xr-x    1 ruben    br             27 Dec 12 12:41 AbsBTagging -> 
../BASE/include/AbsBTagging
lrwxr-xr-x    1 ruben    br             23 Dec 12 12:41 AbsCalo -> 
../BASE/include/AbsCalo
lrwxr-xr-x    1 ruben    br             22 Dec 12 12:41 AbsEnv -> 
../BASE/include/AbsEnv
...
...
lrwxr-xr-x    1 ruben    br             19 Dec 12 12:42 unt -> 
../BASE/include/unt
lrwxr-xr-x    1 ruben    br             19 Dec 12 12:42 vcs -> 
../BASE/include/vcs
lrwxr-xr-x    1 ruben    br             11 Dec 12 12:20 workdir -> 
../workdir/
The bin and lib subdirectories contain further, architecture-specific directories, which in turn contain the binaries and libraries for that release.
    > ls $BFDIST/releases/analysis-30/bin
Linux24SL3_i386_gcc323  SunOS58_sparc_WS6U1
    
    > ls $BFDIST/releases/analysis-30/bin/Linux24SL3_i386_gcc323
...
BearApp
BetaApp
BetaMiniApp
BetaMiniQAApp
...
You can see that BetaMiniApp is only one of the many applications that you can create when you link BaBar software.
     > ls $BFDIST/releases/analysis-30/lib/Linux24SL3_i386_gcc323
...
libBear.a
libBeta.a
libBetaBogus.a
libBetaBuildPidEnv.a
libBetaCoreTools.a
libBetaEvent.a
libBetaExamples.a
libBetaIfrPidCalib.a
libBetaLumi.a
libBetaMC.a
libBetaMicro.a
libBetaMicroAdapter.a
libBetaMicroBase.a
libBetaMicroTruth.a
libBetaMini.a
libBetaMiniData.a
libBetaMiniModules.a
libBetaMiniQA.a
...
In general, every packages has its own lib (".a") file, created when that package is compiled.

ral.gifSpecial for RAL: Releases

lbl.gifSpecial for LBL: Releases

Symbolic Releases

As indicated above, several symbolic links in $BFDIST/releases are used to refer to particular releases. These symbolic releases are defined as follows:
newest
The most recently built release. The only quality requirement is that the release (mostly) compiled. The release coordinator (Matthias Steinke) determines which release this should point to.
current
This release is the most recent to have reached an acceptable level of quality. Acceptable is detemined by a combination of code and physics checks as defined by the QA/QC group with input from the physics groups and detector subgoups. The QA/QC coordinator (Chris Hawkes) determines which release this should point to.
analysis-xx
These releases are successful physics analysis releases which have been tested and found stable for analysis jobs. analysis-30, the release used in the Workbook, is one such example.
Other symbolic release names exist, as you saw in the directory listing above. These releases, such as "online" and "database", are defined as and when required and refer to specific uses.

The "nightly" is the culmination of everyone's submitted changes to individual packages. Each night SLAC attempts to compile the very latest version of the code with all changes and emails are automatically sent to package coordinators with details of what crashes.


A Software Release System Based on CVS - Concurrent Version System

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.

For BaBar software, CVS is to a large extent hidden from the users by the SRT, which automatically provide access to a consistent set of source code without requiring you to know which tagged version of each package that you need. For example, in the Quicktour, when you entered the SRT command:

addpkg workdir
SRT automatically gave you the correct version of workdir for analysis-30, namely V00-04-20. You can check the tag by doing:
    > cd ~/ana30/workdir
    > showtag
. V00-04-20
kumac V00-04-20
So you have tag V00-04-20 of workdir.

ral.gifSpecial for RAL: CVS

Related documents:


Using SRT

The basic principle behind SRT, from a user's point of view, is that users create their own, private, releases, similar to those found under $BFDIST/releases. In the user's case, however, a release is typically a very lightweight collection of directories and is tied to a full BaBar release. With the initialisation and creation of a user's release comes a GNUmakefile which "knows" where to look for binaries, libraries, and include files of the official BaBar release.

For example, in the Quicktour you checked out the release analysis-30, which contains many packages. However, the only packages that you need to check out are the workdir package, needed to run the analysis, and any other package for which the default tag (the tag in $BFDIST/releases/analysis-30) is not good enough. In the Quicktour you added BetaMiniUser, because you wanted to modify some of the code in BetaMiniUser. You also added a number of special tags of other packages to fix some bugs. The release "knows" that when it is looking for code, it is supposed to look in your personal release first, and in $BFDIST/releases/analysis-30 second.

Two tasks performed by the Hepix login scripts are modifications of the PATH and MANPATH environment variables for your unix account. The extension of PATH gives you access to the SRT commands and the current versions of other BaBar binaries. The extension of MANPATH gives access to the man pages for BaBar commands such as those used below (newrel etc.). If issuing SRT commands results with error messages you should check the PATH variable and make sure you have the Hepix scripts in your login shell.

Selecting an Appropriate Release

As previously discussed, current is a symbolic link to the release that is deemed stable by the package coordinator. Most users will want to use current, because the newest release may have strange features that have not been discovered and fixed yet.

Setting up a Test Release

One of the first steps taken in the sample analysis job run in the Quicktour was to create a new release.

The newrel command creates a release within the BaBar software release system.

There are two types of releases supported, test and production. Production releases are created by advanced BaBar code-writers, for eventual inclusion in $BFDIST/releases. Test releases are private copies of the base releases in $BFDIST/releases, for a user's own analysis. At this time we will only use and discuss test releases.

To use new versions of packages, you need to set up a test release in your working area. The syntax is:

newrel -t <BASE-RELEASE> <TEST-RELEASE>
A test release called TEST-RELEASE, with links to the BASE-RELEASE in $BFDIST/releases, will be created in the current directory. Once a test release is established, one can use addpkg to add packages into this release. Your new release directory test-release will contain several empty directories (bin, doc, include, lib, man, results and tmp) and a GNUmakefile. The GNUmakefile has been copied from the base release and is the master one for the release. It is this make file which "knows" where all the libraries and include files are. That is, when using gmake to compile an executable in TEST-RELEASE, the appropriate include and lib directories of BASE-RELEASE:
$BFROOT/dist/releases/BASE-RELEASE
will be searched for any code not in found in your test release. The first command in the Quicktour analysis was
newrel -t analysis-30 ana30
This created a test release named ana30 based on analysis-30 release (also known as 18.6.2a).

The command-line option for newrel, -s scratchdir, puts the lib, bin, and result directories in a "scratch" directory scratchdir, with symbolic links from their normal places in the release directory.

The complete syntax is:

newrel -s scratchdir -t prod-release test-release

The recommended scratch area for BaBar builds is:

$BFROOT/build/<first_letter>/<username>
For example, if your username is "kiwi", you would use:
$BFROOT/build/k/kiwi
This scratch area is attached to a fast server to allow it to handle a high volume of I/O. You also have a scratch directory at:
$BFROOT/work/<first_letter>/<username>
but this one is not as good for builds. There are other non-BaBar-specific NFS disk areas which can also be used, but they aren't as good as $BFROOT/build, either.

If you want, you can define the environment variable MYWORK to this directory and pass it an argument to the newrel command. For example:

setenv MYWORK $BFROOT/work/k/kiwi
newrel -s $MYWORK -t analysis-30 ana30

The first command sets the MYWORK environment variable to the pathname of the user's scratch space (a directory called ${USER} in the babar work space). The newrel command issued creates a new release called ana30 which is based on release analysis-30. This will create a directory by the same name (ana30) in the current working directory, some subdirectory structure, and a file called ".current", and it will copy over the master GNUmakefile. Since the -s flag (for scratch space) was given, an analysis-30 directory is created in the user's work space with subdirectories bin, lib and results. Symbolic links to these scratch subdirectories are created in the ana30 new release directory.

Setting Up the Release Directory

After creating a new release you should issue the srtpath command from the release directory.

Syntax:

srtpath <rel> <arch>

This command sets up several important variables for BaBar's Software Release environment:

  • BFCURRENT = Release number.
  • BFARCH = Architecture of current machine.
  • PATH = Search path for executables.
  • MANPATH = Search path for man pages.
In the Quicktour, after you checked out your release, you did:
   > cd ana30
   ana30> srtpath
The system responded:
enter release number (CR=18.6.2a):
When you pressed <enter>, you accepted the default release offered, namely 18.6.2a.

The system then offered you a choice of architectures:

Select/enter BFARCH (CR=1):
Select/enter BFARCH (CR=1):
1) Linux24SL3_i386_gcc323      [prod][test][active][default]
2) Linux24RHEL3_i386_gcc323    [default2]
When you pressed <enter> again, you accepted the default architecture, which was "1) Linux24SL3_i386_gcc323". In general it is a good idea to accept srtpath's default, because it usually knows what it is doing. Now the environment variables should be set:
    > echo $BFCURRENT
    18.6.2a
    > echo $BFARCH
    Linux24SL3_i386_gcc323
    > echo $PATH
    /usr/local/bin:/usr/afsws/bin:/usr/afsws/etc:/bin:/usr/bin:/sbin:/usr/sbin:
    /usr/etc:/usr/bin/X11:/cern/pro/bin:.:/afs/slac.stanford.edu/g/babar/bin:
    /afs/slac.stanford.edu/g/babar/package/objy8.0.9/babar/linux86gcc3/bin:
    ./bin/Linux24SL3_i386_gcc323:/afs/slac.stanford.edu/g/babar/dist/releases/
    18.6.2a/bin/Linux24SL3_i386_gcc323:/u/br/penguin/bin
    > echo $MANPATH
    ./man:/afs/slac.stanford.edu/g/babar/dist/releases/18.6.2a/man:::
    /afs/slac.stanford.edu/g/babar/man
So srtpath has ensured that you are using the correct binarires and man pages for the given release, and the correct architecture for the machine that you are using.

The primary use of srtpath is to set up your working environment to access the appropriate code. The syntax of this command also supports developers who want to switch between architectures, and allows for explicit architecture assignment in locations where Hepix scripts do not exist.

The srtpath command is actually an alias for running a script. We can see this by issuing the command:

   > which srtpath
   srtpath: aliased to set dialog=1; set argument=(!*); 
                       source $BFROOT/bin/SRTstartup.csh;
                       unset dialog argument
To ease the network access, a remote site can install srtpath.csh locally and set an alias pointing to this C-Shell script.

Checking Out Packages

In the case of test releases (newrel -t) no actual packages are included, they will need to be added explicitly. The addpkg command checks out a package from the CVS repository. The default version of the package added to your release is the tagged version corresponding to the release with which you originally created test-release. There is an optional argument to the addpkg command that allows you to specify a which tagged version of the package to add to your test release. This is useful for development and often arises as a fix. Modified versions of a release, often intended to fix discovered bugs, are commonly described by using a designated release as the base of your test release and then adding a number of packages of specified tagged versions.

The full syntax is :

addpkg <pkgname> [<version_tag>] 

A directory with the same name as the package will be created in your test release directory. It contains all files and links relating to the package. The addpkg command also issues the gmake installdirs command. This command creates architecture-specific directories for storing the package binaries.

If you addpkg a package which already exists in your release, then addpkg will, after confirming with you, update the package directory to the version appropriate for the release and will then check that the required links (in the include directory) are present.

ral.gifSpecial for RAL: Running at both SLAC and RAL

Work Directory

In the Quicktour analysis a work directory was created from within the release directory with the command:
addpkg workdir
workdir is a package from which you can run applications. In the quicktour analysis job you used the workdir to run Beta, the analysis package.

Before use, the workdir directory must be initialized. For this purpose there exists the following command (which you issued during the quicktour analysis session):

gmake workdir.setup
setup is one of the targets defined in the GNUmakefile of the workdir package. The make process is initiated with the gmake command. This will be discussed in more detail in the Compile, Link, and Run chapter of the workbook. A main result of gmake setup is that many symbolic links are created. A few of the key links are defined as follows:
RELEASE
By default this is a link to the directory one level up in the tree, the release directory: ../
PARENT
This is a link to the production release directory under BFDIST that corresponds to the base release with which the new release was created: ~/ana30/
bin
This link points to the bin directory of the RELEASE directory: RELEASE/bin/
The workdir package is a rather unusual package. It will be further discussed in Beta: the Analysis Package and The workdir Package.

At this point the new release and work directories are created and ready for the user to begin using standard analysis tools, modifying or writing code, and other forms of work.

Related documents:

  • For more background on SRT and what specific commands do, refer to the SRT documentation (old, but useful background): $BFROOT/dist/releases/current/SoftRelTools/*.ps
  • User's Guide to the Software Release Tools (Also obsolete, but general discussion is okay)
    Bartelt
  • newrel, srtpath, and addpkg have man pages

Resuming after a New Login

One may be curious to know what parts of the set up completed are "permanent" (will remain after logout) and what steps will be lost or will possibly become outdated before the user's next unix session.

Changing Architecture

If you login to a unix machine of a different architecture than the one from which the release directory was created (or last worked on) you will need to modify your setup with:
gmake installdirs
It will create directories corresponding to the architecture of the new machine. You will then need to compile and link your code to create a new executable that is compatible with the new architecture. The architecture-dependent directories that gmake installdirs creates are used to store the executable and intermediate files produced in creating an executable. You did not have to enter "gmake installdirs" in the Quicktour. This is because "gmake installdirs" is done automatically by various scripts, such as addpkg. In the Quicktour analysis you added several packages before creating the executable, thus a gmake installdirs command was executed, and the required directories were created.

Tracking Your Work

Documenting Your Environment

Note:: The following commands do not document any modificiations of files made by you, the user. They give information only on the structure of your release, that is the contents of packages, which tagged versions you have, and so forth. Still, they can be useful when trying to solve problems encountered using the analysis software with your release.

There are a few instances within BaBar software when GNUmakefiles are used as a means of defining general commands. This is done by creating a "phony" target that when invoked by gmake performs a sequence of tasks. A target spec is added to SRT to help control and monitor the configuration. When you enter gmake spec at the command line, it prints out your environment variables and the complete addresses of important directories. Also, when you compile and link with gmake all, the output of gmake spec is stored in your a file with a name like .spec.$BFARCH.1 or spec.$BFARCH.2 in your test release.

showtag
The showtag command displays tag level of a CVS folder for all packages of a test release. Additionally, it displays the tags numbers on each package that you have checked out. showtag can be run in a CVS check-out folder to display its tag level. It can also be run from a test release to display the tagged level of all packages. If a CVS folder (package) is a tagged version, then the ./CVS/Tag file in the package directory contains this tag with prefix T. If the folder is at HEAD level, then this file does not exist.

statusrel
The statusrel command lists the contents of a release within the BaBar Software Release System. The syntax is:
statusrel [-t] <release> [<pkg>]

For each package contained with a release, statusrel prints to standard output the package name, the version number of the package used, and (if different from the version used) the tag of the most recent available version.

The command-line option, -t, signifies test release. It treats the current directory as a test release based on <release>. It also prints the tag in <release>, if different from the version used. For example, in the Quicktour you could have entered:

> statusrel -t analysis-30
statusrel version: 1.5
Treating current directory as a test release based on analysis-30
BetaMiniUser  V00-04-00  (Release uses V00-04-00)
workdir  V00-04-20  (Release uses V00-04-20)

For other command-line options check out the man page for statusrel.

Showing What Files you have Modified and Updating Files

It is often useful to check what you have changed. You can do this with:

cvs diff <package name>

This command will then list all the differences between your code and the version that you originally checked out.

In the Quicktour, we made a few changes to BetaMiniUser:

> cvs diff BetaMiniUser
cvs diff: Diffing BetaMiniUser
Index: BetaMiniUser/AppUserBuild.cc
===================================================================
RCS file: /afs/slac.stanford.edu/g/babar/repo/BetaMiniUser/AppUserBuild.cc,v
retrieving revision 1.47
diff -r1.47 AppUserBuild.cc
16a17
> //      Sheila Mclachlin                (workbook modifications)
34a36,37
> #include "BetaMiniUser/NTrkExample.hh"
>
40a44,47
>
>   // NTrkExample Module
>   add ( new NTrkExample( "NTrkExample", "Workbook example module"));
>
Index: BetaMiniUser/MyMiniAnalysis.tcl
===================================================================
RCS file: /afs/slac.stanford.edu/g/babar/repo/BetaMiniUser/MyMiniAnalysis.tcl,v
retrieving revision 1.29
diff -r1.29 MyMiniAnalysis.tcl
3a4
> # Modified for the Workbook by Sheila Mclachlin
31,36d31
< ##
< ## Set the number of events to run. If this isn't set, all events in the
< ## input collections will be processed.
< ##
< FwkCfgVar NEvent
<
93a89
> path append Everything NTrkExample
115,122d110
< if [info exists NEvent] {
<   ev begin -nev $NEvent
< } else {
<   ev begin
< }
<
< ErrMsg trace "completed OK"
< exit
<

A few variants on this command that are very useful include:

cvs diff -r HEAD -r V00-07-40

To look at the difference between two tags. Here the HEAD is the most recent (potentially un-tagged) version of the code.

cvs diff -r HEAD

This command is usually used by developers to see the difference between code they are editing and the HEAD of the package. 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
cvs diff -D <date>

Here <date> is a date string, that can be given in several formats, to get the difference between your currently checked-out (and possibly modified) version of a package and the version that was in CVS on the specific date.

As a final example, you can check the changes that have been made to one file using the same sort of commands as these (assuming that you have first remembered to issued an "srtpath" command first):

    > cd ana30/BetaMinuUser
    > cvs diff AppUserBuildBase.cc

Index: AppUserBuild.cc
===================================================================
RCS file: /afs/slac.stanford.edu/g/babar/repo/BetaMiniUser/AppUserBuild.cc,v
retrieving revision 1.47
diff -r1.47 AppUserBuild.cc
16a17
> //      Sheila Mclachlin                (workbook modifications)
34a36,37
> #include "BetaMiniUser/NTrkExample.hh"
>
40a44,47
>
>   // NTrkExample Module
>   add ( new NTrkExample( "NTrkExample", "Workbook example module"));
>

This shows the changes we made to the file AppUserBuildBase.cc in the Workbook QuickTour (these changes were made when you copied across the files from the /workbook/NewExamples/NTrkExample directory. Since no version was specified in this example, the differences are between the copy of AppUserBuildBase.cc you have in your BetaMiniUser directory at this moment and the copy of AppUserBuildBase.cc that is associated with release analysis-30 (which is the version you checked out from CVS).

Related documents:

Updating private copies of a package

The basic command to update a package is (from the package directory):


You will want to use this command twice: once with the -n option, and once without.

The first time you use cvs update, you should use the [-n] option to find out what the update command will do:

cvs -n update <package name>
With the -n option, cvs does NOT change any files. Instead, it tells you what it WOULD do if you issued the command without the -n option.

If you have a tagged version of a module checked out, the default update action will only look for changes to the tagged version and will not bring your code completely up to date. This is generally not what is required (in BaBar we do not allow changes to a version after it has been tagged). An important variation of update is, therefore,

cvs update -A <package name>

This update command will bring your code up to date with the head version in CVS, whatever version you originally checked out.

So, before updating, you should first do:

cvs -n update <package name> -A

If there are no conflicts, you can then update your private copy of a package with

cvs update  <package name> -A

An update brings users private copies up to date with recent changes. All files in the module are listed during an update, preceded by a letter indicating whether the files have been updated(U) or modified(M) by the user. If any files modified by the user have also been modified by others, these files are flagged and both sets of changes are incorporated into the users code. Note this difference from the cvs diff command. The -n command-line option causes cvs update to report what changes it would do, without actually performing them. It is best to use this option first and then only when the proposed changes are acceptable issue the cvs update command to actually execute the changes.

Updating to a more recent release

When you create your test release with newrel you specify the base release upon which it is based. This release is then used in the search path for include files, libraries and binaries. At some point you may wish to base your work on a more recent release, to take advantage of developments in packages without the need to addpkg them and compile your own libraries. This can be done with the updrel command from your release directory. The updrel command will bring a test release up to date with a new release number.

Syntax:

updrel <new release>

Where <new release> is the name of the release that you wish to update to. updrel updates all CVS checked-out directories created by addpkg, updates all links if this folder was created by GNUmakefile, and cleans up bin/lib/tmp.

Beware that this means that all the individual packages that you have checked out will be "updated" to the tags associated with your new release - even if the current tags you have checked out are newer than those tags from the new release! For this reason, you might sometimes want to check out a new test release and add updated package to that one rather than try to update an existing release.

If you want to Update an Already Checked-Out Package

In general, you will be working with versions of packages which have been thoroughly tested in the specific release you are using. You will have seen from the Quicktour that specific "tags" are checked out from the CVS repository when you issue an "addpkg" command. Using older or newer tags than those recommended for the specific release may cause problems as files are occasionally moved around between BaBar packages, or renamed or even deleted. As such, you should be aware that changing versions of checked-out packages can be hazardous.

Exceptions to the above warning are packages that are not linked to any release, for example, the GoodRuns package which lists all the data that has been classified as "good" and useable for analyses. This package is updated far too frequently to have individual tags associated with specific releases, and if you are using GoodRuns, then you should probably update frequently.

Before restarting work in your release directory you should always verify that the packages you have checked out are still current. This is just a matter of reissuing the addpkg command.

If you addpkg a package which already exists in your release, then after confirming with you, addpkg will update the package directory to the version appropriate for the release and will then check that the required links (in the include directory) are present.


Conclusions

So far only modifications and updates with respect to the user's personal copies (private release) have been discussed. Commiting your changes to the repository is a somewhat serious venture and is thus postponed to a much later section in the workbook. These steps should only be taken by individuals with sufficient experience and with the consent of coordinators.

See the advanced SRT workbook section SRT and CVS for more information about changing packages and committing your own new code.


More about tags

You can find the tagset (i.e. the list of tags for included packages) of a given release in

$BFDIST/releases/log/<release>/LatestPackageVersion-<release>.lst.gz

(For some lettered releases - releases where the release number is followed by a letter - the tag list is not gzipped.)

An example of how to view the entire tagset for a given release is, therefore (for release analysis-30 - for which you must enter the full release number, in this case 18.6.2a):

   cd $BFDIST/releases/log/18.6.2a/
   cp LatestPackageVersion-18.6.2a.lst.gz ~/
   cd ~
   gunzip LatestPackageVersion-18.6.2a.lst.gz
   less LatestPackageVersion-18.6.2a.lst
These commands copy the gzipped tagset list into your home directory ("~"), then change into your home directory, unzip and inspect the tagset list.

Part of that list is:

Reading package information from: /afs/slac.stanford.edu/g/babar/dist/releases/
18.6.2a         [l-12]
 Package              packages       releases
 AbsBTagging          V00-04-00      V00-04-00     ( 13)
 AbsCalo              V00-06-02      V00-06-02     ( 10)
 AbsEnv               V00-07-00      V00-07-00     ( 31)
 AbsEvent             V01-03-00      V01-03-00     ( 20)
 AbsEventTag          V00-00-12      V00-00-12     (  9)
 AbsParm              V00-08-06      V00-08-06     ( 20)
 AbsPid               V00-06-00      V00-06-00     ( 32)
 AckMon               V01-00-00                    (  0) 
 <<<< No Files  <<<< Old file (988)
 AdminScripts         V00-00-05      V00-00-05     (  8)
 AfkQed               V00-01-01      V00-01-01     ( 41)
If you want to know which tag is in a release for a specific package, you can type
srtlstag <release> <package>
This command needs to be used after entering srtpath from one of your release directories. For example, following the analysis in the quicktour:
cd ana30
srtpath <enter> <enter>
srtlstag 12.3.1 workdir
You should see:
workdir V00-04-10 12.3.1
This means that the workdir tag for release 12.3.1 is V00-04-10. This is different from your workdir tag V00-04-20, which is the one that belongs to analysis-30. Note that in the above example, the srtlstag command gives the tag number of the workdir package for the release numbered 12.3.1 - the purpose of changing into a release directory and entering the srtpath command first was simply to be able to access the Software Release Tools toolkit.

Finally, to check out a specific tag of a package (i.e. not the one that comes by default with the release you are working with), you use the addpkg command followed the name of the package and then the tag you want, for example:

addpkg PackageName V00-01-23
You can also use -h to check out the most recent version (the "head" of the CVS repository) of (for example) the HOWTO package:
addpkg -h HOWTO

General related documents:

Back to Workbook Front Page

Author: Tracey Marsh
Contributors:
John Bartelt, Neil Geddes,  Joseph Perl, Leon Rochester
Jenny Williams

Last modification: 19 January 2005
Last significant update: 9 September 2005