Installation Instructions for Taurus JavaVM
===========================================

ALL PLATFORMS
~~~~~~~~~~~~~
The JDK version that the VM is built for is controlled by the JDK_VERSION macro
in engine/config.h.  As shipped, the VM will be built for JDK 1.1.8.  If you
wish to build for JDK 1.4 (Java 2) then you need to uncomment one line and
comment out another.  The top of the file should currently read:

    /* Define the JDK version to be used */
    #define JDK_VERSION 118
    /*#define JDK_VERSION 140*/

Change this to read:

    /* Define the JDK version to be used */
    /*#define JDK_VERSION 118*/
    #define JDK_VERSION 140

Note that at the present time, no other JDK version numbers are acceptable in
config.h, though the version of classes.zip or rt.jar that you use may not
exactly match these numbers. e.g. JDK 1.1.7A is know to work, even though the
macro JDK_VERSION is set to 118.


Windows 95/98/ME/NT/2K/XP
~~~~~~~~~~~~~~~~~~~~~~~~~
Project files are supplied for Microsoft Visual C++ 6.  These have been tested
with MSVC6 SP5.

To compile, open the workspace JavaVM.dsw.  Set either 'JavaVM - Win32 Release'
or 'JavaVM - Win32 Debug' to be the active configuration.  The select either
'Build->Build JavaVM.exe' or 'Build->Rebuild All'.  This will produce an
executable called JavaVM.exe in either 'win32\Release' or 'win32\Debug'
depending upon which configuration you selected.

To run, the executable need not be copied anywhere, just use the scripts in the
'bin' folder.  Note that the Release exeutable take priority over the Debug
version.  To make sure that the Debug version gets run, delete or rename the
file 'win32\Release\JavaVM.exe'.


Cygwin32
~~~~~~~~
The Makefile and sources are intended to be compiled using the GNU toolset.
GNU Make and either GCC 2.9x or 3.x need to be installed before compiling.

The Makefile and scripts are shipped ready for use with Cygwin and should
require no editing.  In the directory containing the Makefile type:

    % make
    
An executable called 'javavm' will now be built in a sub-directory called
'cygwin32' (from OUTDIR in the Makefile).

If you change the CFLAGS and LDFLAGS to do a debug build, then before compiling
type:

    % make clean

This will remove any old intermediate files.

The 'javavm' executable will be run from the cygwin32 directory, there is
no need to copy it anywhere.

If you wish to access the provided manual page, then you need to copy it from
docs/javavm.1 to /usr/share/man/man1/javavm.1.  Typing 'man javavm' will then
produce some help on the command line options and files used.


Linux x86
~~~~~~~~~
The Makefile and sources are intended to be compiled using the GNU toolset.
GNU Make and either GCC 2.9x or 3.x need to be installed before compiling.

As shipped, the Makefile is setup for Cygwin and needs to be edited.  Uncomment
the line which reads OUTDIR=linux-i386 and comment out the line which reads
OUTDIR=cygwin32:

    #OUTDIR=cygwin32
    OUTDIR=linux-i386

Similarly change the lines which read JAVAVM= to give:

    #JAVAVM=javavm.exe
    JAVAVM=javavm

The release build CFLAGS can be left as they are (do not use -O2 or -O3 as
a bug in the compiler optimizer prevents the code from working).

Make sure that the LDFLAGS line that is uncommented reads:

    LDFLAGS=-O1 -lm

As the Maths library is needed under Linux.  Save the edited Makefile.

Edit bin/java so that the PLATFORM= lines read:

    #PLATFORM=cygwin32
    PLATFORM=linux-i386

Save the edited script.  You are now ready to compile.

From the directory containing the Makefile, type:

    % make

An executable called 'javavm' will now be built in a sub-directory called
'linux-i386' (from OUTDIR in the Makefile).

If you change the CFLAGS and LDFLAGS to do a debug build, then before compiling
type:

    % make clean

This will remove any old intermediate files.

The 'javavm' executable will be run from the linux-i386 directory, there is
no need to copy it anywhere.

If you wish to access the provided manual page, then you need to copy it from
docs/javavm.1 to /usr/share/man/man1/javavm.1.  Typing 'man javavm' will then
produce some help on the command line options and files used.


RISC OS
~~~~~~~
The source files can currently only be compiled with GCC r2.

Due to the incompatibilites between the Acorn file naming system and that used
by Unix, the file hierachy needs to be adjusted before you can compile the
code.  To do this, let us look at how the files are currently organized:

    /src
        /engine
            config.h
            engine.c
            ...
            Makefile.RISCOS
            ...
        /main
            main.c
            Makefile.RISCOS
            native-io.c
        /native
            java_io_File.c
            java_io_File.h
            ...
            Makefile.RISCOS
            ...
        /zip
            java_util_jar_JarFile.c
            java_util_jar_JarFile.h
            ...
            Makefile.RISCOS
        Makefile
        Makefile.RISCOS

The files named Makefile.RISCOS need to be renamed to Makefile and any existing
Unix Makefiles deleted or renamed out of the way.  Then the headers and sources
need to be split into directories called 'h' and 'c' respectively and the file
extensions removed.  You also need to create a directory called 'arm' at inside
'src'.  The result should look something like this:

    /src
        /arm
            o/
        /engine
            h/
                config
                ...
            c/
                engine
                ...
            Makefile
        /main
            c/
                main
                native-io
            Makefile
        /native
            c/
                java_io_File
                ...
            h/
                java_io_File.h
                ...
            Makefile
        /zip
            c/
                java_util_jar_JarFile
                ...
            h/
                java_util_jar_JarFile
                ...
            Makefile
        Makefile

You should then be able to build using 'make' with no arguments.  This will
compile all the sources and write a executable called 'javavm' into the 'arm'
directory.  Copy 'javavm' into the 'arm' folder of your '!JavaVM' directory.

Note if you have access to a PC with either Cygwin or Linux on it, you can
use the GNU Makefile supplied to rename all the files and build a tar file
which you can use on your Acorn machine.  To do this type:

    % make riscos-tar

This will create a file called riscos.tgz, containing just the files needed for
RISCOS, which can be copied to a floppy or over the network.


Epoc32 Release 5 (e.g. Psion Series 5)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These instructions are for the older Epoc32 Release 5, which was usually
referred to as the Epoc32 SDK.

Create a folder called 'javavm' at the top level of your Epoc32 SDK
installation.  This is the project directory.  Create another folder, also
called 'javavm' inside this.  This is the sub-project directory.  Extract the
sources into the sub-project directory and rename 'javavm-ER5.mmp' to
'javavm.mmp' (removing or renaming any existing 'javavm.mmp'), so that you have
the following structure:

    /Aiftool
    /Aleppo
    /EPOC32
    /javavm
        /javavm
            /engine
            /main
            /native
            /zip
            javavm.mmp
            
On my machine I have mapped the Epoc32 SDK installation to S:.  So unless your
installation is in the top level directory of a drive, use the drive letter you
have mapped your installation to in the following command.

Cd to 'S:\javavm\javavm' and type

    doebld.bat javavm WINS REL
    
This will compile a release build for WINS (the emulator).

This can then be run with:

    S:\EPOC32\Release\WINS\Rel\JAVAVM.EXE <classname>

You should see the Symbian window come up and JavaVM will run in a shell window
with a blue background.  When the program completes, you will be asked to
"press any key", which will close the emulator window.

To build for the Psion itself use:

    doebld.bat javavm MARM REL

This will build an exe in S:\EPOC32\Release\MARM\Rel, which you can copy to
your Psion to run.  Note that on debug builds, the compiler currently produces
a lot of warnings of the form:

  <file>:<lineno>: warning: unsigned int format, long unsigned int arg (arg 3)
  
These are benign, but for the curious, they relate to the format specifiers in
printf statements (mainly used for debugging) - in the example above we have a
'%x' in the printf, which the compiler expects to be an unsigned int, but an
unsigned long is being passed.  As C does not have a format specifier for long,
there is no simple way to fix these messages!  They can however be safely
ignored.
  
On WINS release builds you may instead see warnings of the form:
 
  warning C4710: function 'xxx' not inlined

These can be ignored as the WINS build environment does not support inlining of
functions (at least with the Standard Edition of the compiler).


Epoc32 Release 6 (e.g. Psion Netbook)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These instructions are for Epoc32 Release 6 (a.k.a. Symbian 6.1).

From the folder where you unzipped the JavaVM sources, you first need to build
the batch file which controls the build process.  First ensure that the Symbial
Tools folder is in your path.  Then we use bldmake.bat to operated on the
project files listed in Bld.inf - in our case just javavm-ER6.mmf:

    bldmake.bat BLDFILES
    
This should generate a new batch file called ABLD.BAT.  It is this batch file
which controlls the build process.  It is run in a similar way to the ER5
doebld.bat, but does not take a project name:

    ABLD.BAT BUILD WINS

This will build both the UDEB and UREL versions of the  executable for use with
the Emulator.  To build the UDEB version only you would use:

    ABLD.BAT BUILD WINS UDEB
    
Substitute UREL for UDEB to build the release version.

On my machine the Symbian SDK is installed on D:, so to start the VM executing
a particular class, I would use:

    D:\Symbian\6.1\Quartz\Epoc32\Release\wins\udeb\JAVAVM.EXE <classname>

The Symbian emulator window should pop up and you should see some output from
the JVM.

To build for an Epoc32 device you would use:

    ABLD.BAT BUILD ARMI

Where ARMI could be substituted for ARM4 or THUMB depending upon your device.
This will build an exe in S:\EPOC32\Release\MARM\Rel, which you can copy to
your Psion to run.  Note that currently the compiler produces a lot of warnings
of the form:

  <file>:<lineno>: warning: unsigned int format, long unsigned int arg (arg 3)
  
These are benign, but for the curious, they relate to the format specifiers in
printf statements (mainly used for debugging) - in the example above we have a
'%x' in the printf, which the compiler expects to be an unsigned int, but an
unsigned long is being passed.  As C does not have a format specifier for long,
there is no simple way to fix these messages!  They can however be safely
ignored.
  
On WINS release builds you may instead see warnings of the form:
 
  warning C4710: function 'xxx' not inlined

These can be ignored as the WINS build environment does not support inlining of
functions (at least with the Standard Edition of the compiler).
