!Help file for RISC OS guavac, version 1.2, release 1
April 4th, 2003

This is guavac, the GNU Java source file compiler, ported to RISC OS
by Peter Naulls (peter@chocky.org).

guavac is an alternative to javac, the JDK Java compiler.  Since guavac
is written in C++, rather than Java like javac, it is much faster.

guavac is now part of the Unix Porting Project, and support is only
offered to subscribers.  See:

http://www.chocky.org/unix/


Changes in version 1.2 (release 1)

Updated to newer 1.2 version.
Made 32-bit



Changes since release 1.2

 * If the -cp flag is used (additional classpath directory), the directory
   specified becomes the base for the output directories rather than
   the CSD. 

 * Much improved handling of classes in subdirectories and packages.

 * Fixes for some incorrect calcuations in constant folding situations.

 * Fix for a floating point exception with division by zero.

 * Additions to the FrontEnd.


Changes since release 1.1a

 * Fixed "Numeric overflow" for long values.

 * The source filename would appear wrongly in some throwback situations,
   this has been fixed.

 * A Frontend is now included.  Thanks to Jon Wright for this.


Changes since release 1.1

 * Added some example Java programs to the archive.

 * Fix for RISC OS 3.5 and 3.6 users who do not have the CallASWI module
   loaded.


Changes since release 1.0

 * guavac will now load the library classes (!Guavac.class/zip) regardless
   of whether it is an image file or not, so you are free to have it as
   an archive (filetype &DDC) and open it if you wish.  Note that you
   shouldn't have library files used by Acorn's Java as an image file,
   as this will confuse !Java.

 * guavac correctly finds classes in the CSD. It will also load classes
   if they do not have the "/class" extension.

 * The word ordering of double-precision floating point numbers under RISC OS
   is slighty different to most other operating systems.  Previously, double
   words were compiled into classes so that the high and low words were
   reversed.  This has been corrected.

 * When guavac looks for classes other than those in the library (e.g. those
   in the CSD) it will load them whether or not they have the "/class"
   extension.  Remember that by default, guavac will not add the extension
   when outputting files.  


Installation:

  Copy the contents of the archive to your HD.  Double-click the
  !Guavac icon to enable it to be run.  If !Guavac reports
  "File 'System:Modules.CallASWI' not found" then you will need to obtain
  the CallASWI module from:

    http://micros.hensa.ac.uk/micros/arch/riscos/e/e160/callaswi.zip

  and place it inside !Boot.Resources.!System.Modules.


Usage:

  You might like to first copy "hw/java" "loop/java" and "Compile"
  to somewhere and then double-click on the Compile Obey file.

  To use it, read the documentation in !Guavac.doc; but in general, the
  usage is:
  
    guavac <source filename>
  
  Where the source file is a java source file, with the file name of
  the format:  program.java, program/java or java/program.  For other Risc
  OS specific questions, see the guavac FAQ, in !Guavac.doc.RO-FAQ
  Have a look at the Compile Obey file for an example of running guavac
  in a taskwindow.

  This distribution also contains guavad, a bytecode dissasembler.
  Usage is:

    guavad <class filename>


The following additions to command line options for guavac have been made
for RISC OS:

Command line flags:

  -ext  By default, guavac will not add the "/class" extension to generated
  classfiles, due to the likelihood of it being truncated to 10 characters
  under the RISC OS filecore.  Using this flag means the extension will be
  added.  Note that not adding the extension is not a problem, since the class
  is filetyped to 'Java' (filetype &AE4).

  -th   Use throwback.  To use this, the DDEUtils module must be loaded.
  When using this switch, an editor such as StrongED or Zap which supports
  the throwback protocol will generate a list of files and linenumbers on
  which errors occured.

  -cp   Specifiy additional classpath directories to look in.  This argument,
  if specified, is also used as the output directory instead of the CSD.


Library class files:

  By default, guavac will use the !Guavac.class/zip file as a library to
  compile against.  However, if the system variable Java$ClassDir is
  set (as it will be by RISCafe and Chockcino) then the library file to
  which this points will be used instead.  The -classfile flag may be
  used to overide either of these.  There is no need to set this variable.


Source filenames:

  Source files may either be called program/java (assuming the filing system
  you are using can handle this many characters in the filename) or
  be of the format java.program, using the convention of C source files
  under RISC OS.


Memory Usage:

  Since guavac is linked with Unixlib, guavac cannot manually increase its
  Wimpslot, so the wimpslot size must be set first, like GCC.  guavac sets
  the guavac_heap system variable, so under RISC OS 3.5 or later, it will
  use dynamic areas for its heap.  In this case, a Wimpslot of around 2.8Mb
  should be fine.  It will also work with Virtualise if necessary.  On older
  machines, the Wimpslot will need to be higher - experiment as necessary.
  The value of guavac_heap is irrelevant; it only needs to exist, and
  is set in the !Boot file. Please note that later releases of guavac may use
  less memory.



To do:

  * Fix remainging problems with constant folding of floating point values.

  * Compile guavac 1.2


Where can I learn more about Java?

  URLs
    Javasoft:  http://www.javasoft.com/
    Chockcino homepage:  http://free.prohosting.com/~chocky/java/

  Magazines
    My article in December 1997 Acorn User (that's the one with the Cover CD)
    My series on Java programming in RISC User.

 Make sure you look that the FAQ which is included in the docs directory
 also.


Acknowlegdements:

  Tony Houghton - for help with the C++ templates.
  Peter Burwood - again for help with C++ templates, the alternative
    sprite, and for many comments and much miscelleneous help.
  Jon Wright - for the Frontend. 
  The UnixLib team
  The #acorn channel


Any comments, critisims, etc, to Peter Naulls - pnaulls@usa.net.


