Harissa Manual

Installing Harissa
How to use Harissa
Creating a separate library
Compiling the Javac compiler
Using the graphic Biss library
Choosing between the GC and the non-GC version
Controlling inlining
Implementation details

Installing Harissa

To install harissa:

Retrieve the appropriate harissa.target_platform.tar.gz file.
Uncompress and untar the file in the installation directory. The tar contains the following directories:
```
bin/
include/
lib/
libjdk/
lib/mmwithgc/
lib/mmwithout/
doc/
```
Edit the file bin/harissa_config.csh. Set the JDKLIB variable with the directory where the file classes.zip can be found. Set the HARISSAHOME variable with the name of the directory where Harissa has been installed. Choose between the GC and the non GC version by commenting/uncommenting the appropriate line.
Execute source bin/harissa_config.csh each time you start a new session, or modify your .login accordingly.

How to use Harissa

Harissa offers two commands:

hi: a Java interpreter;
hac: a bytecode-to-C compiler.

hi

hi is a Java interpreter. Its syntax can be obtained by executing it with no parameters:

hi version alpha3.01 copyright (C) Irisa/Inria 1996,1997
syntax: hi [-p] class args...
-p : generate profiling information
'class' is a class containing a 'main' method which will be launched.
        Its signature must be  'public static void main(String[])'.
'args' are the arguments given to the 'main' method.

The profiling information is written into the files vm.prof and call.prof.

The file vm.prof contains an accurate bytecode instruction count. At the end of the file, some global statistics are given.
The file call.prof contains a list of all dynamic call sites encountered during the execution of the program. For each call site, a list of all the methods called is given. At the end of the file, global counts are given.

hac

hac is a Java to C translator. A C source file is generated for each Java class used by the compiled application. The syntax can be obtained by executing hac with no parameters:

Hac version alpha3.02 copyright (C) Irisa/Inria 1996,1997
syntax: hac [-h] [-V] [-o output] [-d path] [-l lib] [-P] [-R] [-J] [-n]
            [-O] [-C] [-i size] [-I n] [-M nClass] [-B] [-T] [-g] [-s] [-t] [-S] [-N (+|-)Method]
            command classes...
'command' : one of header,stub,src,code,prog
'classes' : the Java classes to handle
-h : print this help
-V : verbose (more progress indication)
-o object : name of executable binary (default='./gen')
-d dir : directory of generated C sources (default='a.out')
-l x : don't generate classes provided by the 'libx' library
-P : print bytecode within each method
-R : Generate a dummy return after index bound exceptions (default for the SPARC)
-J : Generate a jump to a common label for index bound exceptions (default for i386)
-O : turn on optimizations (equivalent to -C -i100 -I1 -g)
-C : Class Hierarchy Analysis
-i size : allow method inlining when bytecode size <= size
-I n : perform at most n iterations of inlining (default: 0)
-M nClass : perform at most n iterations of inlining of classes matching Class
-B : no bound checks
-T : no type checks
-g : include source file information (name of variables, name of fields)
-s : assume that no class will be loaded dynamically
-t : Analyse thread creation (implies -C and -s)
-S : Force generation of single-threaded code
-N +Method : Specify that native methods matching Method may create threads (for -t)
-N -Method : Specify that native methods matching Method do not create threads (for -t)

When you compile a Java program into C, the C source files are written by default within the directory ./gen. A Makefile is also created. To compile the C sources you only need to go in the gen directory and type make.

Behavior of commands:

prog is used to translate a whole Java program. Only the class containing the main method should be given. It should be given without the .class extension.
code is used to translate one class and the classes of arrays referenced by it. It used to construct libraries of classes.
header, stub and src are used to create headers and C sources to implement native Java methods. See the SUN program javah for more details.

Behavior of options:

-o specifies the name of the executable binary (default=a.out).
-d permits the overriding of the directory where C sources are generated (default=./gen).
-l x tells hac not to generate a C source for classes that are included in the library libx.so. The library must be reachable through the path given by the LD_LIBRARY_PATH variable.
-P prints bytecode within each method.
-R generates a dummy return after index bound exceptions. This is the default for the SPARC.
-J generates a jump to a common label for index bound exceptions. This is the default for the i386.
-J and -R options are mutually exclusive. We found that puting either a jump or a return gave more control-flow information to gcc especially for array accesses embeded in loops. Caching of intermediate results in registers is more effective and the binary code is more efficient.
-C performs an analysis on the hierarchy of classes. Its purpose is to tell if there is only one target method associated with a call site. If so, the method call is replaced by a static procedure call. This optimization works only if the application does not dynamically load code.
-i size enables method inlining when bytecode size is lower or equal to size for methods that have been transformed into procedure calls.
-I n enables iterative application of the inlining transformation. This can give good speedups, but if applied globally to a large program (such as javac) it can consume a large amount of memory. Inling more than once seems to produce bad code in rare instances. This is currently being investigated.
-M nClass limits the amount of inlining for any class whose prefix matches Class to n times. Note that nClass must be written as a single word. Multiple -M options can be applied, and are processed in the order they appear on the command line (the -M flags implied by the -O option are processed when the -O option is read).

-O turns on various optimizations that are appropriate for most smaller programs, namely Class Hierarchy Analysis (-C), inlining (of methods that aren't longer than 100 lines, at most once, and generation of symbolic names (-g). In general, this option produces fast code without consuming too much memory during the compilation process. Other combinations of options may give better results and/or consume less memory.
-B disables the generation of bound checks in the C code.

-T disables the generation of type checks in the C code.

The purpose of the -B and -T options is to estimate the effective cost of checks in an application. It is not recommended to use them since the generated program does not follow Java semantics and the application is less reliable.

-g includes source file information (name of variables, name of fields). This can sometimes help the C compiler when doing optimizations.

-s assumes that no class will be loaded dynamically. Stubc procedures that call the interpreter from the compiled code are not generated so as to reduce code size.

-t performs an analysis on the hierarchy of classes to detect if the application is single threaded. If so, an optimized runtime system, without synchronizations, is generated. This option can be used for compiling javac. This optimization works only if the application does not dynamically load code.

-S forces generation of single-threaded code. This option is useful for generating libraries that will only be used in a single-threaded context, or for compiling programs that are known (e.g. by previous use of the -t option) to not create threads.

-N +Method specifies the thread-creation property for the native methods whose prefix matches Method. The thread creation detection cannot analyse native methods, so this information must be provided on the command line (hac has appropriate defaults for the JDK 1.0.2 class libraries). The -N + option is used to specify that any method whose prefix matches Method may create threads.

-N -Method is similar to -N+, except that it specifies that methods whose prefix matches Method are known to not create threads.

Creating and compiling separate libraries

The makefile provided in the directory libjdk permits to generate a library containing JDK java classes. Before typing make, edit #define that are OS dependent. Basically, the makefile lists classes of the JDK archive and for each class calls:
hac code class
Then, C files are compiled and put together in a libjdk.so library. Then, the library has to be be used with -l jdk option.

Compiling the Javac compiler

The first step is to create a gen directory.

The following command can then be used to create an optimized binary (assuming the JDK library has been compiled seperately):

hac -ljdk -t -O -o cjavac prog sun.tools.javac.Main
to create the C files (this compilation process consumes about 40Mb of memory).

The C code can be compiled using the make command:
cd gen; make

On a PC/Pentium 90 Mhz, C code generation (without optimizations) takes about 1 mn. C code compilation by gcc 2.7.2 with the -O2 option takes about 8 minutes.
To limit the memory consumption (and compile more quickly) one might use:
hac -ljdk -o cjavac prog sun.tools.javac.Main
which consumes about 15M of memory and thus should work fine on most systems. To compile the jdk library into the binary, use:
hac -o cjavac prog sun.tools.javac.Main

To compile a highly optimized binary, assuming that enough RAM is available (about 100Mb), one might use the command:
hac -o cjavac -O -I5 -M1java. prog sun.tools.javac.Main

On SunOS, the make process sometime crashes, read the FAQ for solution.

Using the graphic Biss library

Graphic applications relying on Biss must be linked with the jdk, awt and biss libraries. Therefore, one should give the -ljdk -lawt -lbiss options to hac. For instance, the LibBrowser application distributed with Biss can be compiled with the following command:

hac -ljdk -lawt -lbiss -C -g prog biss.jde.LibBrowser
CHA requires a lot of memory, for large applications !! 240 Mb of virtual address space are required to compile LibBrowser with CHA.

Choosing between the GC and the non-GC version

Harissa is provided in two different configurations with and without Garbage Collection. The GC version is based on the Boehm-Demers-Weiser conservative garbage collector. The non GC version is based on the system malloc primitive. Since objects are never deallocated, it leads to an increase of the heap segment and a slow down of the application due to disk swapping.

The choice between the two versions is done by linking the application either with lib/mmwithgc/libmem.so or lib/mmwithout/libmem.so. To switch between versions, you have to change the LD_LIBRARY_PATH and HARISSA_LIB_MEM variables. On SunOS, the libmem.so library is statically linked with the program and the link phase has to be redone. To to so the application binary must be removed and the make restarted.

Controlling inlining
As a solution for the memory consumption problems that can arise with inlining on large programs, the command-line switch -M is provided. The command-line switches -i and -I control how much inlining can be performed. The current memory consumption problems are primarily visible when inlining is performed in multiple iterations. The -M option allows one to limit the inlining performed on certain parts of the program, such as the java class library and classes containing non-critical methods.

Implementation details
The Linux version of Harissa uses version 0.6-4 of the linuxthreads package (available at most Linux FTP sites). To compile the programs produced by Harissa, this library must be installed on the machine. Harissa has been tested with version 5.4.33-1 of the libc library.

Harissa's garbage collector, the Boehm-Demers-Weiser conservative garbage collector, internally provides specific memory allocation primitives for data that is known to not contain pointers. These primitives are used for array and string allocation, and in a few other places (as appropriate). However, the garbage collector is conservative and does assume that any value not allocated in this fashion may be a pointer. This can lead to memory leaks, as is probably the case with hac at the moment, but for most applications it works fine.

back to the Harissa home page