This file contains important information you will need to know if you are going to write an interface between GNU Classpath and a Virtual Machine.

Copyright (C) 1998-2001 Free Software Foundation, Inc.

GNU Classpath Hacker's Guide
****************************

This file contains important information you will need to know if you are going to write an interface between GNU Classpath and a Virtual Machine.

This document is incomplete, as we are still in alpha with the interface.

Introduction
************

The Classpath Project's ambition to be a 100% clean room implementation of the standard Java class libraries cannot be fulfilled without some level of integration with the Virtual Machine, the underlying machinery that actually runs Java.

There are several VMs out there, here is a small list.

  * Japhar (http://www.japhar.org) Japhar was the first VM to use GNU Classpath.  Today you can see that sort of relationship in the source tree which denotes several Japhar specific files as a reference implementation of those pieces.  This VM has been primarily tested against Linux and lacks garbage collections, a JIT, and suffers recently from slow development.

  * Intel's Open Runtime Platform (http://www.intel.com/research/mrl/orp/) Intel surprised us not long ago with the release of this rather advanced VM that uses GNU Classpath for a set of class libraries and works on Linux and Windows 2000.

  * SableVM (http://www.sablevm.org/) The goal of this project is to build an efficient Java virtual machine in C for the GNU/Linux operating system. SableVM implements the Java virtual machine specification, second edition, and like the Intel VM includes a special version of the GNU Classpath libraries.

  * Kaffe (http://www.kaffe.org) Kaffe is an advanced VM and together with its own class libraries provides a Java 1.1 compatible environment.

  * Electrical Fire (http://www.mozilla.org/projects/ef) The Electrical File VM continues to be listed as a Mozilla project though development has been somewhat quiet.  A number of concepts from EF were expected at one point to be rolled into Japhar, but that development has not occured as of yet.

  * LaTTe (http://latte.snu.ac.kr/) This VM project so far supports only Sun UltraSparc processors using the proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived from Kaffe but claims a number of improvements.

  * GNU Compiler for Java (GCJ) (http://gcc.gnu.org/java/) This is a portable, optimizing, ahead-of-time compiler for the Java Programming Language. It can compile Java source code directly to native machine code, Java source code to Java bytecode (class files), and Java bytecode to native machine code. Compiled applications are linked with the GCJ runtime, libgcj which is based on the GNU Classpath code, which provides the core class libraries, a garbage collector, and a bytecode interpreter. libgcj can dynamically load and interpret class files, resulting in mixed compiled/interpreted applications. GCJ is part of the GNU Compiler Collection (GCC (http://gcc.gnu.org/)). On march 6 2000 the libgcj and GNU Classpath projects were officially merged and there is active work on merging all the classes between the projects.

  * Kissme (http://kissme.sourceforge.net/) This is a free Java Virtual Machine that is being developed on GNU/Linux and can run console java applications.  kissme also provides support for orthogonally persistent java.

In the past integration efforts were focused mainly on Japhar with an eye towards getting Electrical Fire to work.  Most information contained in this document is gleaned from these efforts. Recently more work has been done on getting gcj, orp and kissme to work out of the box with GNU Classpath but there is much to do before that becomes a reality.

Initialization
**************

The order of initialization, as far as I can tell, doesn't matter just yet.  However, when we move to 1.2 support, it probably will matter, so we'll have a note in here at that time.

Classpath Hooks
***************

Several core classes must be implemented by the VM for Classpath to work.  These classes are:

  * java.lang.Class

  * java.lang.Runtime

  * java.lang.Thread

  * java.lang.Throwable

  * java.lang.reflect.Constructor

  * java.lang.reflect.Method

  * java.lang.reflect.Field

You also need to implement some helper classes in java.lang that classes from Classpath call out to to get certain VM-specific dirty work done:

  * java.lang.VMObject is the bridge between the low level Object facilities such as makeing a clone, getting the class of the object and the wait/notify semantics.

  * java.lang.VMClassLoader provides methods for defining and resolving core and primitive classes.

  * java.lang.VMSystem is used to initialize the System properties, the System.arraycopy method and the identityHashCode of an Object.

  * java.lang.VMSecurityManager provides the class context (stack trace) of the currently executing thread and a way to get the currently active ClassLoader.

Some of the classes you implement for the VM will need to call back to package-private methods in Classpath:

  * java.lang.ThreadGroup.addThread(Thread) Call this method from Thread when a new Thread is created, to add it to the group.

  * java.lang.ThreadGroup.removeThread(Thread) Call this method from Thread when a Thread is stopped or destroyed.

VM Hooks
********

VMs need to do some dirty work; there are some things in the VM that unfortunately are dependent on the internal structure of various classes.  This is a guide to all of the things the VM itself needs to know about classes.

  * java.lang.Class
     You, the VM, get to create this Class, so you may define the internal structure any way you wish.  You probably have code somewhere to translate your internal class structure into a Class object.  That is the only known place where this matters.  Some VMs do not create the Class object at the point where the class is defined; instead, they wait until a Class object is actually used.

  * Array Classes
     When you are creating an array class, you should set the ClassLoader of the array class to the ClassLoader of its component type.  Whenever you add a class to a ClassLoader, you need to notify the ClassLoader and add the new Class to its internal cache of classes.  To do this, call ClassLoader.addVMCreatedClass(Class).  Note: this is written in anticipation of 1.2 support and does not apply just yet.

  * Primordial Class Loader
     When the primordial class loader loads a class, it needs to tell Classpath what it has done in order for security stuff to work right. To do this, call the static method ClassLoader.newPrimordialClass(Class).

     Even the first few core classes need to do this; in order to do it, simply call this method after the initial class loading has been done.  No harm will come, as long as you follow the guidelines in the see Initialization section.

     Note: this is written in anticipation of 1.2 support and does not apply just yet.

  * java.lang.Throwable (Classpath 0.02)
     The VM may choose to implement this class in whatever fashion it would like.  If you choose to use the reference implementation, then you must define two functions within some library and change Throwable.java to load your library.  The two functions are printStackTrace0(Object), and fillInStackTrace().

  * Top-level Exception Handler
     Exceptions take care of themselves in Classpath; all you need to do in the top-level exception handler is call Throwable.printStackTrace().

     XXX I think this was a bad design on my part.  It takes up memory and CPU cycles that do not need to be taken up for exceptions which are simply caught.  This portion of the VM interface will be changed so that VMs must associate native stacktrace data with the Throwable itself or even do some sort of lazy stacktrace information addition to the Throwable, only copying stacktrace data as it is lost (as functions are exited) to preserve memory and cycles.  The usual case is the one where an exception is caught.  The top-level exception handler is, well, an exception among exceptions.

  * Security and Traces
     There will eventually be a feature in the 1.2 security that keeps the AccessController from having to evaluate all of the ProtectionDomains every time a security check is made.  I think a common case is a single method doing a lot of things that require security checks.  However, I don't want to bog down the method stack too much, so this feature of the VM will have the AccessController for a thread calling out to the VM to tell it how high it was on the stack when it made the last security request.  Every time the stack goes lower than that number, the VM will decrement the number.  The AccessController will remember what the accumulated protection status was at every stack level (an AccessControlContext) and use that aggregated information to do the check.  I am not sure, however, whether the savings are substantial enough to outweigh the integer check and set after every method call.  I will investigate.

  * Threading
     I figured I'd put this here because a VM guy might be wondering about it. We implement ThreadGroup, but that class is almost entirely VM-independent.  The root ThreadGroup, a static field called ThreadGroup.root, should be initialized by Classpath, but if you wish to reinitialize it yourself, there should be no harm.