Kaffe for Plan 9 User guide

Kaffe & Plan9

http://www.hut.fi/~akuukank/oht/documents/ko.html
Last updated 23.3.1998.
Authors: Jussi Laakkonen (11.2.1998), Vesa Krpijoki (23.3.1998)
Verifiers: Vesa Krpijoki (23.3.1998), Teemu Ikonen (12.2.1998), Jari
Kytjoki (15.2.1998), Jussi Laakkonen (23.3.1998), Arttu Kuukankorpi
(23.3.1998)

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

Contents

Summary

1. Introduction
     1.1. About this document
     1.2. Target of document
     1.3. Description of the system
     1.4. Interfaces to the system

2. Installation
     2.1. Requirements
     2.2. Installing Kaffe for Plan 9
          2.2.1. Acquire Kaffe for Plan 9
          2.2.2. Compiling Kaffe (optional)
          2.2.3. Environment settings
     2.3. Files in Kaffe
     2.4. Plan 9

3. Functions
     3.1. Basic line functionality
     3.2. Command line switches
     3.3. Examples of use
          3.3.1 Hello World App
          3.3.2 javac - The Java Compiler
     3.4. Notes

4. Problem situations
     4.1. About Kaffe
     4.2. Typical problems
     4.3. Problems with stack tracing in JIT-Kaffe

5. Maintenance
     5.1. Support
     5.2. Upgrading
     5.3. Reporting bugs
     5.4. Modifying Kaffe for Plan 9

6. References

7. Glossary

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



Summary

This is the user guide for Plan 9 port of Kaffe that was a project for an
undergraduate course Tik-76.115 Software Project in the Helsinki University
of Technology. The project was done by the Bela Lugosi team.

Kaffe is a freely distributable JIT-compiler for the Sun Microsystem's Java
language. Kaffe was created by Tim Wilkinson and his team "Jolt Project".
This port of Kaffe runs on Plan 9 system platform for Intel processors. The
port is based on 0.9.2 release of Kaffe which supports the JDK version
1.1.3 of the Java language. It is assumed here that the reader is familiar
with the Plan 9 system.

The Kaffe for Plan 9 package requires Intel 80386 compliant processor and
that you have installed Plan 9 (for Intel) correctly. The installation
itself is very straightforward and simple provided that you follow the
instructions given in this document carefully.

This document describes briefly the use of Kaffe by giving an example. The
document also describes typical problem situations you might encounter
while installing or using Kaffe for Plan 9 and gives the possible solutions
to them. Since this version of Kaffe does not even verify the class files,
most of the possible error messages are actually Java exceptions which
Kaffe does not know anything of and therefore those situations are beyond
the scope of this document.

The Bela Lugosi team can not and will not provide any support for any
version of Kaffe or Plan 9. We take no responsibility for bug fixing or end
user assistance. The reader, however, is encouraged to study and modify the
source code for his/her own interest. It is noteworthy that certain
copyrights apply to this package too. See references and glossary of this
document for further information.

Section                Contents
Section 1 -            The first section gives a short introduction to the
Introduction           Kaffe for Plan 9 package and its background.

Section 2 -            This section gives full instructions of how to
Installation           install and configure the Kaffe for Plan 9 package
                       for your system.
                       The section 3 discusses the use of the software and
Section 3 - Functions  gives also a short example of a typical Kaffe
                       compilation.

Section 4 - Problem    This section describes the problems that the reader
situations             may encounter with Kaffe. The section gives
                       solutions to some trivial problems.

Section 5 -            The fifth section discusses about how the Kaffe for
Maintenance            Plan 9 is supported and how you can modify the
                       source code.
Section 6 -            This section lists the references (most of them are
References             in WWW format) the reader might want to go through.

Section 7 - Glossary   The terms and acronyms used in this document are
                       described here.

Section 8 - Index      An alphabetical index of the keywords of this
                       document.


1. Introduction

1.1. About this document

This is the user guide for Kaffe. Kaffe is a freely distributable JIT-
compiler for the Java language. Kaffe was ported to Plan9 as project for an
undergraduate course Tik-76.115 Software Project in the Helsinki University
of Technology. The project was done by the Bela Lugosi team.

The software and all accompanying files are provided AS IS . You use them
on your own responsibility. Bela Lugosi assumes no responsibility for
direct or indirect damages caused by the use of Kaffe for Plan 9.

As such Kaffe is created by amateurs, "hackers" some might call them. The
original Kaffe distribution was created by Tim Wilkinson and the
collaborative team called the "Jolt project". Kaffe isn't a particularly
easy to use nor user friendly piece of software. It is created with the
serious user or expert in mind.

NOTE: This document assumes that the reader is familiar with the
conventions of Unix and Plan 9. The purpose of this documentation is not to
provide assistance with problems related to Plan 9.

However after it has been set up, Kaffe is relatively easy to use as it
offers a very limited set of operations: Kaffe is used for executing other
programs such as the Java compiler or the basic "Hello world" application.
If the reader isn't familiar with setting up software in Plan 9 systems, we
recommend that a more proficient person will install the software.

1.2. Target of document

This document describes the Plan 9 version of the Kaffe 0.9.2 Java
JIT-compiler and interpreter. Plan 9 is designed to be a multi-platform
operating system. However due to the nature of Plan 9 (development has
ceased, development support and technical documentation is non-existant or
contradictionary), Kaffe has been ported only for i386 compatible systems.

1.3. Description of the system

The Java programming language is network oriented, platform independent
system created by Sun Microsystems. Currently it is developed by JavaSoft,
a daughter company of Sun Microsystems.

The Java language is based on concept of bytecode. When Java programs are
compiled, machine language code for an imaginary Java processor is created.
This code is called bytecode. As there is no actual (save of Sun's special
Java processors) Java processor, the bytecode must be run inside a special
Virtual Machine (VM) that complies to the specifications of the Java
processor.

This Virtual Machine operates on top of the actual operating system, which
can be anything from Windows '95 to SCO-Unix and even Plan 9. Kaffe is one
of the many Virtual Machines. Kaffe has been created by a group
enthusiastic programmers called the "Jolt project".

There are two basic ways in which Java bytecode can be executed:
interpreted or compiled via just-in-time compilers. Interpretation is the
tradional way and considerably slower. JIT (just-in-time) compilers take a
different approach. The Java bytecode is compiled to native machine
language just-in-time (JIT) before the actual execution of the bytecode
takes place. This results in increased speed.

Kaffe supports both of these two modes of execution as does the Plan 9 port
of Kaffe. The port is based on the 0.9.2 release of Kaffe and thus supports
the JDK 1.1.3 version of the Java language.

1.4. Interfaces to the system

From the ordinary users point of view, Kaffe acts like a black box. Java
classes go in and some form of output is produced. The actions between the
input and the output are determined by the class file that is executed. In
most cases (save for exceptions and error situations) the output is also
dictated by the class file that was executed.

The user is able to supply a set of options for the Kaffe (see more details
in here) but otherwise the operation of Kaffe is not determined by the end
user.

From the system's point of view, Kaffe is just an ordinary program. It
starts at some random moment, takes in input, reads and writes logical
devices (hard disk, network, keyboard etc) and produces output. Kaffe runs
in normal user mode. However, as Kaffe is a Virtual Machine the routines
used by Kaffe are often very involved and complex. During normal operation
this doesn't affect the outcome in any other way except that the execution
of a Java program might be slower than a similar C / C++ -program.

In Plan 9 all system objects are considered files: keyboard, windowing
system, network etc. The ported version of Kaffe follows this philosophy.



2. Installation

2.1. Requirements

The system you are installing Kaffe for Plan 9 package into has to fill
these requirements:
   o This package is intended for Intel i386 compliant processors (80386 or
     better) - Plan 9 for Intel utilizes the 32-bit protected mode of the
     machine.
   o Plan 9 (for Intel platform naturally) properly installed (NOTE: if you
     have an older Plan 9 version, we cannot ensure that the version
     supports everything that the Kaffe for Plan9 package requires). If you
     haven't yet installed Plan 9 you should check the Plan 9 manuals or
     the 'Various Ports' information page of the Bell Labs to see if your
     hardware really supports Plan 9.

As was mentioned in the introduction, it is assumed in this document that
the reader is familiar with the Plan 9 and UNIX systems. It is naturally
assumed also that the reader has learned at least the basics of the Java
language.

2.2. Installing Kaffe for Plan 9

Kaffe for Plan 9 is distributed in a single package that contains the
source code of the system, a compiled binary for i386+ compliant Plan 9
systems, Java native methods and documentation (see section 2.3. for
details).

Installation should follow the following procedure:

2.2.1. Acquire Kaffe for Plan 9

Kaffe is distributed at http://www.kaffe.org . This is the WWW-site for the
whole Kaffe project and provides the latest versions of Kaffe for various
platforms including Plan 9.

Make sure that you have the latest version of the Kaffe for Plan 9 before
proceeding. This can be done by comparing your copy to the version
available from the Kaffe website.

2.2.2. Compiling Kaffe (optional)

Kaffe for Plan 9 comes with complete source code. However this port of
Kaffe is intended for Plan 9 systems running on i386 (Intel) compliant
processors. Along with the distribution comes a compiled binary executable
of latest version of Kaffe for Plan 9.

If you wish you can compile a new binary by using the source code and
makefiles provided with the distribution. To do this extract the files from
the tar-archive and compile them using Plan 9's make: mk.

2.2.3. Environment settings

The Java Virtual Machine requires one environmental setting to be available
in order to function. This is called the CLASSPATH environment variable. It
tells the Virtual Machine where to look for the JDK classes that come with
the distribution (classes.zip) and other Java class files. Kaffe has also a
classpath enviroment variable of its own, KAFFE_CLASSPATH which can be used
as alternative to the CLASSPATH variable. You have to set just either of
these two variables. NOTE: Classes.zip is part of Sun's distribution of API
1.1.3 and it has nothing to do with the development team of Kaffe.

Normally your CLASSPATH (or KAFFE_CLASSPATH) will point to the directory
where you installed your version of Kaffe and to your current directory
'.'. E.g.: CLASSPATH=/usr/local/kaffe/classes.zip:.

Now you are set up and ready to use Kaffe.

2.3. Files in Kaffe

For a Kaffe system you need the parts described in the table:

Part                                    Contents

kaffe-0.9.2-plan9.tgz                   Virtual machine and all bits provided
                                        by tjwassoc.co.uk
kaffe-0.9.2-package-javasoft.com.tgz    Sun's class libraries ver. 1.1.3

Uncompress and untar these archives into the same directory.

NOTE: Please read the license restriction for the classes!

2.4. Plan 9

Plan 9 itself does not need any special configurations when running Kaffe.
As was mentioned in the previous section, the environment variable
CLASSPATH (or KAFFE_CLASSPATH) must be set. It is also worth mentioning
that every user using Kaffe must have privileges to the JDK classes package
classes.zip.

3. Functions

3.1. Basic functionality

When Kaffe has been installed correctly, Java classes can be run with this
command:

kaffe [-options] class

It is assumed here that Kaffe can be run from the current directory (thus
the PATH environment variable must be set correctly). Note also that the
filename of the Java class must be given without the '.class'-extension.
The command line options of Kaffe are given as switches, they are explained
in the following section.

3.2. Command line switches

The current version of Kaffe supports the following command line switches:

Switch                    Explanation

-help                     Print this list of command line switches and
                          their explanations
-version                  Print version number
-ss <size>                Maximum native stack size
-mx <size>                Maximum heap size
-ms <size>                Initial heap size
-classpath <path>         Set classpath
-verify                   Verify all bytecode
-verifyremote *           Verify bytecode loaded from network
-noverify                 Do not verify any bytecode
-D<property>=<value>      Set a property
-verbosegc                Print message during garbage collection
-v, -verbose              Be verbose
-verbosejit               Print message during JIT code generation
-verbosemem               Print detailed memory allocation statistics
-debug *                  Trace method calls
-noasyncgc *              Do not garbage collect asynchronously
-cs, -checksource *       Check source against class files
-oss <size> *             Maximum java stack size
-prof *                   ?

NOTE: * = Option ignored in this version (0.9.2) of Kaffe.

3.3. Examples of use

The source comes with a large bunch of test programs (including the killer
application HelloWorldApp) which can be found in the test/ directory in the
distribution.

3.3.1. Hello World App

After installation, you should probably continue with running the
"HelloWorldApp" test program from the test directory by typing the
following:

cd ["the java source directory"/]test/
kaffe HelloWorldApp

This should load and execute the HelloWorld application. If all is well it
will print:

Hello World!

As a further test you might like to try compiling the HelloWorldApp source.
To do this type the following (in the same test directory):

javac HelloWorldApp.java

"javac" is a shell script which has been provided to invoke Kaffe on the
standard Java compiler. If all is well, the application should compile
without incident.

The "javac" shell script:

#!/bin/rc
# Script to run Sun's compiler using Kaffe.
kaffe sun.tools.javac.Main $@

If you want to get more information while JIT-running an application, you
can give the '-verbose' option in the command line:

kaffe -verbose HelloWorldApp

Loading class 'java/lang/Object'.
Loading class 'java/io/Serializable'.
Loading class 'java/lang/Class'.
...
(printing suppressed)
...
Loading class 'java/lang/reflect/Member'.
Loading class 'sun/io/CharToByte8859_1'.
Loading class 'HelloWorldApp'.
Hello World!

3.3.2. javac - The Java Compiler

If you run "javac" without any arguments you will get the currently
available options:

javac

use: javac [-g][-O][-debug][-depend][-nowarn][-verbose][-classpath path]
[-nowrite][-deprecation][-d dir][-J] file.java...

For more info see: javac - The Java Compiler; SYNOPSIS, DESCRIPTION and
OPTIONS [8].

3.4. Notes

Kaffe should run all Java code. However there are still bugs and plenty of
untested native library functions. Some functions which are not currently
implemented will simply abort if called. If you want to work on any of
these then please remember that this is a clean-room implementation (none
of Sun's source code is used in the Kaffe project). Also note that this
version of Kaffe utilizes Sun's freely available compiled class library but
it is impossible to validate whether this software is Java compatible(tm)
because the test suites are not publically available.



4. Problem situations

4.1. About Kaffe

Kaffe itself produces errors only if the command line options (switches
explained in the section 3.2.) are wrong (or something is missing). Of
course, if an internal error is detected, Kaffe may stop its execution when
an assert-call fails. NOTE: Kaffe does not verify the bytecode of the class
file in any way!!! It only checks if the class file has the correct magic
number in the first four bytes (the magic number is 'cafebabe' in hex
format).

Thus every other error messages are created by Java itself! E.g. if Kaffe
is applied to a file that does not exist in the current directory:

term % ls -l
term % kaffe HelloWorldApp
java.lang.ClassNotFoundException: HelloWorldApp

Therefore majority of the problem situations (exceptions given by Java) are
beyond of this document. See Java documentation for further information of
the Java exceptions.

4.2. Typical problems

Typical problems and their possible solutions are listed in the following
table:

 Problem                                         Possible solution

 You get error message from Plan 9               The environment variable
                                                 PATH is not set in Plan
 kaffe: file does not exist                      9. See Plan 9 manuals in
                                                 references section for
                                                 further information.

 Kaffe gives an error message                    The CLASSPATH environment
                                                 variable is not set at
 CLASSPATH is not set!                           all. Consult to section
                                                 2.2. for further
                                                 assistance.

                                                 The CLASSPATH environment
                                                 variable has been given a
 Kaffe signals an error                          wrong value. Therefore
                                                 Kaffe cannot find the
 Cannot find essential class 'java/lang/Object'  essential JDK class
                                                 package 'classes.zip' and
 in class library ... aborting                   it is not able to load
                                                 the necessary base
                                                 classes. Consult to
                                                 section 2.2. for further
                                                 assistance.

                                                 The class file to be
                                                 compiled is either
                                                 corrupted or it does not
                                                 have Java bytecode at
                                                 all. In both cases, the
                                                 four-byte magic number is
                                                 not correct ('cafebabe').
 Kaffe signals an error                          Kaffe does not verify the
                                                 bytecode in any way, so
 Bad magic acdc1234 in class                     as long as the magic
                                                 number is ok and the
                                                 filename given to Kaffe
                                                 is in format
                                                 filename[.class], Kaffe
                                                 thinks the class file is
                                                 ok. At this point, every
                                                 error message is actually
                                                 a Java exception.

                                                 There is no class file
                                                 'HelloWorldApp.class' in
                                                 the current directory,
 You get a Java exception                        make sure that you are in
                                                 the right directory. This
 java.lang.ClassNotFoundException: HelloWorldApp error message is,
                                                 however, created by Java
                                                 itself, so Kaffe does not
                                                 know anything about this
                                                 (or any other) Java
                                                 exception.

 Kaffe signals an error:                         There is not enough
                                                 resources in your machine
 kaffe: threadlauncher failed                    to run Kaffe properly.
                                                 Thus you cannot run
                                                 native threads.

4.3. Problems with stack tracing in JIT-Kaffe

There are currently some extensive problems with the implementation of
JIT-Kaffe for Plan9 - error and exception handling does not work properly
in all situations. Stack tracing is nearly impossible when you compile your
program with Kaffe's JIT version. The problems are caused by Plan9:s
C-compiler 8c: stack tracing of native code is almost impossible, because
of some bugs or misfeatures in 8c which causes the 8c to produce incorrect
stack traces. You can, however, trace JIT-level code (java) until the first
native method is reached - after this the previously mentioned misfeatures
of 8c mess up the stack trace. Therefore we must recommend that when you
test programs with JIT and get strange errors and exceptions, you should
test the programs also with the interpreter (which does NOT mess up the
stack trace). In this way you will get a better picture of the errors and
exceptions.



5. Maintenance

5.1. Support

Kaffe for Plan 9 was originally created by the Bela Lugosi team as part of
their undergraduate studies at the Helsinki University of Technology. Bela
Lugosi can not and will not provide any support for any version of Kaffe,
Plan 9 or otherwise. We simply do not have the resources nor the enthusiasm
to take up this sort of responsibility.

Kaffe is supported by Tim Wilkinson and the Jolt project. You can locate
them at the Kaffe website (www.kaffe.org). However support for Kaffe for
Plan 9 will most probably not be extensive as it differs a great deal from
the mainstream ports of Kaffe. This is due to the special and often
peculiar nature of Plan 9.

5.2. Upgrading

Currently no new versions or updates are planned for Kaffe for Plan 9. The
project in which the original version was ported has ended. Bela Lugosi has
no further interests in pursuing the project.

However, upgrades might appear from other authors, based on this code or
otherwise. You can find these on the Kaffe website.

You are encouraged to study the source code and improve it. If you wish to
include your version on the Kaffe distribution, contact the Kaffe team at
the Kaffe website.

5.3. Reporting bugs

Bela Lugosi assumes no responsibility for helping users of Kaffe for Plan
9. Nor do we provide support or bug fixing. We can only direct you to the
Kaffe website for further assistance.

You find the bug, you fix the bug (tm) =)

5.4. Modifying Kaffe for Plan 9

Kaffe for Plan 9 is provided with the full source code (virtual machine and
Java native methods). You are free to change and improve to program. You
should note that certain copyrights (Tim Wilkinson's and the rest of the
Jolt project) apply to the software. Check the Kaffe website for details.

If you act decently, you are free to do almost anything you desire with the
source code.

6. References

[1] Tim Wilkinson: Kaffe - A virtual machine to run Java(tm) code. USA,
1997.
URL: <http://www.kaffe.org>

[2] Bai, Block, Germain, Rundel, Schumm: Kaffe guide. USA, 1997.
URL: <http://www.oasis.leo.org/java/machines/kaffe/00-index.html>

[3] Sun Microsystems: Java guide. USA, 1997.
URL: <http://java.sun.com>

[4] Lucent Technologies: Plan9 guide. USA, 1995.
URL: <http://plan9.bell-labs.com/plan9/>

[5] Oaks, Wong: Java Threads. O'Reilly, USA, 1997.

[6] Meyer, Downing: Java Virtual Machine. O'Reilly, USA, 1997.

[7] Mike Coleman: Speeding up Java. USA 1996.
URL: <http://chez-gnu.cstp.umkc.edu/~coleman/java_speedup/>

[8] javac - The Java Compiler; SYNOPSIS, DESCRIPTION and OPTIONS.
URL:
<http://java.sun.com/products/jdk/1.1/docs/tooldocs/solaris/javac.html>

[9] Bela Lugosi: The Kaffe for Plan 9 (in Finnish only).
URL: < http://www.hut.fi/~akuukank/oht/>


7. Glossary

All terms and acronyms used in this document are explained in the following
table.

Term               Explanation

API                Application Programming Interface.
AWT                Abstract Windowing Toolkit, The graphics library of the
                   Java language.
JDK                Java Development Kit or Java Developer's Kit, Sun's tool
                   for developing Java applications.
JIT                Just-in-time, compiling is applied to small parts of
                   code (e.g. methods) and it is delayed until it has to be
                   done.
VM                 Virtual machine (of Java in this document).


