Kaffe for Plan 9
================

kaffe-plan9.tar.Z is a restored Kaffe 0.9.2 port for 9legacy/386.
The original port was produced by the Bela Lugosi student team at Helsinki
University of Technology in 1998.  This restoration repairs the interpreter,
JIT, native Java 1.1.3 services, build files and demonstrations, and adds a
JNI 1.1 interface and kaffeh header generator.

This release is intended for historical research, education and small trusted
Java 1.1 programs.  It is not a modern or security-hardened Java runtime.  It
is headless: the Sun AWT peer implementation is not present.

Files
-----

kaffe-plan9.tar.Z
    Restored source tree and Plan 9/386 interpreter, JIT and kaffeh binaries.

sha256
    SHA-256 checksum for kaffe-plan9.tar.Z.

The archive extracts as kaffe/.  It contains no Java class library.

Java 1.1.3 classes.zip
----------------------

An Oracle account and acceptance of Oracle's license are required.  Download
the Solaris/SPARC JDK 1.1.3 file named jdk1.1.3-solaris2-sparc.bin from:

https://www.oracle.com/java/technologies/java-archive-downloads-javase11-downloads.html

Expected installer:

    size:    9666882 bytes
    SHA-256: 6dd68372489a35a5026a5ee0080a697544c98da0e53271b84f2f01efa729b109

On a system with bsdtar, extract only the class library:

    bsdtar -xOf jdk1.1.3-solaris2-sparc.bin \
        jdk1.1.3/lib/classes.zip > classes.zip

Expected classes.zip:

    size:    9359091 bytes
    SHA-256: 0a0bfd6cc3bebed848b9f88f16fbd6f934fca398b0a50cbc55c3e1a6f531cfbd

Copy it to kaffe/classes.zip.  Do not redistribute it with Kaffe.

Extract and run
---------------

On 9legacy/386:

    tar xzf kaffe-plan9.tar.Z
    cd kaffe

Confirm that the supplied Plan 9/386 binaries start:

    kaffeintrp/src/kaffe -version
    kaffejit/src/kaffe -version

The final lines should report:

    Engine: Interpreter   Version: 0.9.2   Java Version: 1.1.3
    Engine: Just-in-time   Version: 0.9.2   Java Version: 1.1.3

These commands check the executables.  The following compilation and run
also check classes.zip and Java execution.

Compile and run Java with the interpreter:

    cd kaffeintrp/test/regression
    CLASSPATH=../../../classes.zip:.
    ../../src/kaffe sun.tools.javac.Main HelloWorldApp.java
    ../../src/kaffe -verify HelloWorldApp

Run the same class with the JIT:

    ../../../kaffejit/src/kaffe -verify HelloWorldApp

Return to the kaffe directory and run the compact interpreter or JIT
demonstration:

    cd ../../..
    rc kaffeintrp/test/run-demo.rc
    rc kaffeintrp/test/run-demo.rc . jit

Each command builds its engine and checks Hello World, child processes,
threads and the original HTTP handler.  The HTTP test accepts three requests
on port 18080 and stops automatically; no server needs to be killed manually.
The HTTP server and handler come from the original 1998 Plan 9 port.
The final line should be:

    demo summary: 4 pass, 0 fail

Build from source
-----------------

    cd kaffeintrp/src
    mk
    cd ../../kaffejit/src
    mk
    cd ../../kaffeh
    mk
    cd ..

Optional per-user commands
--------------------------

When the extracted tree is `$home/kaffe`, Plan 9 normally adds
`$home/bin/386` and `$home/bin/rc` to `/bin`.  Copy the three programs and
the compiler wrapper there if command names are more convenient than paths:

    cp kaffeintrp/src/kaffe $home/bin/386/kaffe
    cp kaffejit/src/kaffe $home/bin/386/kaffe-jit
    cp kaffeh/kaffeh $home/bin/386/kaffeh
    cp kaffeintrp/scripts/javac $home/bin/rc/javac

Set the class path once in the interactive shell:

    CLASSPATH=$home/kaffe/classes.zip:.

Compile the included Hello World source and run it with either engine:

    cd kaffeintrp/test/regression
    javac HelloWorldApp.java
    kaffe -verify HelloWorldApp
    kaffe-jit -verify HelloWorldApp
    cd ../../..

JNI example
-----------

The example calls Plan 9 C from Java and returns a Java String.  With the
optional commands above installed, copy the example into a separate project
directory:

    cd $home
    mkdir kaffe-jni-example
    cp kaffe/jni/examples/* kaffe-jni-example
    cd kaffe-jni-example
    javac HelloJNI.java
    kaffeh -classpath $CLASSPATH -jni HelloJNI
    8c -T -w -I$home/kaffe/include -o HelloJNI.8 HelloJNI.c
    8l -x exports -u -o hello.dyn HelloJNI.8

Run it with the interpreter and then the JIT:

    kaffe -verify HelloJNI
    kaffe-jit -verify HelloJNI

Each engine should print:

    Hello from JNI

Generated files may be removed with:

    rm HelloJNI.class HelloJNI.h HelloJNI.8 hello.dyn

Provenance
----------

Original 1998 archive:

https://web.archive.org/web/*/http://www.hut.fi/~tikonen/plan9/kaffe-plan9.tar.Z

Original archive payload SHA-256:

    51f56865cee11d4f6c87d64ffd86a04aba1602c20831b72865deb51909582a93

Restored kaffe-plan9.tar.Z SHA-256:

    a663c8b6e39dbbaa36f10cc98a41357c18d932baef204fd9d7f3e0e6f7b5ff40