Builder Usage

To control the work of the builder tool, a variety of arguments can be provided. The arguments can be given directly to the builder via command line, or by using a configuration file. By default, the configuration file <HOME>/.jamaica/jamaica.conf (if present) respectively <JAMAICA>/etc/jamaica.conf is used. The given options on the command line have higher priority than options read from the configuration file, i. e. values in the configuration file are "overwritten".

The following special syntax is accepted:

The command line syntax for the builder tool is as follows:

jamaica [-help (--help, -h, -?)] [-Xhelp (--Xhelp)] [-Xdoc]
        [-version] [-verbose=<n>] [-showSettings]
        [-saveSettings=<file>] [-configuration=<file>]
        [-XdefineProperty[+]=<name>=<value>]
        [-XdefinePropertyFromEnv[+]=<name>]
        [-XjamaicaHome=<path>] [-classpath (-cp)=<path>]
        [-Xbootclasspath=<path>] [-main=<class>]
        [-jar=<JAR-file>] [-includeClasses[+]=<class/package>]
        [-includeJAR[+]=<jarfilelist>] [-lazy]
        [-lazyFromEnv=<var>] [-destination=<name>]
        [-tmpdir=<name>] [-resource[+]=<names>]
        [-setLibraries[+]=[<symbol>=<value>{,<value>}]]
        [-XnoMain] [-XnoClasses] [-enableZIP]
        [-ignoreClassNotFound] [-cldc]
        [-XfileNameMap=<mapfile>] [-incrementalCompilation]
        [-smart] [-notSmart[+]=<classes>]
        [-numDynamicTypesFromEnv=<var>] [-numDynamicTypes=<n>]
        [-showIncludedFeatures] [-showExcludedFeatures]
        [-large] [-noCompaction] [-compile] [-debug]
        [-inline=<n>] [-Xtrace=<level>]
        [-excludeLongerThan=<n>] [-XlinkStatic=<libraries>]
        [-optimise (-optimize)=<type>] [-Xcc=<cc>]
        [-XCFLAGS=<cflags>] [-Xld=<linker>]
        [-XLDFLAGS=<ldflags>] [-Xlibraries[+]=<libraries>]
        [-XstaticLibraries[+]=<libraries>]
        [-XlinkDynamicPrefix=<prefix>]
        [-XlinkStaticPrefix=<prefix>]
        [-XlinkDynamicFlags=<switch>]
        [-XlinkStaticFlags=<switch>]
        [-XlibraryPaths[+]=<libraryPaths>] [-Xstrip=<strip>]
        [-XnewTarget[+]=<original_target>] [-target=<platform>]
        [-XnoRuntimeChecks] [-XavailableTargets]
        [-heapSize=<n>] [-stackSize=<n>] [-javaStackSize=<n>]
        [-nativeStackSize=<n>] [-immortalMemorySize=<n>]
        [-numThreads=<n>] [-analyse=<tolerance>]
        [-constGCwork=<gc-work>] [-threadPreemption=<n>]
        [-timeSlice=<n>] [-finalizerPri=<pri>] [-strictRTSJ]
        [-strictRTSJFromEnv=<var>] [-heapSizeFromEnv=<var>]
        [-stackSizeFromEnv=<var>] [-javaStackSizeFromEnv=<var>]
        [-nativeStackSizeFromEnv=<var>]
        [-immortalMemorySizeFromEnv=<var>]
        [-numThreadsFromEnv=<var>] [-analyseFromEnv=<var>]
        [-constGCworkFromEnv=<var>] [-priMap=<jp=sp{,jp=sp}>]
        [-physicalMemoryRanges=<range{,range}>] [-profile]
        [-XprofileFilename=<name>] [-percentageCompiled=<n>]
        [-useProfile[+]=<profilelist>] [-object[+]=<files>]
        [-include[+]=<dirs>] [-XobjectFormat=<none|ELF>]
        [-XobjectGenerateCode=<C|i386|i486|i586|sparc>]
        [-Xstats] [-XcountCalls] [-XcountArrays]
        [-XcountAllocs] [-XcountFields]  class1 [... classn]

General

These are general options providing information about the builder itself or enabling the use of script files that specify further options.

-help (--help, -h, -?)

Display the usage of the Builder and a short description of all possible standard command line options.

-Xhelp (--Xhelp)

Display the usage of the Builder and a short description of all possible standard and extended command line options. The extended command line options are not needed for normal control of the Builder command. They provide means to configure the tools and options to be used and provide tools required internally for development of the Jamaica.

-Xdoc

Setting this option causes the creation of docbook documentation file for this command.

-version

Prints the version of the Builder and exits.

-verbose=<n>

Set verbose level for the Builder. If verbose level is larger than 0, additional output on the state of the build process is printed to standard out. The information provided in verbose mode includes: external tools called, warnings, or the list of all class files that are loaded and the methods that are compiled in case compilation is switched on.

-showSettings

The currently used options of the JamaicaVM Builder are written to stdout in property file format. To make these the default settings, copy these options into your jamaica.conf file.

-saveSettings=<file>

The currently used options of the JamaicaVM Builder are written to the provided file in property file format.

-configuration=<file>

The set of options used to build the application are read from the provided file. The format used to define options must be identical to the default configuration file <JAMAICA>/etc/jamaica.conf. With this option given, the other default configuration files, i.e. <JAMAICA>/etc/jamaica.conf and <HOME>/.jamaica/jamaica.conf, are ignored.

-XdefineProperty=<name>=<value>

Set a system property for the resulting binary. For security reasons, system properties used by the VM cannot by changed.

-XdefinePropertyFromEnv=<name>

At programme 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 to specify classes and paths to be used by the builder.

-XjamaicaHome=<path>

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

-classpath (-cp)=<path>

Specify the paths that are used to search for class files. A list of paths separated by the path separator char (":" on Unix systems, ";" on Windows) can be specified. This list will be traversed from left to right when the Builder tries to load a class.

-Xbootclasspath=<path>

Specifies path used for loading system classes.

-main=<class>

Specify the main class of the application that is to be built. This class must contain a static method "int main(String[] args)". This method is the main entry point of the Java application.

If -main is not specified, the first class of the classes list that is provided to the builder is used as main class.

-jar=<JAR-file>

Specify a JAR file with an application that is to be built. This JAR file must contain a MANIFEST with a Main-Class entry.

-includeClasses=<class/package>

Force inclusion of the listed classes and packages into the created application. The listed classes with all their methods and fields will be included even if smart linking is enabled.

The list of arguments for this option can be: Plain class names, e. g., com.my_company.MyClass to include all methods and fields in a given class; a package name followed by an asterisk, e. g. java.util.*, to include all classes in a given package; a package name followed by "...", e. g., java.lang..., to include all classes in a given package and all sub-packages of this package.

CAUTION: Unlike the option -notSmart <classes>, which forces inclusion of all methods and fields of a class and all of its subclasses, -includeClasses affects only the listed classes itself, subclasses remain subject to smart linking. Consequently, providing the option "-notSmart java.lang.Object" disables smart linking for all classes since all classes are subclasses of java.lang.Object, while "-includeClasses java.lang.Object" only causes the inclusion of all methods and fields of class java.lang.Object, but does have no effect on the smart linking of any other class.

Examples: -includeClasses="com.my_company.MyClass:java.util.*:java.lang... " includes the class com.my_company.MyClas, all classes in package java.util, and all classes in package java.lang and all sub-packages of java.lang such as java.lang.ref etc.

-includeJAR=<jarfilelist>

Force the inclusion of all classes and all resources contained in this archive file or directory, even if smart linking is enabled. Any archive listed here, needs to be in either classpath or bootclasspath, too. If a class needs to be included, not necessarily the implementation in the "includeJAR"-file will be used, but the first implementation of this class which is found in the classpath. This is to make sure the application behaves in the same way as it would do if it was called with the jamaicavm or java command.

-lazy

JamaicaVM by default uses static linking of all Java classes. This means that all classes that are referenced from the main class will be loaded before execution of the application starts. This early loading and linking of classes ensures that during the execution of the Java application, no further class loading and linking will be required, ensuring the predictable execution of statements that can cause class loading in a traditional Java environment.

The statements that may cause loading and linking of classes are the same statements that may cause the execution of static initalizers of a class: calls of static methods, accesses to static fields and the creation of an instance of a class.

Setting this option causes JamaicaVM to load and link classes lazily. This may be required to execute applications that reference classes that are not available and that are never used during runtime. Also, it helps to reduce the startup time of an application that refers to large library code that is actually not needed at runtime.

-lazyFromEnv=<var>

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

-destination=<name>

Specify the name of the destination executable to be generated by the builder. If this option is not present, the name of the main class is used as the name of the destination executable.

The destination name can be a path into a different directory. E. g., "-destination myproject/bin/application" can be used to save the created executable "application" in "myproject/bin"

-tmpdir=<name>

This option can be used to specify a name of a directory used for temporary files generated by the builder (such as C-source files, object files and make files).

If -tmpdir is not specified, the current directory is used.

-resource=<names>

This option causes the inclusion of additional resources in the created application. A resource is additional data (such as image files, sound files etc.) that can be accessed by the Java application. Within the Java application, the resource data can be accessed using the resource name specified as an argument to -resource. To load the resource, a call to Class.getResourceAsStream(<name>) can be used.

If a resource is supposed to be in a certain package, the resource name must include the package name. Any "." must be replaced by "/". E. g., the resource ABC from package foo.bar can be added using "-resource foo/bar/ABC".

The builder uses the class path provided through the option "-classpath" to search for resources. Any path containing resource that are provided using "-resource" must hence be added to the path provided to "-classpath".

-setLibraries=[<symbol>=<value>{,<value>}]

This option can be used to choose the set of libraries to be include in the target application. Library sets are used for features such as encodings, protocols, locales etc. A list of available libraries can be obtained via '-setLibraries ""'.

To obtain a list of symbols that can be provided to this option, set this option to list.

Example: -setLibraries encodings=8859_1,UTF8 sets the set of supported encodings to ISO 8859-1 and UTF8 encoding.

Restricting the supported encodings, protocols, etc. via this option typcally results in a smaller application size since fewer library classes need to be included in the target application.

The library sets are defined via symbols in a class depencencies file, which is stored in <JAMAICA_HOME>/etc/jamaica-dependencies.conf. (default: not used)

-XnoMain

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

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

-enableZIP

Enable ZIP and JAR support in the generated binary. This makes binaries significantly bigger. Only enable this option if your application on the target system might access ZIP and JAR files at runtime. Independently of this option, the Jamaica Builder can always process classes in ZIP or JAR files.

-ignoreClassNotFound

If set, this option causes the builder to ignore missing classes. Empty dummy classes are created instead of the missing classes.

This option is useful to build applications that contain unused referenced to classes that are not available at build time. The Builder needs to load all classes that are referenced, so without this option set, such an application could not be built. An example of an unused class is the type of an unused field.

If smart linking is used, the references to the dummy classes will be removed during the smart linking process, and so will be the dummy classes themselfs.

If smart linking is not used, the dummy classes will be built into the generated application. This will have no effect on the execution of the application, unless the referenced classes are accessed by the application (e. g., through the Class.forName() or the reflection API, or if the reference to the class was not unused.

CAUTION: Use this option with care and check that the warnings printed for all classes that were not found list only classes that are not used by the application. Any missing system classes (java.*) or missing main class of an application will cause the build process to fail or the creation of a broken application.

-cldc

This option forces the inclusion of all standard library code within the CLDC configuration. This 'Connected Limited Device Configuration' is supposed to be used in small connected devices.

Providing this option forces the builder to include all classes, fields, methods and constructors that form part of the CLDC configuration. These will be added to the built application even if smart linking is activated using -smart.

The resulting application will hence be able to access all code in the CLDC configuration through dynamically loaded classes or the reflection API even if this code would otherwise not be included in the application.

-XfileNameMap=<mapfile>

Some file systems have restrictions about file name length or used characters. Normally, Java class files are stored in a file of the same name as the class (with package separator '.' replaced by java.io.File.separatorChar). On systems with such restrictions, usually classes with 'illegal' file names are stored in JAR files. Alternatively, this map can be used to indicate a class should be loaded from a file with a different file name. The map file has to 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 package separator '/'. Classes must have file extension '.class'. A proper entry would be 'java/lang/Object.class: jv/lg/Obj.cl'

-incrementalCompilation

If this option is set to true, C code is split into several files for incremental compilation. The generated code is split into one file per package. This is the default behaviour. If this option is set to false, all C code is put into one single, potentially large C source file.

Smart linking

Smart linking and compaction are techniques to reduce the code size and heap memory required by the generated application. These techniques are controlled by the following options.

-smart

If this option is set, smart linking is enabled for the created application. Smart linking permits the builder to remove unused code and to perform better optimisation to obtain smaller binary files, smaller memory usage and faster execution.

Smart linking must only be used for closed applications that do not use Java's reflection API (including reflection via the Java Native Interface JNI) and that do not download classes dynamically or use functions like java.lang.Class.forName(className) that cause loading of classes that are not visible to the builder tool. If -smart is used for these applications, code that is referenced by classes that are loaded dynamically or through the reflection API might have been removed and methods that are redefined by dynamically loaded code might not be called correctly since -smart causes static binding of virtual or interface methods that are not redefined.

When dynamic class loading or reflection is used, the option -notSmart can be used to restrict the effect of -smart and still profit from better optimisation

-notSmart=<classes>

This option causes all classes provided as an argument to this option to be excluded from the optimisations enabled by option -smart.

For reflection (including reflection through JNI) to work properly, all classes that are used by the reflection API must be excluded from smart linking using this option. Similarly, all classes that might be referenced by classes that are downloaded dynamically must be excluded form smart linking as well.

Since serialization requires the reflection API, smart linking can change the format of the data generated for serialized objects. This can cause conflicts if serialized classes need to be exchanged between different versions of an application or different Java runtime environments. To avoid these difficulties, all classes that are subject to serialization should be excluded from smart linking

If several classes are specified as an argument for -notSmart, the classes must be separated using spaces. E. g., specifying "-notSmart pack1.Foo pack2.Bar" excludes classes pack1.Foo and pack2.Bar from smart linking.

-numDynamicTypesFromEnv=<var>

Specifying this options causes the creation of an application that reads the number of dynamically loadable types from the environment variable specified by <var>. If this variable is not set, the number specified using "-numDynamicTypes <n>" will be used.

-numDynamicTypes=<n>

When -smart is set, the number of types that can be used by the application is limited. Types are all classes used in the system and all arrays of different dimensions and of different element types. The number of classes used by the internal classes of the application is determined automatically by the Jamaica Builder. It is therefore only required to specify the number of types with "-numDynamicTypes" in the case dynamic loading of classes is used.

This option can only specified in conjunction with "-smart". If smart linking is disabled, the number of types is not limited statically. In this case, only the memory available in the Java heap limits the number of types that can be created dynamically.

The value can be set to zero in case dynamic loading is not used. Lower values require less memory. The maximum allowed number of types is 65535.

-showIncludedFeatures

This option will cause the builder to display a list of all classes, methods and fields that will be part of the created application. Any classes, methods or fields removed from the target application through mechanisms such as smart linking (as activated through option -smart) will not be displayed. In conjunction with option -smart and -notSmart, this helps one to identify what methods are included into the application

The output of this option consists of lines starting with the string INCLUDED CLASS, INCLUDED METHOD or INCLUDED FIELD followed by the name of a class or the name and signature of a method or field, respectively.

-showExcludedFeatures

This option will cause the builder to display a list of all classes, methods and fields that where removed from the built application. Any classes, methods or fields removed from the target application through mechanisms such as smart linking (as activated through option -smart) will be displayed. In conjunction with option -smart and -notSmart, this helps one to identify what methods are excluded from the application

The output of this option consists of lines starting with the string EXCLUDED CLASS, EXCLUDED METHOD or EXCLUDED FIELD followed by the name of a class or the name and signature of a method or field, respectively.

-large

The JamaicaVM knows two representations for Java objects, the large and the small object model. The large object model is required only when reflection or dynamic class loading is used, when an application uses many (at least 63) threads or when an application allocates objects in non-heap memory (see class javax.realtime.MemoryArea).

The builder automatically uses the large object model if this is needed, with the sole exception being the use of reflection. If reflection is used, the developer is free to either use the large object model by setting option -large or to inform the builder about the number of types that are referenced through the reflection API (see option -numDynamicTypes).

The large object model requires one additional word of memory (4 bytes) for every object allocated by the Java application or allocated internally by the JamaicaVM.

-noCompaction

Specifying this option disables class file compaction. Disabling compaction forces the Jamaica Builder not to use Jamaica's compact class file format for all the classes in the created application. Not compacting the classes will cause a higher memory overhead since classes are left in the original format.

Deprecated: This option has been deprecated since version 2.5. This option will be set automatically when needed.

Compilation

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

-compile

Enable static compilation for the created application. All methods of the application are compiled into native code causing a significant speedup at runtime compared to the interpreted code that is executed by the virtual machine. It is recommended to use compilation whenever execution time is important. However, it is often sufficient to compile about 10% of the classes, which results in much smaller executables of comparable speed. You can achieve this by using -profile / -useProfile instead of -compile.

-debug

Generate a debugging version of the application. The debugging version of the Jamaica Virtual Machine uses additional runtime checks and performs additional checks in compiled code. These checks enabled debugging of bugs in native code or problems in the VM or compiled code. The additional runtime checks cause a significant slowdown of the application.

-inline=<n>

When methods are compiled (via -compile or -useProfile), this option can be used to set the level of inlining to be used by the compiler. Inlining typically causes a significant speedup at runtime since overhead to perform method calls is avoided. Nevertheless, inlining causes duplication of code and hence might increase the binary size of the application. In systems with tight memory resources, inlining might hence not be acceptable

Eleven levels of inlining are supported by the Jamaica compiler ranging from 0 (no inlining) to 10 (aggressive inlining).

-Xtrace=<level>

Enable the generation of TRACE-code at the given level. Trace code can be used for low-level debugging of compiled code. In trace mode, information on the currently executed method or instruction is printed to standard output.

There are three levels of trace information: no tracing (-Xtrace 0), tracing of method calls (-Xtrace 1), and tracing of single instructions (-Xtrace 2).

The amount of data printed to standard output when trace is enabled is typically significant. Care must be taken when this option is set, it is recommended to be used for problems that are hard to debug otherwise.

-excludeLongerThan=<n>

Compilation of large Java methods, especially in the combination of aggressive inlining can cause large C routines in the intermediate code. 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 this option.

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

-XlinkStatic=<libraries>

Libraries are "system", "jamaica", "all", or "none". The resulting binary is linked statically against those libraries, even if they were specified by -Xlibraries rather than -XstaticLibraries. "jamaica" refers to the JamaicaVM library, "system" to all other libraries. (default: not used)

-optimise (-optimize)=<type>

Specify the flags used additional to disable any optimisation when compiling the intermediate C code into native code. The optimisation flags are only passed to the C compiler if the application is compiled without the '-debug'-option.

-Xcc=<cc>

Specify the C compiler to be used to compile intermediate C code that is generated by the Jamaica Builder.

-XCFLAGS=<cflags>

Specify the cflags for the invocation of the C compiler. Note that for optimisation the compiler independent option -optimise must be used.

-Xld=<linker>

Specify the linker to be used to create a binary file from the object file generated by the C compiler.

-XLDFLAGS=<ldflags>

Specify the ldflags for the invocation of the C linker.

-Xlibraries=<libraries>

Specify the libraries that must be linked to the destination binary. The libraries must include the option that is passed to the linker. Several libraries must be separated using spaces and have to beenclosed in ". E. g, -Xlibraries "m pthread" causes linking against libm and libpthread.

-XstaticLibraries=<libraries>

Specify 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 causes larger executables, but is necessary if the target system (possibly) doesn't provide the library. Several libraries must be separated using spaces andhave to be enclosed in ". E. g, -XstaticLibraries "m pthread" causes static linking against libm and libpthread.

-XlinkDynamicPrefix=<prefix>

Specify a prefix to link a library dynamic to the created executable, e. g. "-Wl,-Bdynamic".

-XlinkStaticPrefix=<prefix>

Specify a prefix to link a library statically to the created executable, e. g. "-Wl,-Bstatic".

-XlinkDynamicFlags=<switch>

Specify flags for dynamic linkage of an executable, e. g. "-dynamic".

-XlinkStaticFlags=<switch>

Specify flags for dynamic linkage of an executable, e. g. "-static".

-XlibraryPaths=<libraryPaths>

Add 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=<strip>

Use the specified tool to remove debug information from the generated binary. This permits to reduce the size of the binary file by removing information that is not needed at runtime.

-XnewTarget=<original_target>

Introduce a new (virtual) target which uses the compiled jamaica libraries of <original_target>. E. g., "-XnewTarget.dilnetpc linux-gnu-i486" introduces the new target dilnetpc which can have its own settings in the property file, but shares its libraries with the linux-gnu-i486 target.

-target=<platform>

Specify a target platform. For a list of all available platforms of your JamaicaVM Distribution, use -XavailableTargets.

-XnoRuntimeChecks

Disable 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 anyruntime checks to fail. The lack of these checks can cause crashes, memory corruption and similardesasters. 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 options 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 MemoryAreas, division by zeroand array instantiation with negative array size.These runtime checks usually result in throwing the exceptions NullPointerException, ArrayIndexOutOfBoundsException,StringIndexOutOfBoundsException, ArrayStoreException, IllegalAssignmentError, ArithmeticException orNegativeArraySizeException. When deactivated, the system will be in an undefined state if any ofthese conditions occurs.

-XavailableTargets

List all available target platforms of this Jamaica distribution.

Memory and threads

Configuring the heap memory and threads has important impact not only on the amount of memory required by the application but as well on the runtime performance and the realtime characteristics of the code. The Jamaica Builder hence provides a number of options to configure the memory and threads of the application.

-heapSize=<n>

Set the heap size to the specified size given in bytes. The heap is allocated at startup of the application. It is used for static global information (such as the internal state of the Jamaica Virtual Machine) and for the garbage collected Java heap.

The heap size can be succeeded by the letter "k" or "m" to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes. The minimum heap size is 85k. The size of the heap has to be larger than (number of threads+1) * 2 * stack size.

-stackSize=<n>

Set the stack size to be used for the runtime stacks of all Java threads in the destination application. The stack size is used several times for different runtime stacks and for every Java thread. The stack size consequently has an important impact on the heap memory required by an application. In systems with tight memory, a small stack size should be selected.

The stack size can be succeeded by the letter "k" or "m" to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes. The minimum stack size is 1k.

Deprecated: This option has been deprecated since version 2.1. Use -javaStackSize and/or -nativeStackSize instead.

-javaStackSize=<n>

Set the stack size to be used for the Java runtime stacks of all Java threads in the built application. Each Java thread has its own stack which is allocated from the global Java heap. Thus the stack size consequently has an important impact on the heap memory required by an application. For systems with a tight amount of memory, it is recommented to select a small stack size. In the case the stack size selected is too small for running the application, an error is reported when a stack overflow occurres.

The stack size can be succeeded by the letter "k" or "m" to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes. The minimum stack size is 1k.

-nativeStackSize=<n>

Set the stack size to be used for the native runtime stacks of all Java threads in the built application. Each Java thread has its own native stack. Depending on the target system the stack is either allocated and mananged by the underlaying operation system, e. g. many *NIX systems, or allocated from the global heap, e. g. some small embedded systems. In the case the native stacks are allocated from the global heap, the stack size consequently has an important impact on the heap memory required by an application. For systems with a tight amount of memory, it is recommented to select a small stack size. In case the stack size is selected too small, it can not be guaranteed that an error is reported because stack-usage of native code is a critical part.

For some target systems, e. g. many *NIX systems, a stack size of 0 can be selected which means 'unlimited'. In that cases stack sizes are increased dynamically as needed.

The stack size can be succeeded by the letter "k" or "m" to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes. The minimum stack size is 1k if not set to 'unlimited' (value of 0).

-immortalMemorySize=<n>

Set the size of the immortal memory area given in bytes. The immortal memory area is allocated from the heap the first time it is used. The immortal memory can be accessed through the class javax.realtime.ImmortalMemory.

The immortal memory area is guaranteed never to be freed by the garbage collector. Objects allocated in this area will survive the whole application run.

-numThreads=<n>

Specify the maximum number of Java threads supported by the destination application. These threads and their runtime stacks are generated at startup of the application. A large number of threads consequently may require a significant amount of memory.

The minimum number of threads is two, one thread is the main Java thread and one thread is needed as finalizer thread.

-analyse=<tolerance>

Enable memory analyse mode with tolerance given in percent. During memory analyse mode, the memory required by the application during execution will be determined. The result is an upper bound for the actual memory required during a test run of the application. This bound is at most the specified tolerance larger than the actual amount of memory used during runtime.

The result of a test run of an application built using -analyse can then be used to configure the heap size of an application such that the garbage collection work that is performed on an allocation never exceeds the amount allowed to ensure timely execution of the application's realtime code.

Using -analyse can cause a significant slowdown of the application. The slowdown is higher for a smaller tolerance of the analysis, i.e., for a lower value specified as an argument to -analyse.

To configure the heap of an application, a version of the application using the option -analyse and, apart form this, the exactly same list of arguments for the final versions must be build. The heap size determined in a test run can then be used to build a final version using the preferred heap size with desired garbage collection overhead. Again, it must be ensured that the argument list provided to the builder for this final version must be the same as the argument list provided for the version used to analyse the memory requirements. Only the -heapSize option of the final version must be set accordingly and the final version must be built without setting -analyse.

-constGCwork=<gc-work>

Run the garbage collector in static mode. In static mode, for every unit of allocation, a constant number of units of garbage collection work is performed. Compared to dynamic mode, this causes a lower worst case execution time for the garbage collection work at an allocation and a more predictable behaviour since the amount of garbage collection work is the same fo any allocation. However, static mode causes higher average garbage collection overhead compared to dynamic mode.

The value specified is the number for units of garbage collection work to be performed for a unit of memory that is allocated. This value can be determined using a test run that was build with -analyse set.

The default setting is that static garbage collection is disabled and the amount of garbage collection work on an allocation is determined dynamically depending on the amount of free memory.

-threadPreemption=<n>

Compiled code contains special instructions that permit thread preemption. These instructions have to be executed often enough to allow a thread preemption time that is sufficient for the destination application. Since the instructions cause an overhead in code size and runtime performance one would want to generate this code as seldom as possible.

This option enables setting of the maximum number of intermediate instructions that are permitted between the execution of thread preemption code. This directly affects the maximum thread preemption time of the application. One intermediate instructions typically corresponds to 1-2 machine instructions, while there are some intermediate instrucitons (calls, array accesses) that can be more expensive (20-50 machine instructions)

The thread preemption must be at least 10 intermediate instructions.

-timeSlice=<n>

For threads of equal priority, round robin scheduling is used when several threads are running simultaneously. Through this option, the maximum size of such a time slice can be given in nanoseconds. A special synchronization thread is used that waits for the length of a time slice and permits thread switching after every time slice.

If no round robin scheduling is needed for threads of equal priority, the size of the time slice can be set to zero. In this case, the synchronization thread is not required, such that fewer system resources are needed and the highest priority threads will not be interrupted by the synchronization thread.

-finalizerPri=<pri>

Set the Java priority of the finalizer thread to <pri>. The finalizer thread is a daemon thread that runs in the background and executed the finalize() method of objects that are about to be freed by the garbage collector. The memory of objects that have a finalize() method cannot be freed before this method was executed.

A priority of zero for the finalizer thread indicates that no finalizer thread shall be created. In this case, the memory of objects that are found to be unreachable by the garbage collector cannot be freed before their finalizers are executed explicitly through a call of java.lang.Runtime.runFinalization(). Not using a finalizer thread can be useful on very small systems to reduce the use of system resources. The priority must be one of the Java priorities 1 through 10 (corresponding to the ten priority levels of java.lang.Thread).

-strictRTSJ

The Real-Time Specification for Java (RTSJ) defines a number of classes in the package javax.realtime. These classes can be used to create realtime threads with stricter semantics than normal Java threads. In particular, these threads can run in their own memory areas (scoped memory) that are not part of the Java heap, such that memory allocation is independent of garbage collector intervention. It is even possible to create threads of class javax.realtime.NoHeapRealtimeThread that may not access any objects stored on the Java heap.

In JamaicaVM, normal Java Threads do not suffer from these restrictions, thread priorities of normal threads can be in the range permitted for RealtimeThreads (see option -priMap). Furthermore, any thread can access objects allocated on the heap without having to fear being delayed by the garbage collector. Any thread is safe from being interrupted or delayed by garbage collector activity, only higher priority threads can interrupt lower priority threads.

When using JamaicaVM, it is hence not required to use non-heap memory areas for realtime tasks and it is possible for any thread to access objects on the heap. Furthermore, scoped memory provided by the classes defined in the RTSJ are available to normal threads as well.

The strict semantics of the RTSJ require a significant runtime overhead to check that an access to an object is legal. Since these checks are not needed by JamaicaVM, they are disabled by default. However, setting the option -strictRTSJ forces JamaicaVM to perform this checks.

If -strictRTSJ is set, the following checks are performed and the corresponding exceptions are thrown:

MemoryAccessError: If a NoHeapRealtimeThread attempts to access an object stored in the normal Java heap, a MemoryAccessError is thrown

IllegalStateException: If a non-RealtimeThread attempts to enter a javax.realtime.MemoryArea or tries to access the scope stack through the methods getCurrentMemoryArea, getMemoryAreaStackDepth, getOuterMemoryArea or getInitialMemoryAreaIndex defined in class javax.realtime.RealtimeThread.

-strictRTSJFromEnv=<var>

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

-heapSizeFromEnv=<var>

Specifying this options causes the creation of an application that reads its heap size from the environment variable specified using this option. If this variable is not set, the heap size specified using -heapSize <n> will be used.

-stackSizeFromEnv=<var>

Specifying this options causes the creation of an application that reads its stack size from the environment variable specified using this option. If this variable is not set, the stack size specified using -stackSize <n> will be used.

Deprecated: This option has been deprecated since version 2.1. Use -javaStackSizeFromEnv and/or -nativeStackSizeFromEnv instead.

-javaStackSizeFromEnv=<var>

Specifying this options causes the creation of an application that reads its Javastack size from the environment variable specified using this option. If this variable is not set, the stack size specified using -javaStackSize <n> will be used.

-nativeStackSizeFromEnv=<var>

Specifying this options causes the creation of an application that reads its nativestack size from the environment variable specified using this option. If this variable is not set, the stack size specified using -nativeStackSize <n> will be used.

-immortalMemorySizeFromEnv=<var>

Specifying this options causes the creation of an application that reads its immortal memory size from the environment variable specified using this option. If this variable is not set, the immortal memory size specified using -immortalMemorySize <n> will be used.

-numThreadsFromEnv=<var>

Specifying this options causes the creation of an application that reads the number of threads from the environment variable specified using this option. If this variable is not set, the number of threads specified using -numThreads <n> will be used.

-analyseFromEnv=<var>

Specifying this options causes the creation of an application that reads the amount of analyse accuracy of the garbage collector from the environment variable specified using this option. If this variable is not set, the number accuracy specified using -analyse <n> will be used. Setting the environment variable to "0" will disable the analysis and cause the garbage collector to use dynamic garbage collection mode.

-constGCworkFromEnv=<var>

Specifying this options causes the creation of an application that reads the amount of static garbage collection work on an allocation from the environment variable specified using this option. If this variable is not set, the value specified using -constGCwork <n> will be used.

-priMap=<jp=sp{,jp=sp}>

Java threads are mapped directly to threads of the operating system used on the target system. The Java priorities are mapped to system-level priorities for this purpose. This options permit one to replace the default mapping used for a target system by a specific priority mapping.

The Java thread priorities are integer values in the range 1 through 255, where 1 corresponds to the lowest priority and 255 to the highest priority. The Java priorities 1 through 10 correspond to the ten priority levels of java.lang.Thread threads, while priorities staring at 11 represent the priority levels of javax.realtime.RealtimeThread threads. The highest priority is not available for Java threads, it is used for the synchronization thread that permits round robin scheduling of threads of equal priorities.

Each single Java priority can and has to be mapped to a system priority. The mapping has to contain an entry of the form <java-priority>=<system-priority>. To simplify the description of a mapping a range of priorities can be described using <from>..<to>.

Example 1: "-priMap=1..11=50,12..39=51..78,40=85" will cause all java.lang.Thread threads to use system priority 50, while the realtime threads will be mapped to priorities 51 through 78 and the synchronization thread will use priority 85. There will be 28 priority levels available for javax.realtime.RealtimeThread threads.

Example 2: "-priMap=1..52=22..104" will cause the use of system priorities 2, 4, 6, through 102 for the Java priorities 1 through 51. The synchronization thread will use priority 104. There will be 40 priority levels available for javax.realtime.RealtimeThread threads.

-physicalMemoryRanges=<range{,range}>

The RawMemory and PhysialMemory classes in the javax.realtime package provide access to physical memory for Java applications. Through the option -physicalMemoryRanges, the memory ranges that may be accessed by the Java application can be specified. The default behaviour is that no access to physical memory is permitted by the application.

The -physicalMemoryRanges option expects a list of address ranges. Each address range is separated by <..>, it gives the lower and upper address of the range: <lower..upper>. The lower address is inclusive, the upper address is exclusive, i.e., the difference upper-lower gives the size of the accessible area. There might be an arbitrary number of memory ranges.

Example 1: "-physicalMemoryRanges=3072..4096" will allow access to the memory range from address 0x0c00 to 0x1000, i.e., to a range of 1024 bytes.

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.

-profile

Build an application that collects information on the amount of run time spend for the execution of different methods. This information is printed to standard output after a test run of the application has been performed.

Profiling information can only be collected when using the JamaicaVM interpreter, compiled code cannot be profiled. Consequently, "-profile" does not work in combination with "-compile"

The information collected in one of several profiling runs can then be used as an input for the option -useProfile to guide the compilation process.

-XprofileFilename=<name>

Set name of file for profiling data. If profiling is enabled output is writting either to this file. If an profile filename is not specified then the profile data is written to the file with the name of the destiniation (see option -destiniation) extended by the suffix '.prof'.

-percentageCompiled=<n>

Use profiling information collected using -profile to restrict compilation to those methods that were most frequently executed during the profiling run. The percentage of methods that are to be compiled is given as an argument to -percentageCompiled. It must be between 1 and 100. Selecting 100 causes compilation of all methods executed during the profiling run, i.e. all methods that were not called during profiling will not be compiled.

-useProfile=<profilelist>

Use profiling information collected using -profile to restrict compilation to those methods that were most frequently executed during the profiling run. The default percentage of methods that are to be compiled is 10, if -percentageCompiled is not set to different value.

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 additionally offers the Jamaica Binary Interface (JBI) to enable a more efficient access to native code

-object=<files>

Specify object files that contain native code that has to be linked to the destination executable. Unlike other Java implementation, Jamaica does not access native code through shared libraries. Instead, the object files that contain native code that is referenced from within Java code are linked into the destination application file.

This option expects a list of object files that are separated using the platform dependent path separator character (e. g., ":").

-include=<dirs>

Add 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=<none|ELF>

Set the object format, e. g. 'none', 'C' or 'ELF'. (default: ELF)

-XobjectGenerateCode=<C|i386|i486|i586|sparc>

Set the type of generated code in output object, e. g. 'C', 'i386' or 'sparc. (default: i386)

Analyzing

Analyzing options

-Xstats

Show compact classfile statistics. (default: not used)

-XcountCalls

Count calls and print statistics after execution. (default: not used)

-XcountArrays

Count array accesses and allocations and print statistics after execution. (default: not used)

-XcountAllocs

Count allocations for arrays and objects. (default: not used)

-XcountFields

Count accesses to fields. (default: not used)

Miscellaneous

Miscellaneous options