Next: GNUmakefiles and gmake Up: User's Guide to the
Previous: Background
Subsections
The software release system requires a few environment variables and entries in your PATH and MANPATH variables. If you are at SLAC and have set up your account to use the HEPiX scripts, this set-up is done automatically for
you; you don't need to use the procedures described below. See the B A B A R HEPiX web page:
/BFROOT/doc/Computing/www/Tools/HEPiX.html
You can check that the environment variables BFDIST, BFARCH, and BFCURRENT are set to something sensible. BFDIST is /afs/slac.stanford.edu/g/babar/dist at SLAC, forexample; the default for BFCURRENT is ``current''; and BFARCH will
depend on your operating system and compiler. Note that the implementation details of BFARCH were undergoing changes in Spring, 1998.
If you're not at SLAC or are not using the standard scripts to set up your environment, you should do the following. First, check that the environment variable $BFROOT is set; if it isn't, set it to: /afs/slac.stanford.edu/g/babar. Then,
depending on your shell, either say
[for csh or tcsh]:
source $BFROOT/dist/releases/current/SoftRelTools/SRTstartup.csh
[or for sh or ksh]:
. $BFROOT/dist/releases/current/SoftRelTools/SRTstartup.sh
You may want to put the appropriate command in your .login (or profile) file, so it is executed every time you log-in. If your network connection is poor, you can copy the appropriate file to your home directory and source it there, but you will
need to update this file if the SLAC version changes.
In addition to setting the necessary variables, the script extends your PATH to include ./bin/$BFARCH and $BFROOT/dist/releases/$BFCURRENT/bin/$BFARCH near the front. The ordering assures that your own release will override the
default B A B A R release. Similarly, MANPATH is extended to include ./man and $BFDIST/releases/$BFCURRENT/man.
These scripts define the environment variable $BFCURRENT to be ``current''. If you want to default to a release other than ``current'', create a file named BFCURRENT in your home directory. Put a single line in the file with the number of the release you
want to use as default. Then source the SRTstartup script again. Note that changing the value of $BFCURRENT may also effect which version of SRT you are using.
You can also select a particular release to work from (other than your default) when you create it, using an option described below.
If you have changed $BFCURRENT (by creating the file BFCURRENT) and want to go back to ``current'', do one of the following:
- 1.
- remove the file BFCURRENT from your home directory and log-in again; or
- 2.
- change the one line in BFCURRENT to ``current'' and source the SRTstartup script again; or
- 3.
- remove the file BFCURRENT, do unsetenv BFCURRENT and then source SRTstartup again.
Create a test release in your own directory tree: cd <some_directory>
newrel -t current <project_name>
The -t means this is a ``test release''. The next parameter specifies the base-release (here, ``current'') upon which your test release will be based. You can specify a different release here (e.g., ``5.2.2''). This will
not affect the version of SRT that you are using, unlike creating a BFCURRENT file to modify $BFCURRENT, as described above.
Finally, ``<project_name>'' is what this release will be named, and is also the subdirectory created in your current directory. Next, cd into the <project_name> directory and ``add'' the base bbsim
package:
cd <project_name>
addpkg gnbase
(See subsection 3.2.2 for more details about addpkg.) You will be told which version of the gnbase package is being checked out. The gnbase package contains
the input files and scripts required to run bbsim, plus man pages. The addpkg command has also done a gmake installdirs for you (some older documentation said you had to do this yourself).
Then just run bbsim:
bbsim
This will run the bbsim executable in $BFDIST. See the bbsim documentation for details on running it; for example
/BFROOT/www/Computing/Offline/Simulation/www/PhysSim.html
In particular, you may want to consider using the ``workdir'' package for running bbsim (this is now the recommended method):
addpkg workdir
cd workdir
gmake setup
and then use the bbrun script. (Alternatively, you could say gmake workdir.setup from the directory above workdir, but you will probably want to cd into workdir anyway, to do the bbrun.)
Note that ``addpkg'' has done a CVS check-out; never copy or move these files between directories or computers. If you do, and then at some point you commit them back to the repository, there is a very good chance you will screw up
the archive (other updates to the files may be lost and things will be very confused).
As before, do this: newrel -t current <project_name>
cd <project_name>
addpkg gnbase
[Note: if you want to make your own executable, you must use the gnbase package.] Then add the package you want to modify, specifying the version if necessary. For example, to change some EMC code, using the default version for this
release:
addpkg gnemca
By default, this gives you the version of gnemca appropriate for the release you are working in. Often, especially if you plan to modify the code, you will want the most recent (``head'') version of the pacakge. To get it, you would say
addpkg -h gnemca
or:
addpkg gnemca HEAD
The latter version is a new option, added to SoftRelTools after V00-06-19. To check out a specific version of the package, say:
addpkg gnemca V00-03-02
where you would substitute the version number you want for ``V00-03-02''. Then modify the code you want to change.
Another new (after V00-06-19) option for addpkg is the ability to read a list of packages and tags from a file. You can say
addpkg -f <tag-file>
where <tag-file> is the name of your file with package names and tags, one pair per line.
You can then edit the files in the packages you have checked out. To build the executable, make sure you are in the <project_name> directory. Then just say
gmake
which builds the executable, following the instructions in the GNUmakefile, including descending recursively into your package directories. See
/BFROOT/doc/www/SRThowtodoc.html
and GNUmakefile.example and GNUmakefile.multi-bins in SoftRelTools for more information on B A B A R's use of GNUmakefiles. The spec.mk file (load by GNUmakefile)
creates a .spec file which lists environment variables and such that are used in the make. It also runs the specver.pl script to get version information about the operating system, compiler, RogueWave, etc.
The packages in your personal area take precedence over the default packages for this test release, so your modifications will appear in the executable built in your area. To run your personal version, you still just say:
bbsim
The executable you just made has precedence over the default B A B A R executable (assuming your PATH has been set by the SRTstartup script, as described in section 3.1). Note, however, that if the make failed and no executable was created, when you say ``bbsim'', bbsim will still run: but it will be the standard version that's already in the B
A B A R release area--because that is still in your PATH. This won't have any of your modifcations, and could even be from a different release.
A reminder: do not move the files in the checked-out packages between directories.
When you created your test release with newrel you specified the release upon which it is based. This might have been ``current'' which either means the B A B A R current, or
whatever you have in your BFCURRENT file. Or you may have specified a particular release in the newrel command (i.e., 5.2.2). At some point you may want to update your work to a more recent release. This can be done easily with
the updrel command. With this command, you don't need to redo the addpkg commands, etc. The form is
updrel <new_release>
for example:
updrel 5.3.0
or for the very latest release:
updrel newest
The release labelled as ``newest'' may be substantially different from ``current''!
Once you have modified some code in a package, you may want your modifications to become part of the repository. Since the ``addpkg'' command did a CVS check-out, you can do this by using the CVS commit function.
Before doing this, you should always:
(1) Check that your changes actually work.
(2) Talk to the coordinator for the particular package.
In some cases, the package coordinator may have restricted who is allowed to commit changes to a particular package. Generally, you are expected to test your code by compiling it on at least two different supported platforms.
Before doing the ``commit'', you should bring your private version of the package up-to-date. Other users may have made modifications since you checked out the package. If you are not already in the pacakge directory, cd there (e.g.,
cd gnemca). Then by issuing the command
cvs diff <filename>
you will get a list of the differences between your version of the file and the version you originally checked out. (If you leave off the filename, CVS will ``diff'' all the files.) You can also compare your versions to a particular tagged version, by
specifiying the tag:
cvs diff -r <tag> <filename>
But what you really want to do (generally) is to compare your version to the head version in the CVS repository. Unfortunately, there seems to be a bug in CVS, so that the command cvs diff -r HEAD <filename> does not work
the way described in the CVS man page (it does the diff against the version you originally checked out, not the head). To get around this, do the following:
cvs log <filename> | grep head:
(this has to be in your checked out package directory). This command will return something like ``head: 1.4'', which tells you that the head version of this file is number 1.4. You can then use that CVS version number to do the diff:
cvs diff -r <version number> <filename>
You can use the ``cvs update'' command to bring your working version up to date. From your package working directory you would say:
cvs update -A
This will bring in new versions of the files in your working directory that you have not changed; it will merge the repository files with your changed files. It may be a good idea to retest at this point. The -A option is required to
bring the CVS tags associated with your copy of the package up to date. Otherwise, when you try to commit, you will get a message something like:
cvs commit: sticky tag 'HEAD' for file 'dswrite.F' is not a branch
If you get such a message, do the cvs update -A again. If you are in your release directory, you can specify the package to update by saying cvs update -A gnemca, for example.
If there have been changes to the package, it is up to you to resolve any conflicts with your modifications before committing. To commit your changes to the repository, from your package working directory, say:
cvs commit -m ``<comment on why and when>''
If you leave off the ``-m'' and comment, an editor window will be opened for your comment. The commit procedure may take some time for remote users. Please do not abort it once begun; that would leave the repository locked and cause big problems
for other users.
After you have committed your new version to the repository, you can use the Release Coordinator's Pacakage Test Page
http://www-hep.colorado.edu/reltest/PackageTestRequest.html
to have it compiled on all the supported platforms in the standard environment. (Note that this facility is sometimes not operational.)
  
Next: GNUmakefiles and gmake Up: User's Guide to the
Previous: Background
John Bartelt
3/23/1998
|
