KAFFE                                                       COMMON PROBLEMS
===========================================================================
Written by Tim Wilkinson <tim@tjwassoc.demon.co.uk>, 1996-97.
Ported to AmigaOS by Matthias Hopf <mshopf@informatik.uni-erlangen.de>


                     NOTES ABOUT THE AMIGAOS PORT
                     ============================

The Amiga port has been done in a relatively straightforward way using  the
Geek  Gadgets  (abbreviated  GG  in  this  document) developer environment,
formerly known as ADE (Amiga Developer Environment). Thus to work  properly
it  needs  at  least  version 45.0 of ixemul.library, available from any GG
mirror.

The needed Sun java classes are not included due to legal reasons. They are
available  as  a  seperate archive, e.g. kaffe-0.9.0-sun.tgz. If you get an
'Cannot find essential class 'java/lang/Object' in class library ...',  you
probably  do  not  have  the  Sun  classes  included in your CLASSPATH (see
below). Note that begining with kaffe-0.9.0 you  will  need  the  JDK-1.1.1
version of classes.zip.

To set up kaffe, do 'make  install'  in  an  GG  environment,  set  up  the
environment  variables as stated in the file ENVIRONMENT and make sure that
kaffe can be found in your path as well as in  the  sh  'PATH'  environment
variable.

Try 'kaffe HelloWorldApp' in the test/ directory. Guess what it does :-)

Try 'javac HelloWorldApp.java' in the  test/  directory.  But  be  prepared
- the javac compiler class is relatively slow...

Try 'make test' in the main directory. This  will  run  a  number  of  test
suites. Most tests should work by now. This test takes a lot of time...

When kaffe does not work properly, please  read  the  COMMON  CONFIGURATION
PROBLEMS  and  KNOWN  BUGS sections below before sending any bug reports to
me, or even better to the mailing list gg-java@ninemoons.com.  When  I  ask
you  to,  please  fill  out the system configuration report you can find in
config/m68k/amigaos/REPORT.amiga and send it to me. It will help debugging.



                     COMMON CONFIGURATION PROBLEMS
                     =============================

- 'version ixemul.library'
  You will need at least V44.0 of ixemul.library. The kaffe binaries that
  can be fetched from ftp.ninemoons.com need at least V45.0 of
  ixemul.library.

- Sun's classes.zip file.
  For kaffe to work properly you will need the JDK 1.1.1 classes.zip file
  from Sun, available from Sunsoft or from any kaffe-sun-* archive from
  ftp.ninemoons.com.
  *NOTE* The JDK classes.zip files from earlier releases will not work with
  kaffe! Guavac seems to be shipped with the old Sun classes.

- 'echo "$CLASSPATH"'
  The classpath has to include at least '.' (the current directory) and
  Sun's classes.zip file (the file itself, not the directory where it is
  located). A valid classpath may be set with e.g.
    setenv CLASSPATH ".;GG:share/kaffe/classes.zip"
  Don't forget the doublequotes (';' is the comment specifier in AmigaDos).
  And do not forget the trailing dot when specifying the current directory
  or volumes (e.g. 'kaffe:.'). Of course the CLASSPATH specification is
  also affected by your ixprefs settings!

- 'ixprefs -i 0'
  Either you will have to make ixemul.library recognize global environment
  variables, or you will have to set the local environment variable
    set CLASSPATH="$CLASSPATH"
  Again, don't forget the doublequotes.

- 'EMT Trap.'
  When kaffe simply aborts with 'EMT Trap', then you have probably an
  executable compiled for Amigas with coprozessors (versions before 0.7.1
  from GG were compiled with -m68881 by accident).
  It is possible, that you have the wrong ixemul.library installed, too.
  If you do not get this problem regulary, it may well be that you just
  encountered a problem inherrited to several IDE drives which cannot
  handle high MaxTransfer settings (if any is set up at all...).
  If you run kaffe from a SCSI drive, it can also be a drive and/or host
  adaptor with reselection problems. In that case disable reselection.



                              KNOWN BUGS
                              ==========

KNOWN BUGS of the current version

- Not all pointer access are checked for null pointer accesses. However,
  kaffe should work better now than in the last few versions.



KNOWN BUGS of former versions

* distributions before V0.9.0

- NullPointerExceptions were not generated at all. The kaffe code relied on
  SIGSEGV signals for NULL pointer access, which cannot work on AmigaOS.
  *NOTE* On NULL pointer access you *will* encounter Enforcer hits.
  These can even crash your computer...

* distributions before V0.7.1

- When kaffe simply aborts with 'EMT Trap', then you have probably an
  executable compiled for Amigas with coprocessors (binary archives from
  GG were compiled with -m68881 by accident and the configure script
  added the options -m68020-40 and -m68881).

* distributions before V0.7.0

- kaffeh produced loads of (most times harmless) Enforcer hits and
  generated wrong files sometimes.

- kaffeh liked to abort with 'Bus error' when invoked without the
  '-stubs' option.

* distributions before V0.6.0

- kaffeh of distributions before V0.6.0 used a different CLASSPATH scheme
  (':' as seperator).

- kaffevm/thread.c did not compile without warnings because of the thread
  switching macros.

- kaffe-0.5p4 aborted with an 'Exception thrown on NULL object' when the
  classes.zip file (see below) couldn't be found. kaffe-0.5.5 simply
  crashes, however. Begining with kaffe-0.6.0 this abnormal exception is
  caught.


KNOWN COMPILATION BUGS of former versions

* distributions before V0.7.1

- Kaffe was compiled with -m68020-40 and -m68881 by accident.

- Several version did not compile when fetched from Tim's original kaffe
  site. The GG versions had several bug fixes.


NONWORKING CLASSES

- some tests in regression still fail

* distributions before V0.9.0

- exception/NullTest  (see BUGS)
- exception/StackDump
- some more...


OTHER NOTES

* distributions before V0.7.1

- The thread switching code was not perfect. However, you should not notice
  that except when compiling kaffe...



That's it, folks :)

Matthias Hopf
<mshopf@informatik.uni-erlangen.de>


----
* Java and Javasoft are registered trademark of Sun Microsystems, Inc.
