Builder Usage

The builder is a command-line tool. It is named jamaica. A variety of arguments control the work of the Builder tool. The arguments can be given directly to the Builder via command line, or by using configuration files. Options given at the command line take priority. Options not specified at the command line are read from configuration files in the following manner:

The following special syntax is accepted:

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

jamaica [-help (--help, -h, -?)] [-Xhelp (--Xhelp)] [-version]
        [-verbose=<n>] [-showSettings] [-saveSettings=<file>]
        [-configuration=<file>] [-classpath (-cp)=<path>]
        [-enableassertions (-ea)] [-main=<class>]
        [-jar=<JAR-file>] [-includeClasses[+]=<class/package>]
        [-excludeClasses[+]=<class/package>]
        [-excludeFromCompile[+]=<methods>]
        [-includeJAR[+]=<jarfilelist>]
        [-excludeJAR[+]=<jarfilelist>] [-lazy]
        [-lazyFromEnv=<var>] [-destination (-o)=<name>]
        [-tmpdir=<name>] [-resource[+]=<names>]
        [-setLibraries[+]=<symbol>=<value>{,<value>} | list]
        [-cldc] [-incrementalCompilation] [-closed]
        [-showIncludedFeatures] [-showExcludedFeatures]
        [-interpret (-Xint)] [-compile] [-inline=<n>]
        [-optimise (-optimize)=<type>] [-target=<platform>]
        [-heapSize=<n>[K|M]] [-maxHeapSize=<n>[K|M]]
        [-heapSizeIncrement=<n>[K|M]] [-javaStackSize=<n>[K|M]]
        [-nativeStackSize=<n>[K|M]] [-numThreads=<n>]
        [-maxNumThreads=<n>] [-numJniAttachableThreads=<n>]
        [-threadPreemption=<n>] [-timeSlice=<n>]
        [-finalizerPri=<pri>] [-heapSizeFromEnv=<var>]
        [-maxHeapSizeFromEnv=<var>]
        [-heapSizeIncrementFromEnv=<var>]
        [-javaStackSizeFromEnv=<var>]
        [-nativeStackSizeFromEnv=<var>]
        [-numThreadsFromEnv=<var>]
        [-maxNumThreadsFromEnv=<var>]
        [-numJniAttachableThreadsFromEnv=<var>]
        [-finalizerPriFromEnv=<var>]
        [-priMap=<jp>=<sp>{,<jp>=<sp>}] [-priMapFromEnv=<var>]
        [-analyse (-analyze)=<tolerance>] [-analyseFromEnv
        (-analyzeFromEnv)=<var>] [-constGCwork=<gc-work>]
        [-constGCworkFromEnv=<var>] [-stopTheWorldGC]
        [-atomicGC] [-reservedMemory=<percentage>]
        [-reservedMemoryFromEnv=<var>] [-strictRTSJ]
        [-strictRTSJFromEnv=<var>]
        [-immortalMemorySize=<n>[K|M]]
        [-immortalMemorySizeFromEnv=<var>]
        [-scopedMemorySize=<n>[K|M]]
        [-scopedMemorySizeFromEnv=<var>]
        [-physicalMemoryRanges=<range{,range}>] [-profile]
        [-XprofileFilenameFromEnv=<var>]
        [-percentageCompiled=<n>]
        [-useProfile[+]=<profilelist>] [-object[+]=<files>] 
        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.

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

The help option displays Builder usage and a short description of all possible standard command line options.

-Xhelp (--Xhelp)

The Xhelp option displays Builder usage and a short description of all possible extended command line options. Extended command line options are not needed for normal control of the Builder command. They are used to configure tools and options, and to provide tools required internally for JamaicaVM development.

-version

Print Jamaica version and exit.

-verbose=<n>

The verbose option sets 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

If the showSetting option is used, JamaicaVM Builder options currently in effect are written to stdout in property file format. To make these the default settings, copy these options into your jamaica.conf file.

-saveSettings=<file>

If the saveSettings option is used, JamaicaVM Builder options currently in effect are written to the provided file in property file format.

-configuration=<file>

The configuration option specifies a file to read the set of options used to build the application. The format used to define options must be identical to the default configuration file <JAMAICA>/target/<target name>/etc/jamaica.conf. When this option is set, the other default configuration files, i.e., <JAMAICA>/target/<target name>/etc/jamaica.conf and <HOME>/.jamaica/jamaica.conf, are ignored.

Classes, files and paths

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

-classpath (-cp)=<path>

The classpath option specifies 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.

-enableassertions (-ea)

The enableassertions option enables assertions for all classes. Assertions are disabled by default.

-main=<class>

The main option specifies 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 the main option is not specified, the first class of the classes list that is provided to the Builder is used as the main class.

-jar=<JAR-file>

The jar option specifies 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>

The includeClasses option forces the inclusion of the listed classes and packages into the created application. The listed classes with all their methods and fields will be included. This is useful or even neccessary if you use reflection with these classes.

Arguments for this option can be: a class name to include the class with all methods and fields, a package name followed by an asterisk to include all classes in the package or a package name followed by "..." to include all classes in the package and in all sub-packages of this package.

Example:

-includeClasses=java.beans.XMLEncoder:java.util.*:java.lang...
includes the class java.beans.XMLEncoder, all classes in the package java.util and all classes in the package java.lang and in all sub-packages of java.lang such as java.lang.ref.

Caution

The includeClasses option affects only the listed classes themselves. Subclasses of these classes remain subject to smart linking.

-excludeClasses=<class/package>

The excludeClasses option forces exclusion of the listed classes and packages from the created application. The listed classes with all their methods and fields will be excluded, even if they were previously included using includeJAR or includeClasses. This is useful if you want to load classes at runtime.

Arguments for this option can be: a class name to exclude the class with all methods and fields, a package name followed by an asterisk to exclude all classes in the package or a package name followed by "..." to exclude all classes in the package and in all sub-packages of this package.

Example:

-excludeClasses=java.beans.XMLEncoder:java.util.*:java.lang...
excludes the class java.beans.XMLEncoder, all classes in the package java.util and all classes in the package java.lang and in all sub-packages of java.lang such as java.lang.ref.

Caution

The excludeClasses option affects only the listed classes themselves.

-excludeFromCompile=<methods>

The excludeFromCompile option forces exclusion of the listed methods from compilation.

Separate method names by spaces and enclose them in double quotes (").

Example:

-excludeFromCompile="java/lang/Math.cos(D)D,java/lang/Math.sin(D)D"
excludes the methods double cos(double x) and double sin(double x) of class java.lang.Math .

Caution

The excludeFromCompile option affects only the listed methods themselves.

-includeJAR=<jarfilelist>

The includeJAR option forces the inclusion of all classes and all resources contained in this archive file or directory. Any archive listed here must be in the classpath or in the bootclasspath. If a class needs to be included, the implementation in the includeJAR file will not necessarily be used. Instead, the first implementation of this class which is found in the classpath will be used.This is to ensure the application behaves in the same way as it would if it were called with the jamaicavm or java command.

-excludeJAR=<jarfilelist>

The excludeJAR option forces the exclusion of all classes and resources contained in this archive file or directory. Any class and resource found will be excluded from the created application. Use this option to load an entire archive at runtime.

-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 behaviour 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 startup time of an application that refers to large library code that is not actually needed at runtime.

-lazyFromEnv=<var>

This option causes the creation of an application that reads its lazy setting from the specified environment variable. 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 (-o)=<name>

The destination option specifies 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>

The tmpdir option can be used to specify the 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 resources that are provided using resource must therefore be added to the path provided to classpath.

-setLibraries=<symbol>=<value>{,<value>} | list

The setLibraries option can be used to choose the set of libraries to be included 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 typically 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 dependencies file, which is stored in <JAMAICA_HOME>/etc/jamaica-dependencies.conf (default: graphics=xwindow).

-cldc

The cldc option forces the inclusion of all standard library code within the CLDC configuration. This "Connected Limited Device Configuration" is intended for use 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.

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.

-incrementalCompilation

If the incrementalCompilation 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 behavior. 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.

-closed

For an application that is closed, i.e., that does not load any classes dynamically that are not built into the application by the Builder, additional optimization may be performed by the Builder and the static compiler. These optimizations cause incorrect execution semantics when additional classes will be added dynamically. Setting option closed to true enables such optimizations, a significant enhancement of the performance of compiled code is usually the result.

The additional optimization performed when closed is set include static binding of virtual method calls for methods that are not redefined by any of the classes built into the application. The overhead of dynamic binding is removed and even inlining of a virtual method call becomes possible, which often results in even further possibilities for optimizations.

Note that care is needed for an open application that uses dynamic loading even when closed is not set. For an open application, it has to be ensured that all classes that should be available for dynamically loaded code need to be included fully using option includeClasses or includeJAR. Otherwise, the Builder may omit these classes (if they are not referenced by the built-in application), or it may omit parts of these classes (certain methods or fields) that happen not to be used by the built-in application.

-showIncludedFeatures

The showIncludedFeatures 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 will not be displayed. Used in conjunction with the options includeClasses, excludeClasses, includeJAR and excludeJAR this can help you to identify which methods are included in 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

The showExcludedFeatures 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 will be displayed. Used in conjunction with the options includeClasses, excludeClasses, includeJAR and excludeJAR this can help you to identify which 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.

Compilation

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

-interpret (-Xint)

The interpret option disables compilation of the application. This results in a smaller application and in faster build times, but it causes a significant slow down of the runtime performance.

If none of the options interpret, compile, or useProfile is specified, then the default compilation will be used. The default means that a pre-generated profile will be used for the system classes, and all application classes will be compiled fully. This default usually results in good performance for small applications, but it causes extreme code size increase for larger applications and it results in slow execution of applications that use the system classes in a way different than recorded in the system profile.

-compile

The compile option enables 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. 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.

-inline=<n>

When methods are compiled (via compile, useProfile, or interpret=false), 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 the overhead of performing 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 may therefore not be acceptable

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

-optimise (-optimize)=<type>

The optimise option enables to specify optimisations for the compilation of intermediate C code to native code in a platform independent manner. <type> =none|size|speed|all . The optimisation flags are only given to the C compiler if the application is compiled without the debug option.

-target=<platform>

The target option specifies a target platform. For a list of all available platforms of your JamaicaVM Distribution, use XavailableTargets.

Memory and threads

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

-heapSize=<n>[K|M]

The heapSize option sets 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 may be succeeded by the letter `K' or `M' to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes ). The minimum required heap size for a given application can be determined using option analyze.

-maxHeapSize=<n>[K|M]

The maxHeapSize option sets the maximum heap size to the specified size given in bytes. If themaximum heap size is larger than the heap size, the heap size will be increased dynamically on demand.

The maximum heap size may be succeeded by the letter `K' or `M' to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes). The minimum value is 0 (for no dynamic heap size increase).

-heapSizeIncrement=<n>[K|M]

The heapSizeIncrement option specifies the steps by which the heap size can be increased when the maximum heap size is larger than the heap size.

The maximum heap size may be succeeded by the letter `K' or `M' to specify a size in KBytes (1024 bytes) or MBytes (1048576 bytes). The minimum value is 64k.

-javaStackSize=<n>[K|M]

The javaStackSize option sets 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. The stack size consequently has an important impact on the heap memory required by an application. A small stack size is recommended for systems with tight memory constraints. If the stack size is too small for the application to run, a stack overflow will occur and a corresponding error reported.

The stack size may be followed 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>[K|M]

The nativeStackSize option sets 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 managed by the underlying operation system, as in many Unix systems, or allocated from the global heap, as in some small embedded systems. When native stacks are allocated from the global heap, stack size consequently has an important impact on the heap memory required by an application. A small stack size is recommended for systems with tight memory constraints. If the selected stack size is too small, an error may not be reported because the stack-usage of native code may cause a critical failure.

For some target systems, like many Unix systems, a stack size of 0 can be selected, meaning "unlimited". In that case the stack size is increased dynamically as needed.

The stack size may be followed 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).

-numThreads=<n>

The numThreads option specifies the initial 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 for the main Java thread and one thread for the finalizer thread.

-maxNumThreads=<n>

The maxNumThreads options specifies the maximum number of Java threads supported by the destination application. If the maximum number of threads is larger than the values specified for numThreads, threads will be added dynamically.

Adding new threads requires unfragmented heap memory, it is therefore strongly recommended to use -maxNumThreads only in conjunction with maxHeapSize set to a value larger than heapSize. This will permit the VM to increase the heap when memory is fragmented.

The absolute maximum number of threads for the JamaicaVM is 511.

-numJniAttachableThreads=<n>

The numJniAttachableThreads specifies the initial number of Java thread structures that will be allocated and reserved for calls to the JNI Invocation API functions JNI_AttachCurrentThread and JNI_AttachCurrentThreadAsDaemon. These threads will be allocated on VM startup, such that no additional allocation is required on a later call to JNI_AttachCurrentThread or JNI_AttachCurrentThreadAsDaemon.

Even if this option is set to zero, it still will be possible to use JNI_AttachCurrentThread and JNI_AttachCurrentThreadAsDaemon. However, then these threads will be allocated dynamically when needed.

Since non-fragmented memory is required for the allocation of these threads, a later allocation may require heap expansion or may fail due to fragmented memory. It is therefore recommended to pre-allocate these threads.

The number of JNI attachable threads that will be required is the number of threads that will be attached simultaneously. Any thread structure that will be detached via JNI_DetachCurrentThread will become available again and can be used by a different thread that calls JNI_AttachCurrentThread or JNI_AttachCurrentThreadAsDaemon.

-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. As the instructions cause an overhead in code size and runtime performance one would want to generate this code as rarely as possible.

The threadPreemption 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 instruction typically corresponds to 1-2 machine instructions. There are some intermediate instructions (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. Using the timeSlice 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, so fewer system resources are needed and the highest priority threads will not be interrupted by the synchronization thread.

-finalizerPri=<pri>

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

If the finalizer thread priority is set to zero, no finalizer thread will be created. In that case, the memory of objects that are found to be unreachable by the garbage collector cannot be freed before their finalizers are executed explicitly by calling java.lang.Runtime.runFinalization(). It can be useful on very small systems not to use a finalizer thread. This reduces 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).

-heapSizeFromEnv=<var>

The heapSizeFromEnv option enables the application to read its heap size from the specified environment variable. If this variable is not set, the heap size specified using "-heapSize <n>" will be used.

-maxHeapSizeFromEnv=<var>

The maxHeapSizeFromEnv option enables the application to read its maximum heap size from the specified environment variable. If this variable is not set, the maximum heap size specified using "-maxHeapSize <n>" will be used.

-heapSizeIncrementFromEnv=<var>

The heapSizeIncrementFromEnv option enables the application to read its heap size increment from the specified environment variable. If this variable is not set, the heap size increment specified using "-heapSizeIncrement <n>" will be used.

-javaStackSizeFromEnv=<var>

The javaStackSizeFromEnv option enables the application to read its Java stack size from the specified environment variable. If this variable is not set, the stack size specified using "-javaStackSize <n>" will be used.

-nativeStackSizeFromEnv=<var>

The nativeStackSizeFromEnv option enables the application to read its native stack size from the specified environment variable. If this variable is not set, the stack size specified using "-nativeStackSize <n>" will be used.

-numThreadsFromEnv=<var>

The numThreadsFromEnv option enables the application to read the number of threads from the specified environment variable. If this variable is not set, the number of threads specified using "-numThreads <n>" will be used.

-maxNumThreadsFromEnv=<var>

The maxNumThreadsFromEnv option enables the application to read the maximum number of threads from the specified environment variable. If this variable is not set, the maximum number of threads specified using "-maxNumThreads <n>" will be used.

-numJniAttachableThreadsFromEnv=<var>

The numJniAttachableThreadsFromEnv option enables the application to read its initial number of JNI attachable threads from the environment variable specified within. If this variable is not set, the value specified using "-numJniAttachableThreads <n>" will be used.

-finalizerPriFromEnv=<var>

The finalizerPriFromEnv option enables the application to read its finalizer priority from the environment variable specified within. If this variable is not set, the finalizer priority specified using "-finalizerPri <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. The priMap option allows one to replace the default mapping used for a target system with a specific priority mapping.

Java thread priorities are integer values in the range 1 through 127, where 1 corresponds to the lowest priority and 127 to the highest priority. Since not all Java priorities need (or can) be mapped to system-level priorities, the maximal avialable Java priority may be less than 127. The Java priorities 1 through 10 correspond to the ten priority levels of java.lang.Thread threads, while priorities starting at 11 represent the priority levels of javax.realtime.RealtimeThread threads. The maximal priority is not available for Java threads as it is used for the synchronization thread that permits round robin scheduling of threads of equal priorities.

Each single Java priority up to the maximal priority can and must be mapped to a system priority. The mapping must 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.

Note: If no round robin scheduling is needed for threads of equal priority and the timeslice is set to zero (-timeSlice=0 ), the synchronization thread is not required and an additional priority is available for the real-time threds.

-priMapFromEnv=<var>

The priMapFromEnv option creates an application that reads the priority mapping of Java threads to native threads from the environment variable <var>. If this variable is not set, the mapping specified using -priMap <jp=sp{,jp=sp}> will be used (default: not used).

GC configuration

The following options provide ways to analyze the application's memory demand and to use this information to configure the garbage collector for the desired realtime behavior.

-analyse (-analyze)=<tolerance>

The analyse option enables memory analyze mode with tolerance given in percent. In memory analyze mode, the memory required by the application during execution is 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 analyze can then be used to estimate and 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 analyze can cause a significant slowdown of the application. The application slows down as the tolerance is reduced, i.e., the lower the value specified as an argument to analyze, the slower the application will run.

In order to configure the application heap, a version of the application must be built using the option analyze and, in addition, the exact list of arguments used for the final version. 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. To reiterate, the argument list provided to the Builder for this final version must be the same as the argument list for the version used to analyze the memory requirements. Only the heapSize option of the final version must be set accordingly and the final version must be built without setting analyze.

-analyseFromEnv (-analyzeFromEnv)=<var>

The analyseFromEnv option enables the application to read the amount of analyze accuracy of the garbage collector from the environment variable specified within. If this variable is not set, the number accuracy specified using "-analyze <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.

-constGCwork=<gc-work>

The constGCwork option runs 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. This results in a lower worst case execution time for the garbage collection work and allocation and more predictable behavior, compared with dynamic mode, because the amount of garbage collection work is the same for 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 built with -analyze set.

A value of `0' for this option chooses the dynamic GC work determination that is the default for JamaicaVM.

A value of `-1' enables a stop-the-world GC, see option stopTheWorldGC for more information.

A value of `-2' enables a atomic GC, see option atomicGC for more information.

The default setting chooses dynamic GC: the amount of garbage collection work on an allocation is then determined dynamically depending on the amount of free memory.

-constGCworkFromEnv=<var>

The constGCworkFromEnv option enables the application to read the amount of static garbage collection work on an allocation from the environment variable specified within. If this variable is not set, the value specified using "-constGCwork <n>" will be used.

-stopTheWorldGC

The stopTheWorldGC option enables blocking GC, i.e., no GC activity is performed until the heap is fully filled. Only then, a complete GC cycle is performed at once, causing a potentially long pause for the application. During this GC cycle, any thread that performs heap memory allocation will be blocked, but threads that do not perform heap allocation may continue to run.

If stop-the-world GC is enabled via this option, then even RealtimeThreads and NoHeapRealtimeThreads may be blocked by GC activity if they allocate heap memory. RealtimeThreads and NoHeapRealtimeThreads that run in ScopedMemory or ImmortalMemory will not be stopped by the GC.

A stop-the-world GC enables a higher average throughput compared to incremental GC, but at the cost of losing realtime behaviour for all threads that perform heap allocation.

-atomicGC

The atomicGC option enables atomic GC, i.e., no GC activity is performed until the heap is fully filled. Only then, a complete GC cycle is performed at once, causing a potentially long pause for the application. During this GC cycle, all Java threads will be blocked.

When this option is set, even NoHeapRealtimeThreads will be stopped by GC work, so all realtime guranatees will be lost!

This mode permits more efficient code compared to stopTheWorldGC since it disables certain tracking code (write barriers) that is required for the incremental GC.

-reservedMemory=<percentage>

JamaicaVM's realtime garbage collector performs GC work at allocation time. This may reduce the responsiveness of applications that have long pause times with little or no activity and are preempted by sudden activities that require a burst of memory allocation. The responsiveness of such burst allocations can be improved significantly via reserved memory.

If the reservedMemory option is set to a value larger 0, then a low priority thread will be created that continuously tries to reserve memory up to the percentage of the total heap size that is selected via this option. Any thread that performs memory allocation will then use this reserved memory to satisfy its allocations whenever there is reserved memory available. For these allocations of reserved memory, no GC work needs to be performed since the low priority reservation thread has done this work already. Only when the reserved memory is exhausted will GC work to allow further allocations be performed.

The overall effect is that a burst of allocations up to the amount of reserved memory followed by a pause in activity that was long enough during this allocation will require no GC work to perform the allocation. However, any thread that performs more allocation than the amount of memory that is currently reserved will fall back to the performing GC work at allocation time.

The disadvantage of using reserved memory is that the worst-case GC work that is required per unit of allocation increases as the size of reserved memory is increased. For a detailed output of the effect of using reserved memory, run the application with option -analyse set together with the desired value of reserved memory.

-reservedMemoryFromEnv=<var>

The reservedMemoryFromEnv option enables the application to read the percentage of reserved memory from the environment variable specified within. If this variable is not set, the value specified using "-reservedMemory <n>" will be used.See option reservedMemory for more information on the effect of this option.

RTSJ settings

The following options set values that are relevant for the Real-Time Specification for Java extensions through classes javax.realtime.* that are provided by JamaicaVM.

-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 thus not necessary to use non-heap memory areas for realtime tasks. 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 these 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.

Lazy linking is automatically disabled when strictRTSJ is set. This avoids runtime assignment errors due to lazily linked classes that may be allocated in a memory area that is incompatible with a current scoped memory allocation context when lazy linking is performed.

-strictRTSJFromEnv=<var>

The strictRTSJFromEnv option enables the application to read its strictRTSJ setting from the environment variable specified within. 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").

-immortalMemorySize=<n>[K|M]

The immortalMemorySize option sets the size of the immortal memory area, in bytes. 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.

-immortalMemorySizeFromEnv=<var>

The immortalMemorySizeFromEnv option enables the application to read 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.

-scopedMemorySize=<n>[K|M]

The scopedMemorySize option sets the amount memory that should be made available for scoped memory areas javax.realtime.LTMemory and javax.realtime.VTMemory. This memory lies outside of the normal Java heap, but it is nevertheless scanned by the garbage collector for references to the heap.

Objects allocated in scoped memory will never be reclaimed by the garbage collector. Instead, their memory will be freed when the last thread exits a the scope.

-scopedMemorySizeFromEnv=<var>

The scopedMemorySizeFromEnv option enables the application to read its scoped memory size from the environment variable specified within. If this variable is not set, the scoped memory size specified using "-scopedMemorySize <n>" will be used.

-physicalMemoryRanges=<range{,range}>

The RawMemory and PhysicalMemory classes in the javax.realtime package provide access to physical memory for Java applications. The memory ranges that may be accessed by the Java application can be specified using the option physicalMemoryRanges. The default behavior 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 "<..>", and gives the lower and upper address of the range: "<lower..upper>". The lower address is inclusive and the upper address is exclusive. I.e., the difference upper-lower gives the size of the accessible area. There can be an arbitrary number of memory ranges.

Example: "-physicalMemoryRanges=0x0c00..0x1000" 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

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

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

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

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

-XprofileFilenameFromEnv=<var>

The XprofileFilenameFromEnv creates an application that reads the name of a file for profiling data from the environment variable <var>. If this variable is not set, the name specified using XprofileFilename will be used (default: not used).

-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 0 and 100. Selecting 100 causes compilation of all methods executed during the profiling run, i.e., methods that were not called during profiling will not be compiled.

-useProfile=<profilelist>

The useProfile option uses profiling information collected using profile to restrict compilation to those methods that were most frequently executed during the profiling run. The percentage of methods to be compiled is 10 by default, unless percentageCompiled is set to a different value.

It is possible to use this option in combination with the option profile . This may be useful when the fully interpreted application is too slow to obtain a meaningful profile. In such a case one may achieve sufficient speed up through an initial profile, and use the profiled application to obtain a more precise profile for the final build.

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.

-object=<files>

The object option specifies object files that contain native code that has to be linked to the destination executable. Unlike other Java implementations, Jamaica does not access native code through shared libraries. Instead, the object files that contain native code 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., `:').