mBooster User Guide

mBooster is a command line tool. It is designed to be easily integrated into build systems and IDEs. mBooster is designed to be compliant with the JVM specification, hence it will work with all other development tools compliant with the JVM specification.

Development tool chain

In a typical J2ME CLDC MIDP development environment, the following development tools are part of the software build process:

• Java compiler, typically JavaC
• Obfuscator, such as Proguard
• Pre-verifier, typically the pre-verifier in Sun's Wireless Tool Kit

It is generally recommended to insert mBooster into the toolchain after the Obfuscator, and to use the integrated pre-verifier in mBooster instead of Sun's pre-verifier:

Be Careful Some obfucators such as Proguard are not 100% compliant to the JVM specification. As such they have difficulties working with mBooster optimized classfiles. It is therefore not recommended to insert mBooster in the toolchain in front of these non-compliant obfuscators.

mBooster incorporates an integrated pre-verifier that generates stackmap information for the optimized classfiles, removing the need for a separate step in the build process to run a pre-verifier. The intergrated pre-verfier typically produces more compact stackmap information than is possible with Sun's preverifier.

Key concept: Entry points

mBooster takes a complete J2ME CLDC MIDP midlet as a set of classfiles, optimizes it and generates an optimized version as a set of classfiles, or a JAR file.

mBooster needs to know the entry points for the midlet, so that it can fully analyse the application. To specify the entry points, you need to define the MIDLETCLASSES property in the properties file, or through -c command line option. The entry points of a J2ME CLDC application are the subclasses of javax.microedition.midlet.MIDlet defined in the midlet-1, midlet-2, ... tags in the /META-INF/MANIFEST.MF

.

When Read Manifest Mode is enabled, mBooster will automatically determine the entry points for the midlet from the manifest file /META-INF/MANIFEST.MF.

Key concept: Classpaths

mBooster locates the classes to be loaded through two classpaths.

LIB.CLASSPATH defines the classpath to locate the classes that reside on the mobile phone. Typically this should point to the library JAR files in the Wireless Tool Kit or a vendor specific mobile development kit.

APP.CLASSPATH defines the classpath to locate the application classes. The classes in APP.CLASSPATH will be analysed, optimized, and output to the defined output location. If you are using a third party library such as a billing library or backend communication library that is not part of the phone resident API, include it in the APP.CLASSPATH

Notes:
1. When mBooster locates a class of a given name on both library classpath (LIB.CLASSPATH) and application classpath (APP.CLASSPATH), the class in the library classpath always takes precedence.

2. A class in the library classpath is not allowed to reference a class in the application classpath in any way, including:

• Subclassing an application class
• Implementing an application interface
• Declaring a field of the type of an application class, or an array of an application class
• Declaring a method with a result type of an application class, or an array of an application class
• Declaring a method with a parameter type of an application class, or an array of an application class

Running mBooster

mBooster is a command line application. mBooster takes its execution parameters (properties) from three different sources, in the following order of precedence:
1. Command line options other than -D
2. Property override defined through -D command line option on the command line
3. Properties defined in the properties file as specified through -p option on the command line

Example command line

mBooster -m -a Input.jar -r Input.jar -o Output.jar 
  -l "C:/wireless toolkit/lib/cldcapi11.jar;C:/wireless toolkit/lib/midpapi20.jar"

The above example would take the input classfiles and resource files from Input.jar and output the optimized midlet to Output.jar. The Read Manifest Mode is turned on. The library JAR files are C:/wireless toolkit/lib/cldcapi11.jar and C:/wireless toolkit/lib/midpapi20.jar.

mBooster -m -a Input.jar -r Input.jar -o Output.jar -p myprops.properties

In this second example, mBooster is configured to read in the input classfiles and resource files from Input.jar and output the optimized midlet to Output.jar. The Read Manifest Mode is turned on. Additional properties are specified in myprops.properties

Command line parameters

mBooster has the following command line parameters, which can be used as an alternative to, or in addition to, a properties file. It is important to note that any paths specified in the command line that contain spaces must be wrapped in "quotes". Both forward and/or backward slashes can be used in paths in the command line.

-p <filename>

Function:
Load the properties file from the specified file

Example:
-p "C:/my config/default_mbooster.properties"

-c <classnames>

Function:
Specifies the main midlet classes to load. These are the entry points, delimited by semi-colons.

Example:
-c game.main.GameMIDlet

Equivalent property:
MIDLETCLASSES

See also:
Read Manifest Mode

-a <classpath>

Function:
Specifies the input JAR files or directories where the application classfiles are located, delimited by semi-colons.
Note: For mBooster Remote Access Client, it is not allowed to specify directories in this property.

Example:
-a "C:/dev/obfuscated/app.jar"

Equivalent property:
APP.CLASSPATH

-l <classpath>

Function:
Specifies the library classpath to be used, delimited by semi-colons.
Note: For mBooster Remote Access Client, it is not allowed to specify directories in this property.

Example:
-l "C:/wireless toolkit/lib/cldcapi11.jar;C:/wireless toolkit/lib/midpapi20.jar"

Equivalent property:
LIB.CLASSPATH

-r <filepath>

Function:
Specifies the input JAR files or directories where resource files are located, delimited by semi-colons. Any non-classfiles found in the specified directories and JAR files specified will be included in the output, with their directory structure intact.
Note: For mBooster Remote Access Client, it is not allowed to specify directories in this property.

Example:
-r "C:/dev/obfuscated/app.jar;C:/dev/resource"

Equivalent property:
RESOURCE.PATH

-o <output directory or JAR file>

Function:
Specifies the output JAR file, or the output directory
Note: For mBooster Remote Access Client, it is not allowed to specify a directory in this property.

Example:
-o C:/MyApp_Optimized.jar
OR
-o C:/MyApp_Optimized_Dir

Equivalent property:
OUTPUT.PATH

-s <filepath>

Function:
Output statistics to the specified filepath.

Example:
-s "C:/stats/MyGame.log"

Equivalent property:
OUTPUT.STATISTICS.ENABLED and OUTPUT.STATISTICS.FILE. Setting this switch is equivalent to setting the property OUTPUT.STATISTICS.ENABLED to ON and setting the OUTPUT.STATISTICS.FILE property to the given filepath.

-m

Function:
Turns on Read Manifest Mode

.

Equivalent property:
READ.MANIFEST

-h

Function:
Print basic help and exit

-v

Function:
Print the version and exit

-D <name=value>

Function:
Set a property with the given name 'name' to the given value 'value'. This will override any value for the property already present in the properties file, but this can be overriden itself by any of the other command line parameters.

Example:
-D OUTPUT.PATH=C:/MyApp_Optimized.jar

Properties file format

A properties file is a standard Java property file, consisting of 'key = value' pairs, where the property name is the key for the pair. Quotes must not be placed around any of the property values, which is different to command line parameters where they are necessary for long paths that contain spaces. Forward slashes rather than backward slashes should be used in paths in the values given to properties. Comments can be placed in the properties file, by preceding any line with the '#' character.

# Properties for PlatformGame
# Lines preceded by '#' are ignored

# Turns on Read Manifest Mode to automatically deduce MIDLETCLASSES 
# and RESOURCE.PACKING.EXCLUDE 
READ.MANIFEST = ON

# The location of the library classes used by the midlet
LIB.CLASSPATH = C:/java/WTK21/lib/cldcapi11.jar;C:/java/WTK21/lib/midpapi20.jar

# The location of the midlet classes to be optimised
APP.CLASSPATH = C:/dev/obfuscated/output/platform.jar
# The location from which the resource files are read in
RESOURCE.PATH = C:/dev/obfuscated/output/platform.jar

# Enable running of the integrated preverifier
PREVERIFIER.ENABLED = ON
PREVERIFIER.METHOD = INTERNAL

# Output into a JAR file
OUTPUT.PATH = C:/dev/optimized/platform.jar

# Uses the mBoosterZip compressor to produce the smallest JAR file
JAR.METHOD = MBOOSTERZIP

Read Manifest Mode

A J2ME CLDC MIDP midlet is required to contain a manifest file /META-INF/MANIFEST.MF containing critical information about the midlet. mBooster is able to interpret the manifest file, and automatically set the MIDLETCLASSES and RESOURCE.PACKING.EXCLUDE properties based on the information in the manifest file. This mode is enabled by setting the -m switch in the command-line or READ.MANIFEST property. When this mode is turned on, mBooster will locate the manifest file within the RESOURCE.PATH. There must exist exactly one /META-INF/MANIFEST.MF file.

When this mode is enabled, mBooster will:

• Add all the main classes (subclass of javax.microedition.midlet.MIDlet) specified in MIDlet-x entries to the MIDLETCLASSES property, to be optimized by mBooster,
• When Resource Packing optimization is enabled, the icon files referenced in the MIDlet-x and MIDlet-Icon entries will be added to the RESOURCE.PACKING.EXCLUDE property, used to indicate that these files must not be combined with other resources into the resource pack files.

Reflection

If the application contains reflection calls, mBooster must be informed through setting the REFLECTEDCLASSES property. Reflection calls include:

• public static java.lang.Class java.lang.Class.forName(String)
• public void java.lang.Class.newInstance()
• public java.lang.Class java.lang.Object.getClass()

Be Careful Since mBooster 2-6, incorrect or missing specification of the REFLECTEDCLASSES property will cause a warning or error to be produced in mBooster. The check of reflection calls for the java.lang.Class.forName(String) function can be disabled by setting the NOCHECK.REFLECTEDCLASSES property. Otherwise if the REFLECTEDCLASSES property is not set for a MIDlet that requires it or is set incorrectly, mBooster will fail with an error. If it is set in a way that may not be complete, mBooster will print a warning and continue.

mBooster Reproducibility

The output and behavior of mBooster is completely reproducible, whenever the configured properties remain unchanged.

mBooster Result Caching

Note: mBooster Evaluation Version disables this feature.
mBooster now contains partial result caching. This feature speeds up mBooster when mBooster optimizes the same application (or variant) in the future.

Configuring mBooster Result Caching

The mBooster result cache directory is defined by the Windows environment variable mBooster_cache_path. If this environment variable is not defined, mBooster will create a cache directory named mbooster-cache under the user home directory.

The mBooster result cache size is defined by the Windows environment variable mBooster_cache_size_limit. If this environment variable is not defined, the cache size will be set to 40MB, adequate for approximately 50 Nokia Series 60 applications.

It is also possible to override the mBooster result cache configuration through this set of properties. However this is generally not recommended.

Sharing mBooster Result Cache Across Multiple Computers

It is possible for multiple computers to share mBooster results cached on a remote network directory. This arrangement is particularly beneficial if you operate a build server farm, or when multiple programmers are working on the same application. The execution of mBooster would be accelerated if your colleagues had run mBooster on a similar variant of the same application.

When multiple computers share a mBooster result cache, it is important that all participating computers have the same mBooster result cache size limit set. It is also recommended to increase the cache size to 100MB or higher.

Controlling memory use

mBooster is a very memory-intensive application, and it is possible to adjust its own memory limit to better suit the execution environment. There is a special windows environment variable that specifies the amount of memory mBooster can use, to set this we recommend the following procedure:

1. Create a text file in the installation directory containing:

   SET JETVMPROP=-Djet.gc.heaplimit:XXXXm
   call mBooster %*

   
   (Where XXXX is the memory limit to run mBooster within, in MB)
2. Name this file mBoosterCustom.bat
3. To run mBooster, call mBoosterCustom.bat instead of mBooster.exe

This value, the heaplimit is 512(MB) by default.
Ideally the heaplimit value wants to be set so that mBooster only uses physical memory, never paging memory to the hard-disk, but still will not throw any java.lang.OutOfMemoryError.

Be Careful Running concurrent builds of mBooster can consume a lot of memory, and performance will degrade if not enough physical memory is available to all instances of mBooster.

Be Careful Setting this environment variable outside of the .bat file approach described above may interfere with other applications running on your system.

— Previous page – Contents – Next page —