$Revision$ ($Date$) 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, replace setenv line by: > CVSROOT=:pserver:cvs@osl.cs.uiuc.edu:/osl > export CVSROOT 4. Set up the correct version number in configure.in. The variable you need to change is on line 11. 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. You could edit Makefile.stdpat to reflect where your JavaDepend is installed, but more generally, use --with-jgl and --with-jdepend options in configure 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 If you don't have JavaDepend then skip this step. This just means that some dependencies may not recompile correctly. You can always get a correctly compiled version by wiping out the .class files and recompiling. Here's how you make java dependencies if you have JavaDepend: > ./configure > 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 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 > 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 a test suite to take care of all of this. But for now, you'll just have to verify by hand: > cd ~/tmp > mkdir test > cd test > setenv CVSROOT :pserver:cvsguest@osl.cs.uiuc.edu:/osl > cvs login > cvs checkout foundry > cd foundry > ./configure > make clean (removes CVS directories) > make > ...run tests... For bash, replace setenv line by: > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT 11. When you're satisfied that the new release works. Go back to the shell where you logged in as "cvs" and tag the new release with the new version number. For example, if the new version number is 0.1.12, you would do the following: > cd ~/newrelease/original/foundry > cvs tag v0_1_12 12. Create a Win32, SPARC and Linux binary distribution (.t.gz files) and put them in the homepage area. Also create a .t.gz for the source. Some people like this better than checkout via CVS. The tar-gzipped source is easiest to create (using release 0.1.12 as an example): > cd ~/tmp > setenv CVSROOT :pserver:cvsguest@osl.cs.uiuc.edu:/osl > cvs login > cvs checkout -r v0_1_12 foundry > cd foundry > ./configure ; make distclean > cd .. > mv foundry foundry-0.1.12 > tar -cvf foundry-0.1.12.t foundry-0.1.12 > gzip foundry-0.1.12.t For bash, replace setenv line by: > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT I usually turn on assertions when creating the binary distributions. You can do that by adding the line KEYS="assert" to the make call (see below). Once things become more stable you can take this out (that is, can say "make binarydist" instead of "make KEYS="assert" binarydist"). Here's how you create a SPARC or Linux binary distribution (assuming you are on a machine with the appropriate OS): > cd > setenv CVSROOT :pserver:cvsguest@osl.cs.uiuc.edu:/osl > cvs login > cvs checkout -r v0_1_12 foundry > cd foundry > ./configure ; make clean > make KEYS="assert" binarydist > mv foundry_0_1_12.tar.gz Solaris-foundry-0.1.12.t.gz (for example) For bash, replace setenv line by: > CVSROOT=:pserver:cvsguest@osl.cs.uiuc.edu:/osl > export CVSROOT NOTE: make sure that "configure" is set up to build the "fshell" program (assuming we're still using it). If fshell isn't built during the "make" then it won't end up in the binary distribution. The Win32 release needs a little more work (of course). To make a Win32 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 executables. The makefile in foundry/win32 is setup to do this using LCC which is a freeware windows compiler available at: http://www.cs.virginia.edu/~lcc-win32. Once you have these executables assembled, you are ready to 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_12.tar.gz Win32-foundry-0.1.12.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. 13. Copy over the tar'd-gzip'd source and binary distributions to ~www/documentroot/foundry. If there's a new version of the quickstart copy it over to: ~www/documentroot/foundry/Quickstart_letter.ps If there's a new version of the manual, copy it over to: ~www/documentroot/foundry/foundry.ps Also copy over the new class documentation (assuming you've built the foundry in ~/projects/foundry): > cd ~www/documentroot/foundry/docs > 'rm' -rf * > cp -rp ~/projects/foundry/osl/docs . 14. 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.