Kawa, the Java-based Scheme system

Node:Source distribution, Previous:Binary distribution, Up:Installation

### Installing and using the source distribution

The Kawa release normally comes as a gzip-compressed tar file named `kawa-1.7.tar.gz`. The same sources are available as a zip file `kawa-1.7-src.zip`. 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. It does not work well under Microsoft Windows. (Even when using the CygWin Unix-emulation package there are some problems with file paths.)

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 `Makefile`s, 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.7.tar.gz
         cd kawa-1.7

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.

If you use a very old or bare-bones Java implementation that not have certain "Java 2" features (such as `java.util.List`, `java.lang.ref`, or `ThreadLocal`) then you need to convert the Kawa source-code so it doesn't depend on those features. You do this with the following command:

         make select-java1

Most people should not need to do this. (You don't need to if you're using GCJ, even though it doesn't implement all of Java 2.) (If you need to convert the code back to the default, do: `make select-java2`.)

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

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 buildfile should work with Ant 1.3, and has been tested with 1.4.1. and 1.5.1. 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.7.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).

#### Using the Jikes compiler

Jikes is a Java source-to-bytecode compiler that is much faster than Sun's `javac`. (Note that this only speeds up building Kawa from source, not actually running Kawa.) The instructions for using jikes are as above, except that you need to specify Jikes at `configure` time, setting the `JAVAC` environment variable. If `jikes` is in your execution path, do:

         JAVAC=jikes ./configure

You also need to inform Jikes where it should find the standard Java classes (since Jikes is a compiler only). For example:

         CLASSPATH=.:/opt/jdk1.3/jre/lib/rt.jar
         export CLASSPATH

#### 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 3.3 or later of GCC is recommended, and only Intel x86-based Linux/GNU system have been tested with Kawa.

First, get and install GCC 3.3. 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. Currently you also need to specify `--without-awt --without-swing` because GCJ does not yet support AWT or Swing:

         ./configure --with-gcj --without-awt --without-swing --prefix $PREFIX

Then as before:

         make
         make install

#### 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. If you want to build Kawa from source under Windows (95, 98, or NT), you could use a Unix empulation package, such as the free Cygwin. However, there are some problems with filenames that make this more complicated than it should be. It should be possible to build Kawa under Cygwin using `gcj` as descibed above.