Installing and using the source distribution

The Kawa release normally comes as a gzip-compressed tar file named ‘kawa-1.14.tar.gz’. Two methods are supporting for compiling the Kawa sources; choose whichever is most convenient for you.

One method uses the traditional GNU configure script, followed by running make. This works well on Unix-like systems, such as GNU/Linux. You can also use this method on Microsoft Windows, as long as use http://www.cygwin.org/. Cygwin.

The other method uses the ant command, a Java-based build system released by Apache’s Jakarta project. This uses an build.xml file in place of Makefiles, and works on non-Unix systems such as Microsoft Windows. However, the ant method does not support all the features of the configure+make method.

Build Kawa using configure and make

In your build directory do:

tar xzf kawa-1.14.tar.gz
cd kawa-1.14

Then you must configure the sources. This you can do the same way you configure most other GNU software. Normally you can just run the configure script with no arguments:

./configure

This will specify that a later make install will install the compiled ‘.class’ files into /usr/local/share/java. If you want them to be installed someplace else, such as $PREFIX/share/java, then specify that when you run configure:

./configure --prefix $PREFIX

If you have the GNU ‘readline’ library installed, you might try adding the ‘--enable-kawa-frontend’ flag. This will build the ‘kawa’ front-end program, which provides input-line editing and an input history. You can get ‘readline’ from archives of GNU programs, including ftp://www.gnu.org/.

If you have Swing installed, and want to use JEmacs (Emacs in Java), also pass the --with-swing flag to configure.

If you have installed Kawa before, make sure your CLASSPATH does not include old versions of Kawa, or other classes that may conflict with the new ones.

As-distributed, the Kawa source code requires Java 6. If you only have Java 5, use the --with-have-source option:

./configure --with-java-source=5

If you want to add support for certain Java 6 features, but produce a .jar file that will execute under Java 5 do:

./configure --with-java-source=6compat5

Note this requires that you build Kawa with Java 6.

In theory Kawa supports older versions of Java (such as JDK 1.4 or even 1.1), though this has not been tested in a while. You use the appropriate --with-java-source option, but you still need a Java 5 or later version of javac to build Kawa. You then need to use a tool like Retroweaver on the Kawa .jar to fix up Java 5 dependencies. Contact the Kawa author if you want to be a tester for this.

Then you need to compile all the .java source files. Just run make:

make

This assumes that ‘java’ and ‘javac’ are the java interpreter and compiler, respectively. For example, if you are using the Kaffe Java interpreter, you need to instead say:

make JAVA=kaffe

It has been reported that parallel make doesn’t work, so don’t use the -j2 or above options.

If you configured with --enable-kawa-frontend, you may need to specify READLINE_INCLUDE_PATH or READINE_LIB_PATH. For example on OS/X you need to do:

make READLINE_INCLUDE_PATH=-I/usr/local/unix/readline/include \
     READLINE_LIB_PATH=-L/usr/local/unix/readline/lib

You can now test the system by running Kawa in place:

java kawa.repl

or you can run the test suite:

make check

or you can install the compiled files:

make install

This will install your classes into $PREFIX/share/java (and its sub-directories). Here $PREFIX is the directory you specified to configure with the --prefix option, or /usr/local if you did not specify a --prefix option.

To use the installed files, you need to set CLASSPATH so that $PREFIX/share/java/kawa.jar is in the path:

CLASSPATH=$PREFIX/share/java/kawa.jar
export CLASSPATH

This is done automatically if you use the ‘kawa’ script.

Build Kawa using ant

Kawa now includes an Ant buildfile (build.xml). Ant is a part of the Apache Jakarta project. If you don’t hava Ant installed, get it from http://ant.apache.org/bindownload.cgi. The build is entirely Java based and works equally well on *nix, Windows, and presumably most any other operating system.

Once Ant has been installed and configured (you may need to set the JAVA_HOME, and ANT_HOME environment variables), you should be able to change to the directory containing the build.xml file, and invoke the ‘ant’ command. With the default settings, a successful build will result in a kawa-1.14.jar in the current directory.

There are a few Ant "targets" of interest (they can be supplied on the Ant command line):

all

This is the default, it does classes and jar.

classes

Compiles all the files into *.class files into the directory specified by the build.dir property.

jar

Builds a jar into into the directory specified by the dist.dir property.

runw

Run Kawa in a GUI window.

clean

Deletes all files generated by the build, including the jar.

There is not yet a test target for running the testsuite.

The are various "properties" that control what ant does. You can override the on the command line or by editing the build.properties file in the same directory as build.xml. For example the build.dir directory tells ant where to build temporary files, and where to leave the resulting .jar file. For example, to leave the generated files in the sub-directory named BUILD do:

ant -Dbuild.dir=BUILD

A sample build.properties is provided and it contains comments explaining many of the options.

Here are a few general properties that help to customize your build:

build.dir

Path to put the temporary files used for building.

dist.dir

Path to put the resulting jar file.

version.local

A suffix to add to the version label for your customized version.

debug

Whether (true/false) the Javac "-g" option is enabled.

optimize

Whether (true/false) the Javac "-O" option is enabled.

Here are some Kawa-specific ones (all true/false): with-collections, with-references, with-awt, with-swing, enable-jemacs, and enable-servlet> See the sample build.properties for more information on these.

If you change any of the build properties, you will generally want to do an ‘ant clean’ before building again as the build is often not able to notice that kind of change. In the case of changing a directory path, you would want to do the clean before changing the path.

A special note for NetBeans users: For some reason the build-tools target which compiles an Ant task won’t compile with the classpath provided by NetBeans. You may do ‘ant build-tools’ from the command line outside of NetBeans, in which case you will not want to use the clean target as that will delete the tool files as well. You can use the clean-build and/or clean-dist targets as appropriate. Alternatively you can add ant.jar to the build-tools classpath by copying or linking it into a lib/ext directory in Kawa’s source directory (the one containing the build.xml file).

Compiling Kawa to native code with GCJ

The GNU Compiler for the Java(tm) Programming Language (GCJ) is part of the GNU Compiler Collection (GCC). It can compile Java source or bytecode files into native code on supported systems. Version 4.1 or later of GCC is recommended, and only Intel x86-based Linux/GNU system have been tested with Kawa.

First, get and install GCC. Set PREFIX to where you want to install GCJ, and configure it with these options:

./configure --enable-threads --enable-languages=c++,java --prefix $PREFIX
make bootstrap
make install

Make sure gcj is in your path and refers to the newly-installed version, and if needed, set LD_LIBRARY_PATH to point to the directory where libgcj.so was installed:

PATH=$PREFIX/bin:$PATH
LD_LIBRARY_PATH=$PREFIX/lib
export LD_LIBRARY_PATH

To build Kawa, you need to specify --with-gcj to configure which tells it to use GCJ.

./configure --with-gcj --prefix $PREFIX

Then as before:

make
make install

Alternatively, you can use configure option --with-gcj-dbtool. This allows gcj to automatically find the kawa shared libraries from the .jar file.

Building Kawa under MS-Windows

Using the ant method is recommended for building Kawa under Microsoft Windows. You may get an error message "Out of environment space." See http://support.microsoft.com/support/kb/articles/Q230/2/05.ASP for a solution. Alternatively you can run the class org.apache.tools.ant.Main directly from the Ant jar.

The Kawa configure and make process assumes a Unix-like environment. The free Cygwin environment can be used for building Kawa: The Kawa configure script recognizes Cygwin, and modifies the classpath to use Windows-style path separators. (At the time of writing there were still some path issues with running the testsuite.)

MinGW may also work but has not been tested.