http://www.hut.fi/~akuukank/oht/documents/ko.html
Last updated 23.3.1998.
Authors: Jussi Laakkonen (11.2.1998), Vesa Kärpijoki (23.3.1998)
Verifiers: Vesa Kärpijoki (23.3.1998), Teemu Ikonen (12.2.1998),
Jari Kytöjoki (15.2.1998), Jussi Laakkonen (23.3.1998),
Arttu Kuukankorpi (23.3.1998)
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 - Introduction | The first section gives a short introduction to the Kaffe for Plan 9 package and its background. |
Section 2 - Installation | This section gives full instructions of how to install and configure the Kaffe for Plan 9 package for your system. |
Section 3 - Functions | The section 3 discusses the use of the software and gives also a short example of a typical Kaffe compilation. |
Section 4 - Problem situations | This section describes the problems that the reader may encounter with Kaffe. The section gives solutions to some trivial problems. |
Section 5 - Maintenance | The fifth section discusses about how the Kaffe for Plan 9 is supported and how you can modify the source code. |
Section 6 - References | This section lists the references (most of them are 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 |
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.
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.
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.
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 |
The system you are installing Kaffe for Plan 9 package into has to fill these requirements:
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.
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:
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.
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.
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.
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!
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 |
NOTE: the input given by the user is printed with
bold fixed fontand output given by Kaffe are is printed with
non-bold fixed font.
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.
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.
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.
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!
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].
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 |
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.
Typical problems and their possible solutions are listed in the following table:
Problem | Possible solution |
You get error message from Plan 9 kaffe: file does not exist |
The environment variable PATH is not set in Plan 9. See Plan 9 manuals in references section for further information. |
Kaffe gives an error message CLASSPATH is not set! |
The CLASSPATH environment variable is not set at all. Consult to section 2.2. for further assistance. |
Kaffe signals an error Cannot find essential class 'java/lang/Object' in class library ... aborting |
The CLASSPATH environment variable has been given a wrong value. Therefore Kaffe cannot find the essential JDK class package 'classes.zip' and it is not able to load the necessary base classes. Consult to section 2.2. for further assistance. |
Kaffe signals an error Bad magic acdc1234 in class |
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 does not verify the bytecode in any way, so 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. |
You get a Java exception
java.lang.ClassNotFoundException: HelloWorldApp |
There is no class file 'HelloWorldApp.class' in the current directory, make sure that you are in the right directory. This 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:
kaffe: threadlauncher failed |
There is not enough resources in your machine to run Kaffe properly. Thus you cannot run native threads. |
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 |
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.
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.
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) =)
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). |
8. Index |