$Revision: 1.1 $ ($Date: 1999/12/15 13:17:34 $) This is a description of the steps I use to create a new foundry release. New Release Creation -------------------- 1. Create directories for building the new release: > cd > mkdir newrelease > mkdir newrelease/working > mkdir newrelease/original 2. Prepare your working version for patching to the source tree. Copy the root directory of your working version into the directory newrelease/working/foundry. In the example below, I use the location of my own working code to demonstrate: > cd ~/newrelease/working > cp -rp ~/projects/foundry . 3. Checkout the latest release into the original directory. Make sure that CVSROOT is set correctly so that you'll be able to commit the patches (only cvs@osl.cs.uiuc.edu is allowed to commit changes to the source): > cd ~/newrelease/original > setenv CVSROOT :pserver:cvs@osl.cs.uiuc.edu:/osl > cvs login > cvs checkout foundry For bash, and also using -r to select version checked out: > cd ~/newrelease/original > CVSROOT=:pserver:cvs@osl.cs.uiuc.edu:/osl > export CVSROOT > cvs login > cvs checkout -r 0_1_12 foundry 4. Set up the correct version number in configure.in. The variable you need to change is on line 11. You can see it via: > head -11 configure.in | tail -1 Foundry releases have the format "major.minor.release". Normally, you'll only need to modify the release number. Once you've changed it, run autoconf to build the new configure file: > cd ~/newrelease/working/foundry > ...edit configure.in... > autoconf 5. Now clean up your working version. Make sure that you have modified the appropriate makefiles so that unnecessary stuff is wiped out, and the stuff you want to keep remains after a "make distclean". Also remember that to make a permanent change to the top-level makefile, you need to change Makefile.in (the top-level Makefile is overwritten each time you call "configure"): > cd ~/newrelease/working/foundry > ./configure > make distclean 6. Rebuild the java dependency files. You must have JavaDepend installed for this to work. If you don't have JavaDepend then skip this step. This just means that some inter-dependent files may not recompile correctly if you change them. You can always get a correctly compiled version by wiping out the .class files and recompiling. > ./configure --with-jgl=... --with-jdepend=... > make jdepsclean > make jdeps > make distclean You may need to specify where JavaDepend is installed. You could edit Makefile.stdpat to do so, but more generally, use --with-jgl and --with-jdepend options to setup paths correctly. For example, on OSL machines, JavaDepend is installed under /usr/local/encap so I say: > ./configure --with-jgl=/usr/local/encap/jgl3.1.0/lib/jgl3.1.0.jar \ --with-jdepend=/usr/local/encap/JavaDepend-2.4.5/WARREN.zip > make jdepsclean > make jdeps > make distclean 7. Do a 'diff' between working and current, then apply patches to the original. There have been reports that certain versions of patch don't behave correctly when applying recursive diffs. For this reason, we suggest you use GNU patch (which is in /local/all on OSL machines) when applying patches. This step will only patch the differences in existing files. The next step adds/deletes new files or directories: > cd ~/newrelease > diff -c -r original working > patch-file > mv working foo > /local/all/patch -p0 < patch-file > mv foo working > rm patch-file 8. Do a 'diff' to discover any new files or directories. Pay close attention to the output of the diff. You want to make sure you don't accidentally include garbage in the new release, or leave left-over files which will conflict with changes in the next release. An easy way to parse diff output is as follows: > cd ~/newrelease > diff -c -r original working | grep "Only in" | grep -v CVS If you see a line "Only in original/foundry..." then this is probably a file you want to delete. The way you do this is: > cd ~/newrelease/original/foundry/...parent dir of file... > rm ...filename... > cvs remove ...filename... Directories are a little trickier to remove. The reason they are so hard to remove is because CVS isn't built to handle them yet. So, there are two hacks for removing a directory: physically remove it from the cvs repository area, or exclude it from the foundry checkout module. Physically removing a directory is an irreversible operation so make sure you really want to do this (or at least tar up the removed directory and archive it somewhere). Here's how you do it: > cd ~cvs/MainFoundrySource > rm ...thedirectorytoremove... The preferred hack is to just exclude the directory from the module checkout line. You do this by editing the file ~cvs/CVSROOT/modules. There is already an example exclusion line (commented out) in this file. It looks something like this: # foundry -a !foundry/lib foundryaux The ! indicates the name of a directory to exclude when checking out. I.e. the foundry/lib directory will not be included when the foundry module is checkout out. "foundryaux" is an alias for the real foundry distribution. NOTE: Don't remove the directories named "CVS" from ~/newrelease/original. Otherwise CVS commit will barf and you'll have to start all over again. Conversely, if you see a line "Only in working/foundry..." then this is probably a file you want to add. To add a file to the distribution, do the following: > cp -p ...file in working dir... ...dest in original dir... > cd ...directory of new file in original dir... > cvs add filename(s) To add a directory you do the same thing (i.e. copy over the entire directory to the appropriate location), except that you have to add the directory first, and then add each file IN the directory. 9. Once you're sure that all the appropriate files have been added and removed, you're ready to commit the changes: > cd ~/newrelease/original > cvs commit foundry The "commit" command will ask you to type in a brief comment describing the changes. Enter something intelligent here like "patches for release x.x.x". NOTE: if you think you have a problem BEFORE you are ready to commit, then just bail out and start over. Wipe out the newrelease directory and begin at step 1. As long as you don't commit you won't mangle the release. If you DID happen to commit, you can still back out of the changes. Consult the CVS manual for that. 10. Pop open a new shell window, go to a scratch area, login in as cvsguest, check out the foundry, and test a few things out. The key is to make sure that everything still compiles correctly and that you can run a few of the examples. In the future we may have comprehensive test methods to take care of this. For now, you can run a set of tests via Tester, and verify by hand: > cd ~/tmp > mkdir test > cd test > setenv CVSROOT :pserver:cvsguest@osl.cs.uiuc.edu:/osl [For bash: > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT ] > cvs login > cvs checkout foundry > cd foundry > ./configure > make clean (removes CVS directories) > make > ... run tests ... see directions in Tester.java ... Examine the compilation list (from make) and verify that no errors occurred. (Note, some warnings of deprecations may occur.) 11. When you're satisfied that the new release works, go back to the shell where you logged in as "cvs" (rather than as cvsguest) and tag the new release with the new version number. For example, if the new version number is 0.1.13, you would do the following: > cd ~/newrelease/original/foundry > cvs tag v0_1_13 12. Create a .t.gz source archive. (Some people prefer using tar instead of CVS checkout.) With release 0.1.13, the steps are: > cd ~/tmp > setenv CVSROOT :pserver:cvsguest@osl.cs.uiuc.edu:/osl [For bash: > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT ] > cvs login > cvs checkout -r v0_1_13 foundry > cd foundry > ./configure ; make distclean > cd .. > mv foundry foundry-0.1.13 > tar -cvf foundry-0.1.13.t foundry-0.1.13 > gzip foundry-0.1.13.t > cp -p *0.1.13.t.gz ~www/documentroot/foundry 13. Create SPARC binary distributions (.t.gz file). Some people prefer use of tar files to use of CVS checkout. I sometimes turn on assertions when creating the binary distributions. You can do that by adding the line KEYS="assert" to the make call, ie, 'make KEYS="assert" binarydist' instead of 'make binarydist'. Also, the SPARC and Linux distributions support an optional native library that speeds up certain critical paths. Here's how you create a SPARC binary distribution without assertions and with the native library (assuming you are on an OSL Sun machine): > cd > setenv CVSROOT :pserver:cvsguest@osl.cs.uiuc.edu:/osl [For bash: > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT ] > cvs login > cvs checkout -r v0_1_13 foundry > cd foundry > ./configure --with-usenative \ --with-tcllibdir=/local/encap/tcl-8.0.5/lib \ --with-tclincludedir=/local/encap/tcl-8.0.5/include > make clean > make binarydist > mv foundry_0_1_13.tar.gz \ ~www/documentroot/foundry/Solaris-foundry-0.1.13.t.gz NOTE: make sure that "configure" is set up to build the "fshell" program if it's desired. If fshell isn't built during "make", it won't end up in the binary distribution. The --with-tcllibdir= and --with-tclincludedir= options above work for OSL suns, 14. Create Linux binary distribution (.t.gz file). For example, > cd > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT > cvs login > cvs checkout -r v0_1_13 foundry > cd foundry > ./configure --with-usenative > make clean > make binarydist > rcp -p foundry_0_1_13.tar.gz \ yangtze:/home/agha/www/documentroot/foundry/Linux-foundry-0.1.13.t.gz NOTE: Use --with-tcllibdir= and --with-tclincludedir= options if necessary. Use 'make KEYS="assert" binarydist' if necessary. 15. Create a Win32 binary distribution. You first need to compile everything in foundry/win32. This must be done so that "foundry/win32/ashell" and "foundry/win32/startfoundry" are windows executable programs. The makefile in foundry/win32 is setup to do this using LCC, a freeware windows compiler available from http://www.cs.virginia.edu/~lcc-win32. After you prepare the executables, you can build the win32 distribution. Here's the complete process: a. Copy the foundry/win32 directory to a windows machine with LCC installed (or some other compiler that is capable of producing the executables). Run "make" in the foundry/win32 directory to build ashell.exe and startfoundry.exe. Copy these executables to foundry/win32 on the UNIX machine where you plan to build the distribution. b. Build the distribution as before with one minor change: > make KEYS="assert" WIN32=yes binarydist > mv foundry_0_1_13.tar.gz Win32-foundry-0.1.13.t.gz c. You may want to unpack the gzip'd archive and repack it as a .zip file. Zip files are usually more palatable for win32 platforms. d. Copy the .t.gz and/or zip file to ~www/documentroot/foundry 16. Publish new javadoc class documentation and any new documents via ~www/documentroot/foundry. If you built the foundry in ~/foundry, say: > cd ~www/documentroot/foundry > 'rm' -rf docs > cp -rp ~/foundry/osl/docs . If there's a new version of the quickstart: > cp -p Quickstart_letter.ps ~www/documentroot/foundry/Quickstart_letter.ps If there's a new version of foundry.ps manual: > cp -p foundry.ps ~www/documentroot/foundry/foundry.ps 17. Create 'what's changed' and 'new release info' areas on the webpage. Commit all the web page changes (i.e. save them to disk). The main web page is: ~www/documentroot/foundry/index.html The new release info is usually stored in the "features" directory: ~www/documentroot/foundry/features where the naming scheme is release___.html. Once the web pages have been updated, you should send e-mail out to all interested parties. Items Which Must Be Rebuilt For Each Release -------------------------------------------- The following items are not stored in the CVS repository which holds the web pages. Thus they must be regenerated and placed in the web area each time a new release is created. - Quickstart_letter.ps - foundry.ps - javadoc generated documentation (/docs subdirectory) - foundry-.tgz - Solaris-foundry-.tgz - Linux-foundry-.tgz - Win32-foundry-.tgz - Win32-foundry-.zip