Software Release Tool Summary
Please send suggestions for additions, mods to T. Wenaus wenaus@llnl.gov
The text and this update line were last updated 4/1/96 by T. Wenaus
Current archive location:
-------------------------
$BFROOT/dist/releases/current/
Specific releases in eg. $BFROOT/dist/releases/0.8.1
Environment variables:
----------------------
$BFDIST = $BFROOT/dist
$BFARCH = (at present) "OSF1V3", "HP-UXA", AIX2", "SunOS5" (Solaris),
"SunOS4"
$BFCURRENT = current or, if it exists, the content of ~/BFCURRENT,
eg. to make one 'echo 0.8.1 > ~/BFCURRENT'
$BFCURRENT is the release used to find pieces (libs, includes, bins) not in
a test release. It will be overridden during gmake by whatever release was
used as the first argument to the newrel command.
NOTE the BFCURRENT gotcha below.
Variables needed for importing at remote sites:
-----------------------------------------------
$BFDISTr = `whoami`@unixhub.slac.stanford.edu:/nfs/juno/u5/dist
$CVSROOTr = `whoami`@unixhub.slac.stanford.edu:/nfs/juno/u5/repo:$BFROOT/repo
Use of unixhub (a Sun) rather than an IBM is recommended. Bizarre tar
errors occur sporadically when using IBMs.
You must configure a ~/.rhosts file in your SLAC account containing the
name of your home machine, and a ~/.rhosts file on your home machine
containing 'unixhub.slac.stanford.edu'. The protections on these files
have to be set 'chmod og-rwx ~/.rhosts'
Path additions (prepended to path):
-----------------------------------
./bin/$BFARCH
$BFDIST/releases/$BFCURRENT/bin/$BFARCH
BEWARE of these! Note that they go on the FRONT of your path.
Also if you are trying to run something that should be in
./bin/$BFARCH but is not, it will be pulled from
$BFDIST/releases/$BFCURRENT/bin/$BFARCH, and won't reflect
any personal mods you've made to the program. It could even
be the wrong version if $BFCURRENT is different from the
version you specified with 'newrel'.
Man page path addition:
-----------------------
$BFDIST/releases/$BFCURRENT/man
Login script:
-------------
SRTstartup.csh, .sh from $BFROOT/dist/releases/current/SoftRelTools
Directories searched for #included files: (in order)
-----------------------------------------
tmp/$BFARCH
$BFDIST/releases/$BFCURRENT/tmp/$BFARCH
include (addpkg creates a link 'packagename' in this dir)
$BFDIST/releases/$BFCURRENT/include
Include statements should be of form: #include "packagename/file.h".
The 'addpkg' command creates a link include/packagename to the first
of the following it finds in a package directory:
A subdirectory with the same name as the package
A subdirectory named "include"
A subdirectory named "src"
The package directory itself
Key Commands:
newrel -t current {pick-a-name}
Create your own (empty) release system directory pick-a-name
-t: generate empty test release in user's directory
-p: generate production release. Issue only from $BFDIST/releases.
Requires a base release number as a parameter, to use as a model.
addpkg {package name} [{version}]
Add package (eg. gnbase) to your release directory. Issue from your
release directory. Optionally, package version can be specified.
Also does a 'gmake installdirs' to set up dirs for the package.
-R: passed to CVS to control RCVS. Needed at remote sites.
-h: get the most recent version (from the Head of the repository)
gmake
Set up directories and build it all.
gmake cold
Restart from scratch in a self-consistent way, eg. packages (dbio, dbin)
needed to build other packages are done first. Used for 'get me out of
this mess' situations.
gmake installdirs
Set up directories. You may choose to precede with 'rm -rf bin lib'
to start clean. This command is now built in to 'gmake' and 'addpkg'
and so will rarely be needed directly.
Key USER Procedures:
Create personal release directory bbsoft, obtain package gnbase, run bbsim
newrel -t 0.8.1 bbsoft
cd bbsoft
addpkg gnbase
gmake installdirs
gmake (gmake MODE=INTERACTIVE for interactive)
bbsimb (the runtime db file used is gnbase/runtime.db and the FFREAD
card deck used is gnbase/dat/ftn01)
bbsim (interactive rather than batch)
Select interactive (batch is default)
'MODE := INTERACTIVE' in gnbase/GNUmakefile
then 'gmake gnbase.bin'
or 'gmake gnbase.bin MODE=INTERACTIVE'
Select subsystems
edit gnbase/src/Flags.h
Add the latest version of a package and build it fully
addpkg -h pkgname
gmake pkgname.all
Run with personal mods to database parameters
./bbsimb.exe runtime.db
where runtime.db contains only the parameters you want to change, eg.
database bbgeom 0100
structure dbio
int write 1
char xdrfile "myoutput.xdr"
end structure
end
Add library material to your compiles, links
-I$(BFDIST)/releases/$(BFCURRENT)/include in compilation
-L$(BFDIST)/releases/$(BFCURRENT)/lib/$(BFARCH) in link
Make your own package
mkdir pkgname issue from the release directory
cp mycode pkgname/ install your code
Set up makefile; see prototype
$BFDIST/releases/current/SoftRelTools/GNUmakefile.example
addpkg pkgname to make gmake search your directory for includes,
if needed
Get it all working (gmake installdirs ; gmake)
Install it in cvs
'cvs import pkgname import1 original' issued from package dir
'cvs tag V00-00-00' issued from package dir
-R if you are remote
Rebuild database includes and code after modifying structure of a .db file
touch gnbase/*.db
gmake gnbase.include
gmake gnbase.lib
gmake gnbase.bin
OR simply gmake gnbase.all
Compile for the debugger (or set other compiler options)
setenv CCFLAGS -g (for C code)
setenv CXXFLAGS -g (for C++ code)
setenv FCFLAGS -g (for Fortran code)
setenv F90CFLAGS -g (for Fortran 90)
setenv CPPFLAGS [whatever] (for C preprocessor)
Or for any of these 'gmake [...] xxxFLAGS=-g'
The standard f77bb line used within SRT makefiles is
f77bb -f77 "$(FCFLAGS)" -cpp "-I [...] $(CPPFLAGS)" $(F77BBOPT) name.F
Select the compiler
setenv CC cc (or gcc or your choice) C compiler
setenv CXX cxx (or CC or G++ etc.) C++ compiler
setenv FC f77 (or xlf etc.) Fortran compiler
Standard link options:
This is the link command line used by package makefiles (C++ example):
$(CXX) files $(CXXFLAGS) $(CPPFLAGS) $(LDFLAGS) -o $@ $(LOADLIBES)
(Note: This line is often overridden in specific packages. The options and
order are supposed to stay the same, but don't always. If you have trouble
getting an option changed, read the package GNUmakefile and look for the
link command line.)
Run the make with tons of output for debugging
gmake [params] VERBOSE=yes
Key MANAGEMENT Procedures:
Import a release from SLAC
importrel -p -a 0.8.1 Command can be issued from anywhere. Installs to
$BFDIST/releases. Note the environment variables
you need to have defined, above (CVSROOTr, BFDISTr)
-a means import only the platform-independent part
(follow with importarch)
importarch -p 0.8.1 $BFARCH import platform-dependent part
Tag a new package version and install in 'packages' area
cvs tag Vxx-xx-xx issued from a directory containing the package in
exactly the form you want to tag it (ie. normally
'cvs update -A' issued; current with archive)
cd $BFDIST/packages/packagename go to packages area
newver -p Vxx-xx-xx create the package version
The 'newver' step is done by the release coordinator, Hwanbae Park.
List the existing tags on a package
listtag packagename Issue at SLAC (unless you have it locally). Listtag
is a very useful script written by T. Hung.
Remove an unwanted version from the packages area
rmver -p packagename Vxx-xx-xx (release coordinator only, normally)
Check the tag and CVS revision status of all packages in a given
release
statusrel -c -p 0.8.1
Gotchas:
- Be sure you obtain packages with 'addpkg' and not 'cvs co'. If you
do the latter out of habit, you'll have trouble (eg. the make
procedure unable to find the package include files). To recover from
having used 'cvs co', just use addpkg, even though the directory
already exists.
- If you find yourself unable to do a commit on a package file because
of a sticky bit error ('sticky tag not a branch'), do 'cvs update -A'
first. '-A' resets any sticky tags.
- If you encounter gmake attempting compilation with a bad rule, eg.
compiling with f77bb and passing -I options not encapsulated in
-cpp "-I...", this may be due to 'bad craziness in the .d file'.
Delete the file tmp/$BFARCH/package/name.d and try again. I have
not seen this problem in some time, happily.
- if you are getting 'can't find include file' errors when trying to
compile a package, the reason is often bad .d files. Do
'rm tmp/$BFARCH/package/*.d ; gmake package.include' and try again.
Other possibilities:
- you're not in your release directory (created by newrel)
- there's no link in include/ for the package, in which case do 'addpkg name'
- the included file in the code is not in the form #include "package/file.h"
ie. be sure to include the 'package/' prefix
- the includes are kept in a place where addpkg can't find them (see addpkg
search procedure above)
- If you change BFCURRENT by editing the file $HOME/BFCURRENT (the only sure
way to change it), then you must rerun SRTstartup.sh, otherwise the PATH
and MANPATH are wrong. (D. Wright)
- Be aware that the version of SRT commands that you are using is
determined entirely by BFCURRENT which is 'current' unless you have a
~/BFCURRENT file. Thus if you make a 0.8.1 area with newrel, but
'current' is still 0.6.2, when you use SRT commands such as 'addpkg'
in your new area, you will be using the old 0.6.2 version. To pick up
a version associated with 0.8.1, you either have to set ~/BFCURRENT
or do 'addpkg SoftRelTools ; gmake SoftRelTools.bin'.
- Another gotcha along the lines of the last one, but more sinister: if
you make a 0.8.1 area, the GNUmakefile installed in the area by newrel
is from the version given by BFCURRENT, NOT necessarily 0.8.1. ie. It
gives you an old makefile to build the new version. This is a bug.
- CONCLUSION from the previous two gotchas: HAVING A ~/BFCURRENT FILE
THAT MATCHES THE VERSION SPECIFIED IN YOUR newrel IS A REALLY GOOD
IDEA. (Be sure you log out and log in again after changing ~/BFCURRENT.)
- BE SURE YOUR LOGIN SCRIPTS DO NOT PRINT STUFF TO THE SCREEN. This can
cause rCVS (used by addpkg) to fail, often with a 'mismatched version
numbers' error. Recommendation: move to the newest CVS that does not
use rCVS.
Key Packages (simulation bias):
gnbase bbsim base package, needed to run bbsim
gnbbg bbsim module containing framework code and Geant
hook routines (eg. gustep)
Aslund Aslund fast simulation
workdir package to run bbsim and Aslund
SoftRelTools the release system itself
|
