Building Pooka from Source

Pooka is an open-source project, released under the GNU General Public License. Its source is freely available. See the license for more information about usage and distribution of the source code.

The first thing that you'll need to do is figure out which version of Pooka you want to build. If you're using a 1.2 or 1.3 JDK, then you will need to build the 1.0 version. If you are using JDK 1.4 or above, then you will want the 1.1 version. If you have a choice, go with the 1.1--it's equally as stable and has a few new features.

Steps for compiling Pooka: Get the source, get the third party libraries, and compile the program.

Getting the source

There are two ways to get the Pooka source code: downloading it from CVS and downloading it as a .jar file. Note that, if you're planning on building using ant, then you really need to get the source using anonymous CVS, since it includes things like the ant build.xml file and all of the third-party libraries in the correct location. Actually, even if you're not building with ant, you're probably better off checking out the code from SourceForge, since it's an easy way to get all of the third-party libraries. The only real drawback is that there's always the chance that I've checked in some changes that aren't yet stable, since the CVS tree is the main development tree, after all.

Checking out snapshots from CVS

The CVS tree for Pooka is now available at SourceForge. You should be able to check out the latest CVS tree from there using the following commands:

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/pooka login

Note: when it asks you for a password, just hit return. Interestingly enough, this seems to be necessary; if you try to enter a password, the login fails.

After anonymously logging in, you can check out the code. If you're checking out the 1.1 version for JDK 1.4, you just get the main branch:

cvs -z8 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/pooka co pooka

If you want the 1.0 version of Pooka (usable with JDK 1.2 and 1.3) then you'll have to specify the pooka_10 tag.

cvs -z8 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/pooka co -rpooka_10 pooka

You can also look at the SourceForge CVS HOWTO for additional information.

Downloading the Pooka source in jar format

Each Pooka release includes three jar files: an executable jar file containing all of the files necessary to run Pooka, a source file containing the Pooka source code, and a file containing the generated JavaDocs for the Pooka application. Not surprisingly, for building Pooka, you need the Pooka source jar file.

These jar files are available from the main Pooka page at SourceForge.net . Note that, for the 1.0 version, you'll want to download from the Pooka-fullJar section, while for the 1.1 version you'll want to get the Pooka-11 (jdk1.4) files.

Getting the third-party libraries

Pooka uses the following third-party libraries (in addition to the standard Java classes, of course):

Library	Pooka 1.0	Pooka 1.1
JavaMail	1.2	1.3
JavaBeans Activation Framework	1.0.1	1.0.2
JavaHelp	1.1.3	1.1.3
Java Secure Socket Extension	1.0.3	included in JDK 1.4
The Knife mbox provider
Kunststoff Look and Feel (optional)	2.0	2.0
ICE JNI library

You should be able to get all of the libraries from the above links.

As an (easier) alternative, all of the third party libraries are included in the CVS tree (under pooka/Imported). So if you get the Pooka source via anonymous CVS, then you shouldn't need to download anything else. (Actually you could also just use the executable Pooka jar file as your source for third party libraries, but I'd only suggest that if you know what you're doing.)

Compiling Pooka

Again, there are two ways to compile Pooka. You can either compile it by hand using a java compiler (such as javac or jikes), or you can use ant, the Java build tool from Apache.

Using `ant`

Using ant is really easy. Assuming ant is set up properly, you just go to the pooka directory that you've just checked out. There should be a build.xml file there. Just type

ant dist-full

from that directory and the build should proceed. You will end up with an executable jar file in the Dist subdirectory called pooka_YYMMDD.jar (or, for version 1.1, pooka_11_YYMMDD.jar). You should be able to run that file as usual (java -Xmx64M -jar pooka_YYMMDD.jar).

Compiling Pooka by hand

If you're compiling Pooka by hand, then the first thing that you need to do is to set up your CLASSSPATH. Whether you're compiling Pooka 1.0 or 1.1, you will need to add following files to your CLASSPATH:

mail.jar (from JavaMail)
activation.jar (JAF)
mbox.jar (MBOX provider)
jh.jar (JavaHelp)
kunststoff.jar (Kunststoff PLAF; optional)

If you are compiling Pooka 1.0, then you will also need the following JSSE libraries in your CLASSPATH:

jcert.jar
jnet.jar
jsse.jar

You should also put the root of your Pooka source tree in the CLASSPATH. Once your CLASSPATH is set up, it should look something like this:

/home/akp/pooka/Imported/mail.jar:/home/akp/pooka/Imported/activation.jar:/home/akp/pooka/Imported/mbox.jar:/home/akp/pooka/Imported/jh.jar:/home/akp/pooka/Imported/kunststoff.jar:/home/akp/pooka

Once you've gotten the source in place and set up your CLASSPATH, you should be just about ready to compile Pooka. Now, on the one hand, compilers such as javac are set up to compile all necessary dependencies. On the other hand, in hopes of giving myself some flexibility in extending parts of Pooka, I've relied on reflection in several cases to load the classes that I need. The net result is that you can't just compile Pooka.java and have the entire application compile correctly. Personally, I just go into all of the following directories:

/net/suberic/pooka/
/net/suberic/pooka/search/
/net/suberic/pooka/ssl/
/net/suberic/pooka/filter/
/net/suberic/pooka/gui/
/net/suberic/pooka/gui/filter/
/net/suberic/pooka/gui/search/
/net/suberic/pooka/gui/propedit/
/net/suberic/util/gui/propedit/

and do a javac *.java in each directory. Yes, it's a bit of a pain the first time that you do it, but once you have a compiled build tree, it's a lot easier to do incremental compiles after that.

Once you've compiled Pooka, you should be able to run it using

java -Xmx64M net.suberic.pooka.Pooka

(If you are using a HotSpot JVM, you may also want to include the -client option.)

At a later date (sometime soon, I hope), I'll post a quick guide to the Pooka class structure.

Building Pooka from Source / http://www.suberic.net/pooka/building.html
Allen Petersen / allen at suberic dot net

Last modified: May 10, 2005.