Builder Extended Usage

A number of extended options provide additional means for finer control of the Builder's operation for the more experienced user. The following sections list these extended options and describe their effect.

As for normal options explained in the Section called Builder Usage, extended options can be stored in a configuration file. The configuration file <HOME>/.jamaica/jamaica.conf is used if present. If not, <JAMAICA>/etc/jamaica.conf is used. The options given on the command line have higher priority than options read from the configuration file, i.e., values read from the configuration file are overwritten.

The command line syntax for the Builder tool's extended options is as follows:

jamaica [-XdefineProperty[+]=<property>=<value>]
        [-XdefinePropertyFromEnv[+]=<name>]
        [-XjamaicaHome=<path>] [-Xbootclasspath=<path>]
        [-XextendedGlobalCPool] [-XlazyConstantStrings]
        [-XlazyConstantStringsFromEnv=<var>] [-XnoMain]
        [-XnoClasses] [-XenableZIP] [-XfileNameMap=<mapfile>]
        [-XfullStackTrace] [-XexcludeLongerThan=<n>]
        [-Xcc=<cc>] [-XCFLAGS=<cflags>] [-Xld=<linker>]
        [-XLDFLAGS=<ldflags>] [-dwarf2]
        [-XstripOptions=<options>] [-Xlibraries[+]=<libraries>]
        [-XstaticLibraries[+]=<libraries>]
        [-XlinkDynamicPrefix=<prefix>]
        [-XlinkStaticPrefix=<prefix>]
        [-XlinkDynamicFlags=<switch>]
        [-XlinkStaticFlags=<switch>]
        [-XlibraryPaths[+]=<libraryPaths>] [-Xstrip=<tool>]
        [-XnoRuntimeChecks] [-XavailableTargets]
        [-XprofileFilename=<name>] [-Xinclude[+]=<dirs>]
        [-XobjectFormat=default | none | C | ELF]
        [-XobjectProcessorFamily=<type>]
        [-XobjectElfSymbolPrefix=<prefix>]
        [-XignoreLineNumbers]
        [-agentlib=<lib>=<option>=<val>{,<option>=<val>}] 
        class1 [... classn]

General Options

The following are general options which provide information about the Builder itself or enable the use of script files that specify further options.

-XdefineProperty=<property>=<value>

The XdefineProperty option sets a system property for the resulting binary. For security reasons, system properties used by the VM cannot by changed.

-XdefinePropertyFromEnv=<name>

At program start, the resulting binary will set a system property to the value of an environment variable. This feature can only be used if the target OS supports environment variables. For security reasons, system properties used by the VM cannot be changed.

Classes, files and paths

These options allow the specification of classes and paths to be used by the Builder.

-XjamaicaHome=<path>

The XjamaicaHome option specifies the path to the Jamaica directory. The Jamaica home path can also be set with the environment variable JAMAICA_HOME.

-Xbootclasspath=<path>

The Xbootclasspath specifies path used for loading system classes.

-XextendedGlobalCPool

If set to true, the global constant pool can take up to 0x7FFFFFF (31bit) UTF8 strings. The default is false (0xFFFF, 16bit). Please note that this extension breaks runtime annotation and jvmti/debugging.

-XlazyConstantStrings

JamaicaVM by default allocates all String constants at class loading time such that later accesses to these strings is very fast and efficient. However, this approach requires code to be executed for this initialization at system startup and it requires Java heap memory to store all constant Java strings, even those that are never touched by the application at run time

Setting the option -XlazyConstantStrings causes the VM to allocate string constants lazily, i.e., not at class loading time but at time of first use of any constant string. This saves Java heap memory and startup time since constant strings that are never touched will not be created. However, this has the effect that accessing a constant Java string may cause an OutOfMemoryError.

-XlazyConstantStringsFromEnv=<var>

This option causes the creation of an application that reads its XlazyConstantStrings setting from the specified environment variable. If this variable is not set, the value of boolean option XlazyConstantStrings will be used. The value of the environment variable must be 0 (for "-XlazyConstantStrings=false") or 1 (for "-XlazyConstantStrings=true").

-XnoMain

The XnoMain option builds a standalone VM. Do not select a main class for the built application. Instead, the first argument of the argument list passed to the application will be interpreted as the main class.

-XnoClasses

The XnoClasses option does not include any classes in the built application. Setting this option is only needed when building the jamaicavm command itself.

-XenableZIP

The XenableZIP option enables ZIP and JAR support in the generated binary. This makes binaries significantly larger. Set this this option only if you are building a virtual machine (see XnoMain) and the application application executed on the target system might access ZIP and JAR files in the class path at runtime.

Independently of this option, the Jamaica Builder can always process classes in ZIP or JAR files.

-XfileNameMap=<mapfile>

Some file systems have character restrictions or filename length limits. Normally, Java class files are stored in a file with the same name as the class (with package separator `.' replaced by java.io.File.separatorChar). On systems with such restrictions, classes with "illegal" file names are usually stored in JAR files. Alternatively, this map can be used to indicate that a class should be loaded from a file with a different file name. The map file must be in Java Property File format, i.e., a new line for each map of the form "class name: file name". Class file names must be relative names that will be searched for in the classpath. Class names and class file names must have the package separator `/'. Classes must have the file extension .class. E.g., "java/lang/Object.class:jv/lg/Obj.cl".

Compilation

Compilation and different optimisation techniques are used for optimal runtime performance of Jamaica applications. These techniques are controlled using the following options.

-XfullStackTrace

Compiled code usually does not contain full Java stack trace information if the stack trace is not required anyway (as in a method with a try/catch clause or a synchronized method. For better debugging of the application, the XfullStackTrace option can be used to create a full stack trace for all compiled methods.

-XexcludeLongerThan=<n>

Compilation of large Java methods can cause large C routines in the intermediate code, especially when combined with aggressive inlining. Some C compilers have difficulties with the compilation of large routines. To enable the use of Jamaica with such C compilers, the compilation of large methods can be disabled using the option XexcludeLongerThan.

The argument specified to XexcludeLongerThan gives the minimum number of bytecode instructions a method must have to be excluded from compilation.

-Xcc=<cc>

The Xcc option specifies the C compiler to be used to compile intermediate C code that is generated by the Jamaica Builder.

-XCFLAGS=<cflags>

The XCFLAGS option specifies the cflags for the invocation of the C compiler. Note that for optimisations the compiler independent option -optimise should be used.

-Xld=<linker>

The Xld option specifies the linker to be used to create a binary file from the object file generated by the C compiler.

-XLDFLAGS=<ldflags>

The XLDFLAGS option specifies the ldflags for the invocation of the C linker.

-dwarf2

The dwarf2 option generates a DWARF2 version of the application. DWARF2 symbols are needed for tracing Java methods in compiled code. Use this option with WCETA tools and binary debuggers.

-XstripOptions=<options>

The XstripOptions option specifies the strip options for the invocation of the stripper. See also option Xstrip .

-Xlibraries=<libraries>

The Xlibraries option specifies the libraries that must be linked to the destination binary. The libraries must include the option that is passed to the linker. Multiple libraries should be separated using spaces and enclosed in quotation marks. E.g., -Xlibraries "m pthread" causes linking against libm and libpthread.

-XstaticLibraries=<libraries>

The XstaticLibraries option specifies the libraries that must be statically linked to the destination binary. The libraries must include the option that is passed to the linker. Static linking creates larger executables, but may be necessary if the target system doesn't provide the library. Multiple libraries should be separated using spaces and enclosed in quotation marks. E.g., -XstaticLibraries "m pthread" causes static linking against libm and libpthread.

-XlinkDynamicPrefix=<prefix>

The XlinkDynamicPrefix option specifies a prefix to link a library dynamic to the created executable, e.g., "-Wl,-Bdynamic".

-XlinkStaticPrefix=<prefix>

The XlinkStaticPrefix option specifies a prefix to link a library statically to the created executable, e.g., "-Wl,-Bstatic".

-XlinkDynamicFlags=<switch>

The XlinkDynamicFlags option specifies flags for dynamic linkage of an executable, e.g., "-dynamic".

-XlinkStaticFlags=<switch>

The XlinkStaticFlags option specify flags for dynamic linkage of an executable, e.g., "-static".

-XlibraryPaths=<libraryPaths>

The XlibraryPaths option adds the directories in the specified paths to the library search path. Multiple libraries should be separated by the path separator character (e.g., `:'). E.g., to use the directories /usr/local/lib and /usr/lib as library path, the option "-XlibraryPaths /usr/local/lib:/usr/lib"must be specified.

-Xstrip=<tool>

The Xstrip option uses the specified tool to remove debug information from the generated binary. This will reduce the size of the binary file by removing information not needed at runtime.

-XnoRuntimeChecks

The XnoRuntimeChecks option disables runtime checks for compiled Java code. This option deactivates runtime checks to obtain better runtime performance. This may be used only for applications that do not cause any runtime checks to fail. Failure to run these checks can result in crashes, memory corruption and similar disasters. When untrusted code is executed, disabling these checks can cause vulnerability through attacks that exploit buffer overflows, type inconsistencies, etc.

The runtime checks disabled by this option are: checks for use of null pointers, out of bounds array indices, out of bounds string indices, array stores that are not compatible with the array element type, reference assignments between incompatible memory areas, division by zero and array instantiation with negative array size. These runtime checks usually result in throwing the exceptions NullPointerException, ArrayIndexOutOfBoundsException, StringIndexOutOfBoundsException, ArrayStoreException, IllegalAssignmentError, ArithmeticException or NegativeArraySizeException. When deactivated, the system will be in an undefined state if any of these conditions occurs.

-XavailableTargets

The XavailableTargets option lists all available target platforms of this Jamaica distribution.

Profiling

Profiling can be used to guide the compilation process and to find a good trade-off between fast compiled code and smaller interpreted byte code. This is particularly important for systems with tight memory and CPU resources.

-XprofileFilename=<name>

The XprofileFilename option sets a filename for profiling data. If profiling is enabled output is written to this file. If a profile filename is not specified then the profile data is written a the file with the name of the destination (see option destination) with the extension .prof added.

Native code

Native code is code written in a different programming language than Java (typically C or C++). This code can be called from within Java code using the Java Native Interface (JNI). Jamaica internally uses a more efficient interface, the Jamaica Binary Interface (JBI), for native calls into the VM and for compiled code.

-Xinclude=<dirs>

The Xinclude option adds the specified directories to the include path. This path should contain the include files generated by jamaicah for the native code referenced from Java code. The include files are used to determine whether the Java Native Interface (JNI) or Jamaica Binary Interface (JBI) is used to access the native code.

This option expects a list of paths that are separated using the platform dependent path separator character (e.g., `:').

-XobjectFormat=default | none | C | ELF

The XobjectFormat option sets the object format. Possible formats are default , none , C and ELF (default: ELF).

-XobjectProcessorFamily=<type>

The XobjectProcessorFamily option sets the processor type for code generation. Available types are none , i386 , i486 , i586 , i686 , ppc , sparc , arm , mips , sh4 and cris . The processor type is only required if the ELF object format is used. Otherwise the type may be set to none (default: i386).

-XobjectElfSymbolPrefix=<prefix>

The XobjectElfSymbolPrefix sets the object ELF symbol prefix, e.g., `_' (default: not used).

Miscellaneous

Miscellaneous options.

-XignoreLineNumbers

Specifying the XignoreLineNumbers option instructs the Builder to remove the line number information from the classes that are built into the target application. The resulting information will have a smaller memory footprint and RAM demand. However, exception traces in the resulting application will not show line number information.

-agentlib=<lib>=<option>=<val>{,<option>=<val>}

The agentlib option loads and runs the dynamic JVMTI agent library <libname> with the given options. Be aware that JVMTI is not yet fully implemented, so not every agent will work.

Jamaica comes with a statically built in debugging agent that can be selected by setting BuiltInAgent as name. The transport layer must be sockets. A typical example would be: "-agentlib=BuiltInAgent=transport=dt_socket,server=y,suspend=y, address=8000". This starts the application and waits for a incoming connection of a debugger on port 8000. See the Section called Enabling the Debugger Agent in Chapter 14 for further information on the options that can be provided to the built-in agent for remote debugging.