This is Kissme, a free Java Virtual Machine
-------------------------------------------

Dependencies
------------

Please refer to doc/BUILDING for a list of the tools needed to
build Kissme.


Building
--------

For detailed build instructions read doc/BUILDING.

Brief build instructions for release 0.0.31:

1) Download the GNU Classpath 0.06 tarball from:
      http://www.gnu.org/software/classpath/

2) Untar the Classpath tarball

3) Change directory to the Classpath dir and configure it with the 
   following command: 
      $ ./configure --enable-jni --enable-gtk-peer

4) Compile Classpath: 
      $ make

5) Install Classpath:
      $ make install      # this command is typically run as 'root'

6) Change to the Kissme directory, and configure with this command: 
      $ ./configure --enable-use-zips \
	--with-gnu-classpath=<directory to classpath-0.04>

7) Compile Kissme as follows: 
      $ make

This should produce the "./kissmebin" binary and a "classes.zip" file 
containing VM-specific .class files.

Running
-------

Kissme requires you to manually indicate where to find the classpath 
native .so libraries. If you don't do this, you will see a whole lot 
of errors.  You also need to get the classpath correct.  The easy way
to do all of this is to run Kissme using the wrapper script provided.
For example:

       $ ./useful_scripts/kissme helloworld

Class libraries
---------------

Kissme will *only* work with the Classpath java libraries. Using a 
classes.zip from Sun's JDK or IBM's JDK will not work.

Documentation
-------------

doc/BUGS describes the bugs we know about 
doc/BUILDING describes the kissme build process in greater detail
doc/BUILDING_OSKIT describes how to build an OSKIT multiboot image 
	from kissme (out of date)
doc/BUILDING_CLASSES_ZIP describes how to build a classes.zip file 
	containing only the classes needed to run a certain program
	(out of date)

Testing Kissme
--------------

You can test that Kissme is working by compiling and running the 
mini tests:

      $ jikes trivial.java helloworld.java
      $ useful_scripts/kissme trivial
      $ useful_scripts/kissme helloworld

The Makefile contains further rules for testing Kissme:

      $ make build-hitme            # build & run the 'hitme' VM tests
      $ make run-hitme              # ...
      
      $ make configure-mauve        # configure, build and run the Mauve
      $ make run-mauve-regression   # regression tests for the JDK

Note: a significant number of Mauve tests fail, but this is largely
due to problems with Classpath and the tests themselves.


Configuration Options
---------------------

You can tweak the configuration process using ./configure options.
See "./configure --help" for details.  Also refer to doc/BUILDING

You can also edit the #defines in the config.h file to enable /
disable debug code and other things.  Be careful though, since many
of the alternative #define settings haven't been tries in a long,
long time.

Reporting bugs
--------------

Please report bugs using the Kissme project's bug reporting page
on SourceForge:

      http://sourceforge.net/projects/kissme

It helps to send the java source code and .class files of the program
you tried to run. Also include a description of what happened. If
possible generate a core file by first typing:

      $ ulimit -c unlimited

and then rerun kissme.  Run gdb on the core file and get a backtrace 
by typing 'bt'. 


--------------------------------------------------------

John Leuner
jewel@pixie.co.za

Stephen Crawley
crawley@dstc.edu.au

Updated: 20 August 2003







