Chapter   14

JavaCodeCompact (JCC)

KVM supports the JavaCodeCompact (JCC) utility (also known as the class prelinker, preloader or ROMizer). This utility allows Java classes to be linked directly in the virtual machine, reducing VM startup time considerably.

At the implementation level, the JavaCodeCompact utility combines Java class files and produces a C file that can be compiled and linked with the Java virtual machine.

In conventional class loading, you use javac to compile Java source files into Java class files. These class files are loaded into a Java system, either individually, or as part of a jar archive file. Upon demand, the class loading mechanism resolves references to other class definitions.

JavaCodeCompact provides an alternative means of program linking and symbol resolution, one that provides a less-flexible model of program building, but which helps reduce the VM’s bandwidth and memory requirements.

JavaCodeCompact can:

combine multiple input files
determine an object instance’s layout and size
load only designated class members, discarding others.

14.1 JavaCodeCompact options

JavaCodeCompact accepts a large number of arguments and options. Only the options currently supported by KVM are given below.

filename

Designates the name of a file to be used as input, the contents of which should be included in the output. File names with a .class suffix are read as single-class files.

File names with .jar or .zip suffixes are read as Zip files. Class files contained as elements of these files are read. Other elements are silently ignored.

-o output filename

Designates the name of the output file to be produced. In the absence of this option, a file is produced with the name ROMjava.c.

-nq

Prevents JavaCodeCompact from converting the byte codes into their “quickened” form. This option is currently required by KVM.

-classpath path

Specifies the path JavaCodeCompact uses to look up classes. Directories and zip files are separated by the delimiting character defined by the Java constant java.io.File.pathSeparatorChar. This character is usually a colon on the Unix platform, and a semicolon on the Windows platform.

Multiple classpath options are cumulative, and are searched left-to-right. This option is used in conjunction with the -c cumulative-linking option, and with the -memberlist selective-linking option.

-memberlist filename

Performs selective loading as directed by the indicated file. This file is an ASCII file, as produced by JavaFilter, containing the names of classes and class members.

-v

Turns up the verbosity of the linking process. This option is cumulative. Currently up to three levels of verbosity are understood. This option is only of interest as a debugging aid.

-arch Architecture

Specify the architecture for which you are generating a romized image. At this time, you must specify KVM as the architecture.

14.2 Porting JavaCodeCompact

With one exception, JavaCodeCompact outputs C code that is completely platform-independent.

To initialize a variable that is final static long or final static double, JavaCodeCompact performs the appropriate initialization using the two macros:

    ROM_STATIC_LONG(high-32-bits, low-32-bits) 
    ROM_STATIC_DOUBLE(high-32-bits, low-32-bits) 

If you have initialized either the compiler BIG_ENDIAN or LITTLE_ENDIAN to a non-zero value, the file src/VmCommon/h/rom.h generates default values for these macros.

If you have not defined BIG_ENDIAN or LITTLE_ENDIAN, or if for some reason the macros defined in rom.h are inappropriate for your platform, you should create appropriate definitions for ROM_STATIC_LONG and/or ROM_STATIC_DOUBLE in a platform-dependent location.

There are no other known platform or port dependencies.

14.3 Compiling JavaCodeCompact

The sources for JavaCodeCompact are in the directory tools/jcc/src.

On Unix and Windows machines, you compile JavaCodeCompact by typing the command “gnumake” in the tools/jcc/ directory. This compiles all .java files in the tools/jcc/src subdirectory, and places the resulting compiled file in the tools/jcc/classes directory.

You may need to make modifications to the Makefile in the tools/jcc/ directory to indicate the location of your javac compiler.

14.4 JavaCodeCompact files

The directory tools/jcc contains a Makefile that shows all the steps necessary to execute JavaCodeCompact. This Makefile currently has two targets:

unix 
windows 

each of which can be used to create all the files necessary for that platform.

On the unix and windows platforms, two files are created:

ROMjavaPlatform.c 
nativeFunctionTablePlatform.c 

The first file contains the C data structures that correspond to the classes in the zip file. The second file contains tables necessary for using native functions (see §11.3). This second file should be compiled and linked into KVM whether or not you are planning to use the other features of the JavaCodeCompact utility.

14.5 Executing JavaCodeCompact

The JavaCodeCompact utility is used to built the platform-specific file nativeFunctionTablePlatform.c, which contains tables necessary for calling native methods.

This file must be built even if you are not using the ability of JavaCodeCompact to pre-load classes for you. If you are not ROMizing your system classes (in other words, you are loading all system classes dynamically), you may skip Step 4 below.

The simplest method for using the JavaCodeCompact utility is to either use the Makefile provided or to modify it for your platform. The following lists the steps that the Makefile performs:

Compile all the .java files in the api/src directory. The resulting class files are verified and merged into a single zip file classes.zip. This zip file is copied to the tools/jcc directory.
Compile the sources for JCC as described in §14.3 above.
Copy classes.zip to classesPlatform.zip. Remove from this platform-dependent zip file any classes or packages that should not be used on your platform.
Execute your system’s equivalent of the following command in the jcc directory:

   env CLASSPATH=classes \
      JavaCodeCompact -nq -arch KVM \
      -o ROMjavaPlatform.c classesPlatform.zip   

The “env CLASSPATH-classes” sets an environment variable indicating that the code for executing JavaCodeCompact can be found in the subdirectory called classes. Next on the command line is the name of the class whose main method is to be executed (JavaCodeCompact), and the arguments to that method.

Execute your system’s equivalent of the following command in the jcc directory:

   env CLASSPATH=classes \
      JavaCodeCompact -nq -arch KVM_Native
      -o nativeFunctionTablePlatform.c classesPlatform.zip 

This command creates the file containing the native function tables necessary to link native methods to the corresponding C code.
Recompile all the sources for KVM. You must ensure that the preprocessor macro ROMIZING is set to a non-zero integer value. You must also ensure that the file ROMjavaPlatform.c is included as one of your source files.

The resulting kvm image will include, pre-loaded, all of the class files that were in the original classesPlatform.zip file.

14.6 Limitations

The current implementation of JavaCodeCompact requires that the class files that you compact constitute a “transitive closure.” If class A is compacted, and class A’s constant pool references class B, then class B must also be included as part of the compaction.

Class A includes Class B in its constant pool if any of the following conditions are true:

Class A is a direct subclass of class B, or class A directly implements class B.
Class A creates an instance of class B, or an array of class B.
Class A calls a method that is defined in class B.
Class A checks to see if an object is an instance of type B, or casts an object to type B.

Note that the following do not cause class B to be included in class A’s constant pool. Under certain circumstances, it may be possible to compact A without also compacting B.

Class A has an instance variable of type B
Class A has a method whose argument or return type includes type B in its signature.
Class A creates an instance of class B using the Class.forName() method.

JavaCodeCompact will fail and give you an error message if you fail to include a class file that it requires.

KVM Porting Guide , CLDC 1.1

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.