Commands at the left margin are necessary. Indented lines are suggestions so that you can see what's going on at each stage to better understand what's happening.
In this example I am going to work on the D0 package trfutil. I want to link an executable that's in trftest to test my changes. trftest contains code that #include's trfutil headers. I won't be changing any code in trftest.
Since I'm doing active development, I'll setup the "test" version of D0RunII and will use that version as my "base". I'll also be working on the "head", or latest version of trfutil that's currently in cvs.
<d0chb> setup d0cvs
<d0chb> setup D0RunII test
<d0chb> ls $BFDIST/releases/$BFCURRENT/SoftRelTools/
<d0chb> mkdir workdir
<d0chb> cd workdir
<d0chb> man newrel
<d0chb> newrel -t mytest
<d0chb> newrel -t test mytest
<d0chb> ls -R
<d0chb> cd mytest
<d0chb> man addpkg
<d0chb> addpkg -h trfutil **** NOTE ****
<d0chb>depend trfutil
<d0chb> man lnkpkg
<d0chb> lnkpkg trftest
lnkpkg doesn't work with the KAI compiler at the moment, must use
addpkg.
<d0chb> ls -la
<d0chb> cat .current
<d0chb> cat .experiment
<d0chb> ls trfutil/
<d0chb> ls trfutil/CVS
<d0chb> cat trfutil/CVS/Repository
<d0chb> cat trfutil/CVS/Root
<d0chb> ls -l include/
<d0chb> gmake
<d0chb> ls lib/IRIX5-KCC/
<d0chb> ls bin/IRIX5-KCC/
<d0chb> ls tmp/IRIX5-KCC/*
<d0chb> cd trfutil/
<d0chb> emacs RecoTest.cc &
<d0chb> cd ..
<d0chb> gmake
<d0chb> cvs -n update -dA
<d0chb> cvs diff
<d0chb> cvs update -dA
<d0chb> cvs commit -m "Testing, negligable change"
*** <d0chb> cvs release -d trfutil
*** <d0chb> cd ..
*** <d0chb> rm -r mytest
<d0chb> cvs -H
<d0chb> cvs --help-commands
<d0chb> cvs add -H
<d0chb> cvs commit -H
<d0chb> cvs history -H
<d0chb> cvs rtag -H
<d0chb> cvs tag -H
<d0chb> cvs diff -H
<d0chb> cvs log -H
NOTE: and this is important, if you don't start over everytime. CVS and
SoftRelTools are both "sticky". That is they remember the versions of modules,
packages and releases being used. The setup D0RunII above
determines the version of SoftRelTools used in this build and the
value of any package environment variables used when running your executable.
It does not determine the versions of the code you link
against within gmake. That's determined by the
base release specified in the newrel command.
-setup d0cvs and D0RunII development version:
<d0chb> setup d0cvs
<d0chb> setup D0RunII test
****setup D0RunII test NULL
** using architecture/compiler combo IRIX5-KCC **
PYTHONPATH is /d0usr/products/python/v01_04/lib/python1.4:/d0usr/products/python/v01_04/lib/python1.4/tkinter
-create a clean directory in which to work and cd into it:
<d0chb> mkdir workdir
<d0chb> cd workdir
/home/jonckheere/example/workdir
-I've forgotten the command to use, so:
<d0chb> ls $BFDIST/releases/$BFCURRENT/SoftRelTools/
GNUmakefile arch_spec_Inventor.mk importrelonly
GNUmakefile.example arch_spec_RW.mk importver
GNUmakefile.link arch_spec_Tcl.mk importver.1
GNUmakefile.link_ana arch_spec_X11.mk init_cdfsoft2.csh
GNUmakefile.main arch_spec_XDR.mk lnkpkg
PORTING arch_spec_cern.mk lnkpkg.1
README arch_spec_f77.mk makeDist.sh
SRTcheck arch_spec_fortmain.mk makeReleaseList
SRTdepend arch_spec_geant.mk newrel
SRTfilt arch_spec_ocs.mk newrel.1
SRTpath.1 auditrel newver
SRTpath.csh auditrel.1 newver.1
SRTpath1.1 auditver rmrel
SRTpath1.csh auditver.1 rmrel.1
SRTpath2.1 depend rmver
SRTpath2.csh depend.1 rmver.1
SRTstartup.1 dependson setup.sh
SRTstartup.csh f77bb standard.mk
SRTstartup.sh fix_gnbase statusrel
SoftRelToolIntro.ps fix_gnbase.1 statusrel.1
SoftRelToolUser.ps freezerel stdlinking.mk
TODO freezerel.1 unsetup.sh
addpkg importarch ups_files
addpkg.1 importarch.1 vms2f90
arch_spec.mk importrel
arch_spec_CERNLIB.mk importrel.1
-Ah! it's newrel, but I don't remember the syntax:
<d0chb> man newrel
. . .
SYNOPSIS
newrel [-t|-p] <base release> [<new release>]
. . .
-OK, let's do it:
<d0chb> newrel -t mytest
Two arguments required; found 1
-Whups: forgot an argument
<d0chb> newrel -t test mytest
next, add pkg, checkout or ln -s to your packages, then gmake installdirs
-Let's see what newrel actually did:
<d0chb> ls -R
mytest
./mytest:
GNUmakefile doc include man tmp
bin ide lib results ups
./mytest/bin:
./mytest/doc:
./mytest/ide:
./mytest/include:
./mytest/lib:
./mytest/man:
man1
./mytest/man/man1:
./mytest/results:
./mytest/tmp:
./mytest/ups:
-Ah: It built an empty "release" tree.
-so cd into the top of the tree and add my package, but I don't
-remember the syntax. It's been awhile since I've done this.
<d0chb> cd mytest
/home/jonckheere/example/work/mytest
<d0chb> man addpkg
. . .
SYNOPSIS
addpkg [-h] <package name> [<version string>]
. . .
-add the "head" version (-h) of trfutil:
<d0chb> addpkg -h trfutil
Taking trfutil from head of CVS main branch
cvs server: Updating trfutil
U trfutil/BINARIES
U trfutil/COMPONENTS
U trfutil/EventID.cpp
U trfutil/EventID.h
. . .
cvs server: Updating trfutil/doc
U trfutil/doc/index.html
U trfutil/doc/trfutil_class.ps
U trfutil/doc/trfutil_physical.ps
cvs server: Updating trfutil/ups
U trfutil/ups/setup.csh
U trfutil/ups/setup.sh
U trfutil/ups/unsetup.csh
U trfutil/ups/unsetup.sh
This release based on t00.01.00, overriding BFCURRENT value of test
Cannot access bin/*/*: No such file or directory
Cannot access lib/*/*: No such file or directory
-don't worry about those access errors. You'll always get those. The comment
-about overriding BFCURRENT will only occur if my "setup D0RunII" and the
-"base release" don't agree. In this example I wouldn't actually have gotten
-that message since they do agree.
-ok: now I need to determine what packages depend on my package:
<d0chb> depend trfutil
No release specified; will check release test.
These packages in release test use include files from package trfutil:
trfbase trfcyl trffind trffit trfplane trftest
-Hum, at lot of them. But, since I know what I'm doing and I'm
-only going to be linking code in trftest, I'll only do that one.
-So:
<d0chb> lnkpkg trftest
Release test uses trftest version v00-40-00, will link to this version.
lnkpkg doesn't work with the KAI compiler at the moment, must use
addpkg.
-let's see what we have now:
<d0chb> ls -la
drwxr-xr-x 12 jonckhee D0 512 Jan 19 12:20 .
drwxr-xr-x 3 jonckhee D0 512 Jan 19 12:11 ..
-rw-r--r-- 1 jonckhee D0 5 Jan 19 12:11 .current
-r--r--r-- 1 jonckhee D0 3 Jan 19 12:11 .experiment
-r--r--r-- 1 jonckhee D0 12077 Jan 19 12:11 GNUmakefile
drwxr-xr-x 3 jonckhee D0 512 Jan 19 12:17 bin
drwxr-xr-x 2 jonckhee D0 512 Jan 19 12:11 doc
drwxr-xr-x 2 jonckhee D0 512 Jan 19 12:11 ide
drwxr-xr-x 2 jonckhee D0 512 Jan 19 12:20 include
drwxr-xr-x 3 jonckhee D0 512 Jan 19 12:17 lib
drwxr-xr-x 3 jonckhee D0 512 Jan 19 12:11 man
drwxr-xr-x 2 jonckhee D0 512 Jan 19 12:11 results
drwxr-xr-x 3 jonckhee D0 512 Jan 19 12:17 tmp
lrwxr-xr-x 1 jonckhee D0 39 Jan 19 12:21 trftest ->
/d0dist/dist/packages/trftest/v00-40-00
drwxr-xr-x 5 jonckhee D0 1536 Jan 19 12:20 trfutil
drwxr-xr-x 2 jonckhee D0 512 Jan 19 12:11 ups
-What are these hidden files:
<d0chb> cat .current
test
<d0chb> cat .experiment
D0
-Oh! my "base release" and experment.
-What's in trfutil, especially the CVS directory?
<d0chb> ls -F trfutil/
BINARIES RandomRegistry_t.cpp Tuple.h
COMPONENTS RootFindLinear.cpp TupleManager.cpp
CVS/ RootFindLinear.h TupleManager.h
EventID.cpp RootFindLinear_t.cpp TupleManager_t.cpp
EventID.h RootFinder.cpp Tuple_fwd.h
EventID_t.cpp RootFinder.h VERSION
GNUmakefile RootFinder_t.cpp array.c
...
RandomRegistry.cpp TRFMath.h ups/
RandomRegistry.h TRFMath_t.cpp
-trf* have a rather "flat" directory structure. They don't have src/
nor "header" directories. The latter is, by convention, named the same
as the package, ie) it would be "trfutil" in this case.
<d0chb> ls trfutil/CVS
Entries Entries.Log Repository Root
<d0chb> cat trfutil/CVS/Repository
/cvsroot/d0cvs/trfutil
<d0chb> cat trfutil/CVS/Root
cvsuser@d0chb.fnal.gov:/cvsroot/d0cvs
-CVS/Repository and ROOT record where I got trfutil
-Other files might exist depending on what tagged version you used.
<d0chb> ls -l include
total 2
lrwxr-xr-x 1 jonckhee D0 39 Jan 19 12:32 trftest -> /d0dist/dist/packages/trftest/v00-40-00
lrwxr-xr-x 1 jonckhee D0 10 Jan 19 12:20 trfutil -> ../trfutil
-- trftest include directory points to the distribution area, while
-- trfutil points to my copy of it.
-In the following I've replaced:
-/d0chb/home/room2/jonckheere/example/work -> ... for brevity.
<d0chb> gmake
This release based on test, overriding BFCURRENT value of t00.01.00
-agian I wouldn't really get the above because my setup D0RunII and
-my base release agree.
-gmake first builds the dependency (.d) files for trftest
-This is done using cpp
Making .../mytest/tmp/IRIX5-KCC//trftest/SFPathBuilder.d
Making .../mytest/tmp/IRIX5-KCC//trftest/SFLayerManager.d
Making .../mytest/tmp/IRIX5-KCC//trftest/TrackMatch.d
. . .
Making .../mytest/tmp/IRIX5-KCC//trfutil/RootFindLinear.d
Making .../mytest/tmp/IRIX5-KCC//trfutil/Match.d
Making .../mytest/tmp/IRIX5-KCC//trfutil/SpacePath.d
. . .
-then it compiles the source code and puts it into an archive
Compiling RandomSeed.cpp
a - .../mytest/tmp/IRIX5-KCC//trftest/RandomSeed.o
s - creating archive symbol table. Wait...
s - done
Compiling MCTrackMaker.cpp
C++ prelinker: DPtr<T1> &DPtr<T1>::operator =(const DPtr<T1> &) [with T1=VTrackGenerator] assigned to file .../mytest/tmp/IRIX5-KCC//trftest/MCTrackMaker.o
C++ prelinker: DPtr<T1>::DPtr<VTrackGenerator>(T1 *) [with T1=VTrackGenerator] assigned to file .../mytest/tmp/IRIX5-KCC//trftest/MCTrackMaker.o
. . .
s - creating archive symbol table. Wait...
s - done
lib stage done in /d0chb/home/room2/jonckheere/workdir/mytest/trftest
-a lot of output is due to template instantiation.
-done with the lib stage of trftest, begin working on trfutil
Compiling array.cpp
a - /d0chb/home/room2/jonckheere/workdir/mytest/tmp/IRIX5-KCC//trfutil/array.o
s - creating archive symbol table. Wait...
s - done
Compiling SpacePoint.cpp
a - /d0chb/home/room2/jonckheere/workdir/mytest/tmp/IRIX5-KCC//trfutil/SpacePoint.o
s - creating archive symbol table. Wait...
s - done
. . .
lib stage done in /d0chb/home/room2/jonckheere/workdir/mytest/trfutil
-- NOTE the following isn't real, it's just for illustration, but...
-- at some point you are likely to see something like:
Compiling AlgTests.cpp
AlgTests.cc:1: iostream: No such file or directory
gmake[4]: *** [.../mytest/lib/IRIX5//libtrfutil.a(AlgTests.o)] Error 1
gmake[3]: *** [src.lib] Error 2
gmake[2]: *** [trfutil.lib] Error 2
gmake[1]: *** [lib] Error 2
gmake: *** [all] Error 2
-Whoops can't find iostream. It should be iostream.h!
-Fix it and try again. Fix the next and the next etc.
-Eventually I get it "right". It then makes it through the lib and bin stages
-of both packages. For the trf packages I can now do:
<d0chb> gmake test
-- to test the components of the packages.
-- keep iterating until you get it right. Anything that built "correctly" won't need
-- to be recompiled.
I now have:
<d0chb> ls lib/IRIX5-KCC/
ii_files libtrftest.a libtrfutil.a
<d0chb> ls bin/IRIX5-KCC/
findcyl fitcyl ii_files
<d0chb> ls -R tmp/IRIX5-KCC/*
tmp/IRIX5-KCC/trftest:
CylTrackNtuple.d
KCC_files
MCTrackMaker.d
RandomSeed.d
SFLayerManager.d
SFPathBuilder.d
TrackMatch.d
findcyl.o
fitcyl.o
ii_files
-- The *.d files are the "dependency" files created by the cpp preprocessor.
-- They are makefile fragments that detail the dependence on include files.
tmp/IRIX5-KCC/trftest/KCC_files:
07YhlKJt6EMsFi.c
07YhlKJt6EMsFi.o
0MlGQBIYsIpDUN.c
0MlGQBIYsIpDUN.o
. . .
LnpjiYtooPUIM6.c
LnpjiYtooPUIM6.o
MCTrackMaker.c
MCTrackMaker.h
MCTrackMaker.k
MCTrackMaker.o
MJ2p6pKTjzg7wa.c
MJ2p6pKTjzg7wa.o
. . .
zHuDjZZoYJJjv7.o
zogcAkKaAkU55i.c
zogcAkKaAkU55i.o
-- these are present in this directory only for trf++ (I think).
tmp/IRIX5-KCC/trftest/ii_files:
CylTrackNtuple.ii
MCTrackMaker.ii
RandomSeed.ii
SFLayerManager.ii
SFPathBuilder.ii
TrackMatch.ii
findcyl.ii
fitcyl.ii
-- these are created by the Kai compiler during template instantiation.
tmp/IRIX5-KCC/trfutil:
EventID.d
InvalidQuality.d
KCC_files
Match.d
Quality.d
RandomGenerator.d
RandomRegistry.d
RootFindLinear.d
RootFinder.d
SimpleQuality.d
SpacePath.d
SpacePoint.d
SpaceVector.d
StatusValue.d
TRFMath.d
TupleManager.d
array.d
ii_files
matrix.d
nvector.d
smatrix.d
tmp/IRIX5-KCC/trfutil/KCC_files:
07YhlKJt6EMsFi.c
07YhlKJt6EMsFi.o
. . .
zogcAkKaAkU55i.c
zogcAkKaAkU55i.o
tmp/IRIX5-KCC/trfutil/ii_files:
Match.ii
RandomGenerator.ii
RandomRegistry.ii
RootFindLinear.ii
RootFinder.ii
SpacePath.ii
SpacePoint.ii
SpaceVector.ii
StatusValue.ii
TupleManager.ii
smatrix.ii
-I now check if anyone else has updated any of these files while I was
-messing around trying to get them to work.
<d0chb> cvs -n update
? trfutil/d0vector.hh
cvs server: Updating .
cvs server: Updating trfutil
M trfutil/src/AlgTests.cpp
cvs server: Updating trfutil/doc
cvs server: Updating trfutil/ups
-The "?" means that I've created a new file. The "M" means that I've modified
-the file but haven't commited it yet.
-Just to be sure of what changes I've made:
<d0chb> cvs diff
? trfutil/trfutil/d0vector.hh
cvs server: Diffing .
cvs server: Diffing trfutil
Index: trfutil/AlgTests.cpp
===================================================================
RCS file: /cvsroot/d0cvs/trfutil/src/AlgTests.cc,v
retrieving revision 1.8
diff -r1.8 AlgTests.cc
1c1
< #include <iostream>
---
> #include <iostream.h>
cvs server: Diffing trfutil/doc
cvs server: Diffing trfutil/ups
-OK, that's mine. Now we need to "add" the new routine to cvs:
<d0chb> cvs add d0vector.hh
cvs server: scheduling file `d0vector.hh' for addition
cvs server: use 'cvs commit' to add this file permanently
-I could have used wildcards here, but didn't need to.
-now we need to commit the changes. If someone else had modified anything,
-cvs would require us to reconcile the differences by doing a "cvs update".
-So I might as well do it anyway.
<d0chb> cvs update
cvs server: Updating .
cvs server: Updating trfutil
A trfutil/trfutil/d0vector.hh
M trfutil/src/AlgTests.cc
cvs server: Updating trfutil/doc
cvs server: Updating trfutil/ups
-So I have the "A"dded and the "M"odified file, and noone else has done anything.
<d0chb> cvs commit -m "Put in a real comment here"
RCS file: /cvsroot/d0cvs/trfutil/d0vector.hh,v
done
Checking in trfutil/trfutil/d0vector.hh;
/cvsroot/d0cvs/trfutil/d0vector.hh,v ------ d0vector.hh
initial revision: 1.1
done
Checking in trfutil/AlgTests.cpp;
/cvsroot/d0cvs/trfutil/AlgTests.cc,v ------ AlgTests.cpp
new revision: 1.9; previous revision: 1.8
done
-I'm done. At this point I can just quit. Or I can "release" my working directory.
-The latter is safest, frees disk space etc, but means that I'll have to recompile
-everything again if I want to more work.
-I won't be working on this for a while, so I opt for that.
<d0chb> cd ..
/home/jonckheere/example/work/mytest
<d0chb> cvs release -d trfutil
You have [0] altered files in this repository.
Are you sure you want to release (and delete) module `trfutil': y
<d0chb> cd ..
/home/jonckheere/example/work
<d0chb> rm -rf mytest
-I'm done.
CVS
<d0chb> cvs -H
Usage: cvs [cvs-options] command [command-options] [files...]
Where 'cvs-options' are:
-H Displays Usage information for command
-Q Cause CVS to be really quiet.
-q Cause CVS to be somewhat quiet.
-r Make checked-out files read-only
-w Make checked-out files read-write (default)
-l Turn History logging off
-n Do not execute anything that will change the disk
-t Show trace of program execution -- Try with -n
-v CVS version and copyright
-b bindir Find RCS programs in 'bindir'
-e editor Use 'editor' for editing log information
-d CVS_root Overrides $CVSROOT as the root of the CVS tree
-f Do not use the ~/.cvsrc file
-z # Use 'gzip -#' for net traffic if possible.
-s VAR=VAL Set CVS user variable.
and where 'command' is: add, admin, etc. (use the --help-commands
option for a list of commands)
<d0chb> cvs --help-commands
CVS commands are:
add Adds a new file/directory to the repository
admin Administration front end for rcs
annotate Show revision where each line was modified
checkout Checkout sources for editing
commit Checks files into the repository
diff Runs diffs between revisions
edit Get ready to edit a watched file
editors See who is editing a watched file
history Shows status of files and users
import Import sources into CVS, using vendor branches
export Export sources from CVS, similar to checkout
log Prints out 'rlog' information for files
login Prompt for password for authenticating server.
rdiff 'patch' format diffs between releases
release Indicate that a Module is no longer in use
remove Removes an entry from the repository
status Status info on the revisions
tag Add a symbolic tag to checked out version of RCS file
unedit Undo an edit command
rtag Add a symbolic tag to the RCS file
update Brings work tree in sync with repository
watch Set watches
watchers See who is watching a file
<d0chb> cvs add -H
Usage: cvs add [-k rcs-kflag] [-m message] files...
-k Use "rcs-kflag" to add the file with the specified kflag.
-m Use "message" for the creation log.
<d0chb> cvs commit -H
Usage: cvs commit [-nRlf] [-m msg | -F logfile] [-r rev] files...
-n Do not run the module program (if any).
-R Process directories recursively.
-l Local directory only (not recursive).
-f Force the file to be committed; disables recursion.
-F file Read the log message from file.
-m msg Log message.
-r rev Commit to this branch or trunk revision.
<d0chb> cvs history -H
Usage: cvs history [-report] [-flags] [-options args] [files...]
Reports:
-T Produce report on all TAGs
-c Committed (Modified) files
-o Checked out modules
-m <module> Look for specified module (repeatable)
-x [TOFWUCGMAR] Extract by record type
Flags:
-a All users (Default is self)
-e Everything (same as -x, but all record types)
-l Last modified (committed or modified report)
-w Working directory must match
Options:
-D <date> Since date (Many formats)
-b <str> Back to record with str in module/file/repos field
-f <file> Specified file (same as command line) (repeatable)
-n <modulename> In module (repeatable)
-p <repos> In repository (repeatable)
-r <rev/tag> Since rev or tag (looks inside RCS files!)
-t <tag> Since tag record placed in history file (by anyone).
-u <user> For user name (repeatable)
-z <tz> Output for time zone <tz> (e.g. -z -0700)
<d0chb> cvs rtag -H
Usage: cvs rtag [-aflRnF] [-b] [-d] [-r tag|-D date] tag modules...
-a Clear tag from removed files that would not otherwise be tagged.
-f Force a head revision match if tag/date not found.
-l Local directory only, not recursive
-R Process directories recursively.
-n No execution of 'tag program'
-d Delete the given Tag.
-b Make the tag a "branch" tag, allowing concurrent development.
-[rD] Existing tag or Date.
-F Move tag if it already exists
<d0chb> cvs tag -H
Usage: cvs tag [-lRF] [-b] [-d] [-r tag|-D date] tag [files...]
-l Local directory only, not recursive.
-R Process directories recursively.
-d Delete the given Tag.
-[rD] Existing tag or date.
-f Force a head revision if tag etc not found.
-b Make the tag a "branch" tag, allowing concurrent development.
-F Move tag if it already exists
<d0chb> cvs diff -H
Usage: cvs diff [-lN] [rcsdiff-options]
[[-r rev1 | -D date1] [-r rev2 | -D date2]] [files...]
-l Local directory only, not recursive
-D d1 Diff revision for date against working file.
-D d2 Diff rev1/date1 against date2.
-N include diffs for added and removed files.
-r rev1 Diff revision for rev1 against working file.
-r rev2 Diff rev1/date1 against rev2.
<d0chb> cvs log -H
Usage: cvs log [-l] [rlog-options] [files...]
-l Local directory only, no recursion.