From: R J Lechner Subject: Frequently-Asked Questions about building and testing bde Date: 97/4/10 (update of 1994 original) Ref: $PH/COOL-BDE/How2BuildBde_97s_faq.txt (was at, but know linked from, $CASE/95s523/95sbde/bde/how2buildbde.faq) Contents (as of 97/4/10): 1: Is there a common bde directory where casual users can try bde? 2: How often is the bde executable updated? 3: How can I build my own bde executables? 4: Where can I build bde to test my own updates? 5: How large is the bde executable? 6: When is it OK to check in updates with cvs and rebuild bde there? 7: How can you document bugs if bde crashes? 8: What if there isn't space in /usr/proj3/case... to build bde? ==================================================================== Question 1: Is there a common bde directory where casual users can try bde? Answer: Yes-and-No: The executable below is intended for casual users: /usr/proj3/case/95s523/95sbde/bde/executables/bde However, DO NOT cd there because you don't have write privileges. Instead, you can run bde from anywhere simply by typing: alias bde /usr/proj3/case/95s523/95sbde/bde/executables/bde or by creating a symbolic link to it: ln -s /usr/proj3/case/95s523/95sbde/bde/executables/bde bde Thereafter, to run bde you just type 'bde'. To see the real path, type 'which bde'. 1A: What happens then? 'bde' actually executes a shell script called "bde" in the executables directory that figures out which bde to run depending upon the host machine architecture ($HOSTTYPE = decstation or vax or alpha). Contents of script that runs the correct version of bde for your CPU: [The 1994 version: m /usr/proj3/case/94s523/94sbde/bde/executables/bde ...[cvs revision comments deleted - RJL]... set bde_dir = "/usr/proj3/case/94s523/94sbde/bde" set exec = "$bde_dir/executables/${HOSTTYPE}/bde" set dte = `ls -l $exec | awk '{print $5" "$6", "$7}'` echo -n "Running bde on `/bin/hostname` [${HOSTTYPE}]. Compiled:($dte)" $exec $* ] [The 97s523 version (redirects bde to later project trial versions): #!/bin/tcsh -f # set bde_dir = "/usr/proj3/case/95s523/95sbde/bde" # temp forwrd to fjara's version - RJL 96/10/10: #set bde_dir = "/usr/proj3/case/96su523/bdelog/fjara/bde" # temp forwrd to cparisi's version - RJL 97/3/?: set bde_dir = "/usr/proj3/case/96f523/bdecode/cparisi/bde" set exec = "$bde_dir/executables/${HOSTTYPE}/bde" #this runs the real executable: set dte = `ls -l $exec | awk '{print $5" "$6", "$7}'` echo "path to bde is " echo " $exec" echo -n "Running bde in background on \n \t `/bin/hostname` [${HOSTTYPE}] Compiled: ($dte) " #this runs the real executable: $exec $* & ] =================================================== Question 2: How and when is the public bde executable updated? Directory $bde_dir (see Question 1) contains the full tree checked out from the cvs repository, and will be rebuilt (hopefully) whenever a new stable bde revision is achieved. However, don't expect robust operation - bde is for public trial use only. After significant updates to $CVSROOT/bde/src files, the project manager will repeat, preferably on a regular basis: cd /usr/proj3/case/95s523/95sbde/bde # the public top-level parent node cvs update # this gets the most up-to-date checked-in versions # of ALL files (provided there is room for all of them) make # This works IFF the previous bde build was on the same hosttype. # To rebuild bde to run on a different host (vax/decstation/alpha), # before running make you need to do make clean # removes previous object and Makefile artifacts xmkmf -a # rebuilds Makefiles from generic Imakefiles # Make will update the directory tree with the current sources and Makefiles, # update the doc tree, and build the executable, whose full path name will be: .../bde/executables/${HOSTTYPE}/bde where $HOSTTYPE is either vax or decstation; (bde does not run on alpha's). After the revised version is reliable enough, it is checked into CVS again. =================================================== Question 3: How can I build my own bde executables? Answer: Complete the entire build for one type of host CPU at a time, otherwise your .o files will be invalid and recompile more than once. Our Makefiles are not smart enough to keep track of duplicate *.o files and we don't have enough disk space to duplicate source trees for each hosttype. The build procedure is as follows, starting 'from scratch': Makefiles are built using imkmf from the X library. It creates the X and Motif-dependent actions that bind bde to X-windows. [From MarkTorpey: How to build Makefiles and executables with imkmf, for one system at a time: cs> cd ?/bde [this is your top level bde tree node] cs> make clean [this will remove all old object files] cs> xmkmf -a [this makes the Makefiles/dependencies] cs> make [this actually makes bde] ] This will update the directory tree with the current sources and Makefiles, update the doc tree, and build the executable, whose full path name will be: .../bde/executable/${HOSTTYPE}/bde. where $HOSTTYPE is either vax or decstation. After that is done, you can repeat the whole process on another $HOSTTYPE: remus> cd bde remus> make clean remus> xmkmf -a remus> make This is because Imake will produce a (set of) Makefiles which "depends" on the current system. It is a system dependency tool. A makefile produced by imake for CS will almost definiteLy not work on remus, and vice/versa. Also, object files should always be removed when moving from one system from another (make clean). This is because Make is sometimes brain-dead about checking for things like that. Building bde on cs or remus should be no problem, but a complete build takes a large amount of time (15-20 mins). [Bde needs more work for dec/alpha hosts - it crashes immediately]. One more thing: Do not run make in directory bde/src. We did not set up Imake to allow that. You have to be in your top-level bde directory. Its Makefile runs make in the src and pr_util subdirectories. ] ==============================================- Question 4: Where can I build bde to test my own updates? Answer: In YOUR working directory, for example, in /usr/proj3/case/9xx52x/9xxproject//bde. Project partners can sym-link to your executable to save space. Each builder must have write access to /bde/src (*.cc and *.o files go there) and to /bde/pr_util (pr_*.c and schema.h go there). In order to use cvs commands (checkout, update, diff, history, checkin), make sure your .login file predefines the environment variable CVSROOT: setenv CVSROOT /usr/proj3/case/95s523/95sbde/base/Master echo $CVSROOT /usr/proj3/case/95s523/95sbde/base/Master The result of 'make' is a new executable in your bde/src directory, which you should move to bde/executables/$HOSTTYPE/bde, where your checked-out copy of script bde/executables/bde can find it. You should test your version of bde extensively to debug it. AFTER it works with your changes, you should do cvs update to merge other parallel updates with it then RETEST it to detect new bugs. Only then should you even think of checking it into the shared $CVSROOT repository. ================================================ Question 5: How large is the bde executable? Answer: With DEBUG #DEFINED, the executable is about 5Mb on DECstations (risc) and over 2 Mb on cs (vax). The vax version (last line below) is stripped. The command 'strip bde' removes symbol table info from bde and reduces the image by at least 50%, BUT it prevents gdb from giving you symbolic debugging help: 4774320 Jan 30 18:16 /usr/proj3/case/96f523/bdecode/cparisi/bde/executables/decstation/bde 1051648 Dec 19 18:17 /usr/proj3/case/96f523/bdecode/cparisi/bde/executables/vax/bde ================================================ Question 6: When is it OK to check in updates with cvs and rebuild bde there? Answer: Anytime in YOUR OWN $CWD; WITH CARE, AFTER testing, in the shared repository. Before checking a file you 'fixed' back into the repository, first retest it integrated with other checked-in bde updates in your OWN current working directory ($cwd): 1) Use cvs update to capture other revs than your own and merge them into your source copies in your $cwd. 2) Build and test bde locally to make sure your src files still work with other uptodate repository file mods running with or merged into them in your $cwd BEFORE cvs ci = cvs commit: 3) If bde features you and others have been fixing still work without crashing, ONLY THEN should you dare to do the cvs checkin procedure on your revised files. Before it works OK you should only build bde locally. Each checkin request asks for a revision comment. The checkin event is logged and emailed to persons identified in the file $CVSROOT/CVSROOT/loginfo. ================================================ Question 7: How can you document bugs if bde crashes? Answer: Keep another window open where you can log test results and notes with the command 'cat > bdetest.username.ddmmmyy'. E.g. bdetest.lechner.10apr97. This log file is ESSENTIAL if you want help from others (including me) to track down bugs, or if your memory does not retain enough info between debug sessions. The date-value extension avoids overwriting the log, and keeps the chronology straight until you fix the bugs you detect, or run all the s you need. ] =================================================== Question 8: What if there isn't space in /usr/proj3/case... to build bde? Answer: It takes about 10 Mb free space to build a 5Mb image for risc CPUs (decstations). One alternative, IF you have space elsewhere, is to build in your directory, then move the executable to $CASE. The new sources are then updated by 'cvs co bde' in the shared directory: [From MarkT: ...There was not enough room on the proj disk to build.. It took like 10 megs of disk space.. so i would check it out into my own directory, build it, copy the executable into the proj dir, and then build it on the other platform (vax or decstation)... The I would check it out in the proj tree so that the sources in that tree were updated.. However, some files were never updated - like the configure.h file. I DID update the file at the end of the semester though. ]