The following release notes are applicable to the above version of the Taurus Java Virtual Machive. The copyright notice is applicable to any version of the VM unless stated otherwise.

Copyright notice
The Taurus Java Virtual Machine is © Copyright 2003, Taurus Software.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The Taurus Java Virtual Machine has been produced, as a "clean room" implementation, in accordance with Sun Microsystems, Inc's (SUN) licence agreement for "The Java™ Virtual Machine" specification. Also, in accordance with this agreement the virtual machine distribution does NOT, to the author's knowledge, contain ANY material which is copyrighted by SUN. As such the class files relied upon by the virtual machine must be obtained separately, directly from SUN. The use of this specifcation does not in any way imply that the software conforms to it, nor does it imply that it will ever wholey do so. The Taurus Java Virtual Machine does not, and will not, ever pretend to be "Java-compliant", it will always remain as closer approximation as time and money will allow. Users of this software do so at their own risk. Developers of any Java software should NEVER use this as a reference platform.

Taurus Java Virtual Machine is a trademark of Taurus Software. Sun, Sun Microsystems, the Sun logo, Java, JavaSoft, Personal Java, Embedded Java, KVM and Java 2 Micro Edition are all trademarks or registered trademarks of Sun Microsystems, Inc. All other product names mentioned herein are the trademarks of their respective owners.

All references to Taurus Software directly refer to the non-profit freeware/shareware software development unit run from the UK by myself. Any conflict with names of companies inside or outside of the UK is unintentional and should be disregarded.

Platform Support
The Taurus Java Virtual Machine version 1.06 alpha is provided as binaries for the following platforms:

• Win32 - should work with any i386 based Microsoft Windows™ OS (95/98/ME/NT/2K/XP)
• Linux-i386 - any i386 based Linux™ distribution
• Cygwin - Cygwin running on Win32
• RISC OS - Archimedes or RISC PC running Acorn RISC OS 3.10 or later

For space reasons is provided without any of the required support libraries (DLLs, .so or RMs). In order to run this software you must install these libraries yourself (they are likely to be already installed on most systems). Binaries for other platforms may follow at some later date.

Java Support
This alpha release provides an incomplete implementation of the SUN Java Virtual Machine Specification 1.0. The key features of this release are as follows:

• Loading and execution of Java applications - the VM should be able to load and begin executing any Java application.
• Dynamic loading - classes are loaded as needed, exceptions or errors are reported when a class cannot be found
• Can interpret almost all Java virtual instructions - all the common instructions used by large programs like the javac and javadoc have been implemented.
• Can read and write files on disk.
• Support for exceptions - most exceptions generated by the VM can be caught, all exceptions generated by user code can be caught. All Java exceptions support the stack trace facility.
• Runs with standard JDK classes - there are no modified class files used by the VM. (SIBO and DOS versions do use modified classes).
• Debug at method, instruction and exception level is supported. Any serious VM problemsc(access violations) should generate a Java stack trace.
• Complete virtual instruction set implementation - 100% of the virtual instructions have been implemented, though one or two are dummy implementations.

The main restrictions are as follows:

• Non-conformant arithmetic implementation - the VM uses its own internal format (that of C) to represent numbers on the stack. In particular floating-point numbers may not behave quite correctly for NaN, +Inf and -Inf. Also beware of bitwise logic on large numbers, as shifts etc. may not be 100% correctly implemented.
• Incomplete native method implementation - only those native methods which have been encountered in pratice (about 18%) have been implemented. This leaves a lot of unimplemented native methods, including those native methods which fall outside the core implementation, namely those found in the "winawt", "net" and "zip" libraries. No attempt has been made to support the Java Native Interface (JNI) specification, though the code has been designed to make support a possibility in the future.
• Single thread of execution - multi-threading may be added in the form of "green" threads in a later release. Native threads are unlikely to be supported as the smaller target platforms do not support threading.
• No AWT - the standard Java AWT classes require far too much native support and are tied too closely to the host platform for implementation in a truely "portable" VM. Mechanisms to implement the AWT may be provided in a later release.
• No Networking - as with the AWT, the standard java.net classes require a lot of native support. Mechanisms to implement networking may be provided in a later release.
• No Garbage Collector - due to the complexity of GC, its implementation has been left until a later release. It is likely to be necessary to adopt a smarter GC technique in order to allow the Java VM to run on really small platforms.
• No JIT - a performance enhancing JIT may be added later. The development of a JIT is difficult and ties the VM to a host platform. JITs are also a complex technology to develop and even some of the commercial Java vendors still haven't got it quite right!
• Limited refelection interface - reflection is limited to obtaining handles of classes, super-classes and fields (for serialver) Support for interrogating class definitions has been omitted.
• No support for CLASSPATH - only a single directory (or on some platforms, the current directory) is checked for class files.
• No support for Applets or sandbox - at the moment the VM must be run as a stand-alone application.

Support for "Standard Applications"
Below is a table of the "standard Java applications", which come with most JVM's. They are all written in Java, so should run on any virtual machine. As a simple test of the Taurus Java VM, here is what happens when they are run with the scripts provided:

Installation
The Taurus JavaVM is shipped as an archive (usually ZIP) without the standard class files. If you haven't done so already, you need to download a copy of JDK 1.1 from java.sun.com. Pick the latest 1.1 release.

Win32, Linux and Cygwin
Create a suitable directory (e.g. C:\JavaVM or /home/robert/javavm), and unpack the downloaded ZIP file containing the VM into this directory.

Next install the class files from the JDK 1.1.x - these come packed as a zero compression Zip file called classes.zip, approx 8Mb in size. You need to unpack this directly into your JavaVM lib directory (You may need to create this, if there isn't one already).

RISCOS
Unpack the downloaded ZIP file using !ZipEE or similar into a suitable directory e.g. $.Apps. This will create an !JavaVM application directory containing the necessary files.

Next install the class files from the JDK 1.1.x - these come packed as a zero compression Zip file called classes.zip, approx 8Mb in size. You need to unpack this into $.Classes (unlike !JavaVM, this cannot be moved anywhere else). You then need to rename all the files to remove the .class file extensions.

Running
Running JavaVM is very simple, and it is designed to be run in a similar way to other virtual machine implementations.

Win32, Linux and Cygwin
To run the VM you must either add JavaVM's bin directory to your path, or if you have other VM's installed, you must cd to this directory and type, for example, .\java (Win32) or ./java (Cygwin and Linux).

To run your own programs, you must place your .class files in the lib directory along with the standard Java classes.

RISC OS
Before you can run the VM under RISC OS, you must first double-click the !JavaVM application. This doesn't actually launch an application, it just sets up various environment variables, adds the VM's bin directory to you path and loads the appropriate modules.

To actually run the VM, open a Task Window (Ctrl+F12). As with most large programs, you need to increase the wimpslot of the task with wimpslot -min 3000k for example. Larger programs will need a bigger wimpslot. The VM is then run by typing, for example, java, in the same manner as other platforms.

To run your own programs, you must place your .class files in the $.Classes directory along with the standard Java classes.

Testing the VM
To make sure that the VM is setup properly and that you are running the right VM (if you have more than one installed), run the VM with the -version switch. This should result in something similar to the following:

robert@odie$ ./java -version
java version "1.1"
Taurus Java Virtual Machine CYGWIN32 v1.0.6a DBG
(C) Copyright 2001, Taurus Software

If you don't get this, or you get a similar message which does not contain the word "Taurus", then check your path, or make sure you are using .\java -version (Windows) or ./java -version. On RISC OS make sure you have double-clicked !JavaVM.

Minimum requirements
The VM can function in a much smaller environment than provided by the JDK classes. If you wist to implement your own "standard" classes, then the VM really only needs the following classes and methods to function:

It is also advisable to include the following error/exception classes, as they can be raised directly by the VM (either in response to class-loading or by being thrown by native method implementations):

To make your own environment, you need to implement a set of Java classes similar to those provided by Sun. The main reason for doing this on a small platform is the amount of crap that gets loaded before any of your classes. I am currently looking at the Personal Java and Embedded Java specifications for some ideas on how to shrink the VM - Just using System.out loads an awful lot of classes!