Jamaica Virtual Machine and Java Compiler
=========================================

(c) 1999-2005 aicas GmbH
              Hoepfner Burg
              Haid-und-Neu-Straße 18
              D-76131 Karlsruhe
              Germany
              http://www.aicas.com
              info@aicas.com

Legal:
  Before using this software, read the LICENSE file 
  carefully which explains your right and duties when
  using this product. If you don't want to accept the license, please
  remove all Jamaica files from your system.
  

System requirements:

 Solaris: 
  - On Solaris: Solaris >= 5.6 (pthread support)
  - gcc installed and in PATH
  - GNU make installed and in PATH

 Linux:
  - On Linux: Linux >= 2.2
  - gcc 2.95 resp. 3.3 installed and in PATH
  - GNU make installed and in PATH
  - libc version 6 or newer

Having a java Compiler like javac or jikes in your classpath is
useful, since Jamaica operates on CLASS files, not on java source
code.


Working with JamaicaVM and the Eclipse-IDE:
  An Eclipse plugin for the JamaicaVM and the JamaicaVM Builder tool 
  is available at http://www.aicas.com/eclipse.html. For a quick
  download and installation, use the Eclipse Update Manager with the 
  following Update Site URL: http://www.aicas.com/download/eclipse/3.0
  For more information on Eclipse see: http://www.eclipse.org.


Installation:

Jamaica is delivered in several package formats, depending on the
system that you want to use:

 Linux (RPM format):

  - download the RPM file (Jamaica-*-*-*.rpm), where * is the
    Jamaica version number and *-* your operating system and processor
    architecture.
  - become root:
	su
  - install Jamaica:
	rpm -i Jamaica-*-*-*.rpm


 SUN Solaris (pkg format):

  - download the pkg file (Jamaica-*-solaris-2.8-sparc.pkg.Z)
  - uncompress the pkg:
	uncompress Jamaica-*-solaris-2.8-sparc.pkg.Z
  - become root:
	su
  - install Jamaica:
	pkgadd -d Jamaica-*-solaris-2.8-sparc.pkg
  - Select Jamaica by typing '1' or just hitting ENTER.


 ANY System (Tar ball format):

  - download the Tarball (Jamaica-*-*-*.tar.gz), where * is the
    Jamaica version number and *-* your operating system and processor
    architecture.
  - uncompress the Tarball:
	gzip -d Jamaica-*-*-*.tar.gz
    (Note: gzip may not be available on your system. In that case, you
     can either download it (e.g., at http://www.leo.org or
     http://www.tuxfinder.com) or choose another package format for
     your system.)
  - untar Jamaica:
	tar xfv Jamaica-*-*-*.tar
  - become root:
	su
  - install Jamaica:
	./Jamaica.install

  
 The install directory is /usr/local/jamaica.


Deinstallation:

  If you really want to deinstall Jamaica, proceed as follows:

 Linux (Jamaica was installed via RPM):

  - become root:
	su
  - deinstall Jamaica:
	rpm -e Jamaica


 Solaris (Jamaica was installed via pkgadd):

  - become root:
	su
  - deinstall Jamaica:
	pkgrm Jamaica


 Any platform (Jamaica was installed via Tarball and Jamaica.install
               skript):

  - become root:
  - deinstall Jamaica:
	/PATH/TO/DEINSTALL/SKRIPT/Jamaica.remove
    (where /PATH/TO/DEINSTALL/SKRIPT is the directory where you
     untared Jamaica during installation.)


Documentation:

  Please refer to the documentation at /usr/local/jamaica/doc/html/index.html.

  
Quick Start:

  There is an example HelloWorld.java in the subdirectory
  target/HOST_TARGET/examples. You execute it as follows:

   > cd /usr/local/jamaica/target/HOST_TARGET/examples/HelloWorld
     (where HOST_TARGET is the name of your host target, e.g.: 
      'linux-gnu-i686')
   > make classes/HelloWorld.class
     (using the provided Makefile to compile the class)
   > jamaicavm -classpath classes HelloWorld
                 Hello        World!
              Hello       World!
           Hello     World!
        Hello    World!
      Hello   World!
    Hello  World!
   Hello World!
   Hello World!
   Hello World!
   [...]

  This run used the JamaicaVM and loaded class files using the 
  CLASSPATH variable. Next, we can create a standalone executable,
  i. e., pack all the classes of HelloWorld into one binary file that
  can be executed without the need to load class files. Using the 
  provided Makefile type:

   > make HelloWorld
   Jamaica Builder Tool 272 Release 8
   Generating code for target 'linux-gnu-i686', optimization 'speed'
    + tmp/HelloWorld__.c
    * C compiling
    * linking
   Class file compaction gain: 95.8409% (1729988 ==> 71952)
   > ./HelloWorld
                 Hello        World!
              Hello       World!
           Hello     World!
        Hello    World!
      Hello   World!
    Hello  World!
   Hello World!
   Hello World!
   Hello World!
   [...]

  During this process, the class files were compacted, so that the 
  executable's size is reduced. Further the option -smart was used
  to remove any code that never will be executed.
  Chapter 7 'Performance Optimization' of the JamaicaVM User Documentation 
  describes in detail how to further reduce code size and improve 
  performance.


Most important Options of the builder:

  -help

  -smart        Enable smart linking
 
  -compile      Enable the compiler

  -heapSize     Set the size of the heap (eg. -heapSize 32m)

  -numThreads   Select how many threads should be useable
                at the same time.


Cross Compiling:

If your host environment architecture differs from your target
environment architecture, you need a C cross compiler installed on
your system and a Jamaica distribution that supports this
architecture. To see a list of all supported architectures of your
distribution, type
	jamaica -XavailableTargets

To generate code for a certain architecture, use the -target option of
the jamaica command. The target "host" is always available.
	jamaica -target host Whatever
builds a ROM image of the class Whatever that can be executed on the
host environment.


Bug reports:

  Please send them to info@aicas.com. 
  
Have fun!