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.)
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:
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.
 Special for RAL: Releases
 Special 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.
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.
Special for RAL: CVS
Related documents:
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.
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.
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.
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.
Special for RAL: Running at
both SLAC and RAL
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
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.
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.
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.
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:
- 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
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:
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.
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.
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.
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:
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
|
