C H A P T E R 7 - Java Wireless Client Software Build System

C H A P T E R 7

Java Wireless Client Software Build System

The build system for the Java Wireless Client software builds MIDP and any optional APIs you wish to include. This build system is based in the midp directory, but it is capable of including optional API source code from other locations.

Overview

To perform the build, find the midp/build subdirectory that corresponds to the platform for which you are building. For example, if you want to build the Java Wireless Client software on top of the JavaCall API, perform the build in midp/build/javacall.

You need to tell the build system about the lower layers upon which you are building, as follows:

Set CLDC_DIST_DIR to the dist directory of the CLDC build.

Set PCSL_OUTPUT_DIR to the output directory of the PCSL build.

If you are using the JavaCall API, set JAVACALL_OUTPUT_DIR to the same value you used when you built the JavaCall API. Also set JAVACALL_PLATFORM to the right value for your target platform.

You must also set JDK_DIR to point to your installation of the JDK software.

In addition, the Java Wireless Client software build uses some internal tools. Use TOOLS_DIR to point to the tools directory.

Finally, the output of the Java Wireless Client software build is placed in MIDP_OUTPUT_DIR.

TABLE 7-1 lists and describes the build targets for the Java Wireless Client software build system.

TABLE 7-1 Java Wireless Client Software Build Targets
Target	Description
`all`(default)	Creates the executables, classes, and tools for an implementation of the Java Wireless Client software.
`parallel_all`	Makes possible more effective building of Java Wireless Client modules, by allowing more than one make to be run in parallel. Example: `$` `make` `parallel_all` `NUM_JOBS=4`
`docs_html`	Generates Porting API documentation. Define `DOXYGEN_CMD` to point to your installation of Doxygen.
`clean`	Removes all build output files.

Output

Many output directories are placed in $MIDP_OUTPUT_DIR, but you do not need all of it. The appdb, bin, and lib directories contains everything you need to run an executable on your target device.

Debugging Symbols

TABLE 7-2 shows the build options that control the build's debug configuration. All of the options are false by default. To enable a debugging option, set it to true.

TABLE 7-2 Debugging Selection Options
Name	Description
`USE_DEBUG`	Builds an implementation that enables debug in the build. This preserves symbols in both class file and executables. Useful when Java platform stack trace is needed or native debugger is used.
`USE_I3_TEST`	Build an implementation with unit tests. Run all unit tests with `bin/i3test` command.
`USE_JAVA_DEBUGGER`	Enables Java platform debugger support, also known as KDWP. Allows debugging on installed MIDlet classes. To enable debugging on ROMized system classes, use this option with `USE_DEBUG=true`. Example: `USE_JAVA_DEBUGGER=true`
`USE_JAVA_PROFILER`	Enables CLDC HotSpot Implementation profiler feature, used by the Sun Java Wireless Toolkit.

When you want to make adjustments to the debugging options, first make clean to get a fresh start. Then set debugging options and build the Java Wireless Client software again.

API Documentation

The Java Wireless Client software generates API reference documentation using Doxygen and javadoc. Doxygen is available at http://doxygen.org/.

The build system assumes that Doxygen is located at /usr/bin/doxygen. You can override this value on the command line by defining DOXYGEN_CMD.

javadoc is part of the JDK software, so it is found as long as JDK_DIR is defined.

Build Options

This section describes options you can use to control the Java Wireless Client software build.

CLDC Selection

TABLE 7-3 shows the build options that control the CLDC technology in the build.

TABLE 7-3 CLDC Selection Options
Name	Values	Description
`USE_CLDC_11`	`true` (default) `false`	Builds an implementation that is compliant with the CLDC 1.1 Specification. If this variable is `false`, CLDC 1.0 is used instead.
`USE_CLDC_RELEASE`	`false` (default) `true`	For non-debug builds, setting this variable to `false` means that the product version of CLDC is linked. This provides the best footprint and performance, with no debug or tracing facilities.
`USE_MONET`	false (default) true	Enables on-device support (conversion and loading) of binary application image files for fast class loading.

Module Selection

TABLE 7-4 shows the build options that control which LCDUI and AMS implementations are in the build.

TABLE 7-4 Module Selection Options
Name	Value	Description
`SUBSYSTEM_LCDUI_MODULES`	`chameleon` (default) `platform_widget`	`chameleon` builds an implementation that uses adaptive user-interface technology. `platform_widget` uses Qt native widgets.
`USE_NATIVE_AMS`	`false` (default) `true`	When `false`, builds an implementation that uses the AMS written in the Java programming language. When `true`, builds an implementation that uses a native AMS.

Native AMS Image Resource Policy

Image resources in a native AMS are usually stored in PNG format. However, decoding compressed PNG images takes time while the Java Wireless Client software starts up. To start faster, images can be stored in a platform-dependent raw format that is faster to load.

When you set the build option USE_NATIVE_AMS=true, you can improve startup performance by also setting USE_RAW_AMS_IMAGES=true. The trade-off for this optimization is an increase in memory needed to store the raw image resources.

If the build option USE_NATIVE_AMS=true, and the build option USE_RAW_AMS_IMAGES=false, the original PNG image resources of the AMS are used during the build process.

Multitasking

USE_MULTIPLE_ISOLATES controls multitasking in the build. When set to true, the Java Wireless Client software can run more than one MIDlet at the same time. The default is false, which means that only one MIDlet can be run at a time.

Startup Performance

The USE_VERIFY_ONCE option determines whether a MIDlet's classes are preverified when the MIDlet is installed (true) or every time the MIDlet is run (false). Preverifying during installation (true) improves MIDlet startup time.

Resource Allocation Policy

When USE_FIXED is false, the implementation uses the default resource policy, open-for-competition. This is the default value.

When USE_FIXED is true, the implementation uses a fixed partition resource policy.

Cryptography Selection

TABLE 7-5 shows the build options that control the cryptography configuration in the build.

TABLE 7-5 SSL Selection Options
Name	Values	Description
`USE_SSL`	`true` `false` (default)	Controls whether the implementation uses SSL. This does not affect security for OTA and SATSA. For that, see `USE_RESTRICTED_CRYPTO`.
`USE_RESTRICTED_CRYPTO`	`true` `false` (default)	Includes ciphers and the features that depend on ciphers, which are secure OTA, `SecureConnection`, HTTPS, and SATSA-CRYPTO (JSR 177).
RESTRICTED_CRYPTO_DIR		Required when `USE_RESTRICTED_CRYPTO=true`. Customers must provide their own crypto library.

Server Socket Selection

USE_SERVER_SOCKET controls whether server socket support is included in the build. Use true, the default value, to include server socket support.

Runtime Java Platform Properties Selection

Java platform properties can be hard-coded in the Java Wireless Client software, or they can be loaded from files at runtime. Hard-coding is faster, but using files is more flexible.

USE_STATIC_PROPERTIES controls this behavior. The default value is true, which means hard-coded values are used. Set USE_STATIC_PROPERTIES to false to load properties from files. The default file locations are lib/internal.config and lib/system.config in MIDP_OUTPUT_DIR.

Specifying a Target CPU and Device

The TARGET_CPU option specifies the type of processor for which you are building the software. TARGET_DEVICE makes it possible to be even more specific.

Use the TARGET_DEVICE build option to select configuration parameters within a specific platform. Valid values are omap730, zaurus, and x86. This value is appended to the names of input files for the configurator tool (see the Porting Guide for details).

For linux_qt and linux_fb builds, the default value of TARGET_DEVICE is x86. However, if TARGET_CPU is set to arm, then TARGET_DEVICE will default to omap730.

For wince, javacall, and win32 builds, the default value for TARGET_DEVICE is x86.

Build Constraints

Some build options can be used together and others cannot. For example, some build combinations require the option USE_MULTIPLE_ISOLATES=true for other options to work.

Following are the known constraints when building the Java Wireless Client software:

If SUBSYSTEM_LCDUI_MODULES=platform_widget, you must build using one of the qte configurations.

If USE_NATIVE_AMS=true, you must also set USE_MULTIPLES_ISOLATES=true.

If USE_FIXED=true, you must also set USE_MULTIPLES_ISOLATES=true.

If USE_MULTIPLES_ISOLATES=true, you must also set SUBSYSTEM_LCDUI_MODULES=chameleon.

If USE_MONET=true, you must set USE_VERIFY_ONCE=false, and vice-versa.

If USE_SSL=true, you must also set USE_RESTRICTED_CRYPTO=true.

Including Optional APIs

In general, optional APIs can be included by defining two variables. The first enables the API and has the form USE_JSR_XXX. The second specifies where to find the source code for the API and has the form JSR_XXX_DIR.

Most JSRs define a single API, but some contain more than one. JSR 75, for example, includes a PIM API and a FileConnection API. JSR 177 defines four distinct optional APIs. The build flags described in this section affect all the APIs defined in a JSR.

For example, if you want to include the JSR 75 PIM and FileConnection APIs, set USE_JSR_75 to true and set JSR_75_DIR to jwc/jsr75, where jwc is the installation directory of the Java Wireless Client software.

Unless you specify otherwise, all the USE_JSR_XXX flags are false.

When you are building with the JavaCall API, you must provide identical sets of optional API flags to the JavaCall API build and the Java Wireless Client software build. For example, if you wish to build Java Wireless Client software with USE_JSR_120=true, you must first build the JavaCall API with USE_JSR_120=true.

The Java Wireless Client software supports the following JSRs and their corresponding build flags:

JSR 75

JSR 82

JSR 120

JSR 135

JSR 172

JSR 177

JSR 179

JSR 180

JSR 205

JSR 211

JSR 226

JSR 229

JSR 238

JSR 239

Some JSRs have more complicated builds. The next section describes how to build these optional APIs.

Optional API Details

This section describes additional steps that need to be performed in order to build some of the optional APIs.

Building JSR 120 and JSR 205

Unlike the JSRs, which can be built independently of each other, a dependency exists between the Wireless Messaging 1.0 optional API (JSR 120) and the Wireless Messaging 2.0 optional API (JSR 205). JSR 205 is a superset of JSR 120.

To properly build JSR 205, you must have an implementation of JSR 120 available, and USE_JSR_120 and USE_JSR_205 must both be set to true.

You must also set JSR_205_DIR to the location of your JSR 205 source files, for example:

JSR_205_DIR=jwc/jsr205

Building JSR 135

Support for JPEG image format is a requirement of the MSA-248 Specification. Therefore, the JPEG decoder in your build is dependent upon the graphics platform used in your JSR 135 implementation.

For example, if you build a linux_qte configuration, the JSR 135 implementation can use the JPEG decoder from Qt. Therefore, no JPEG decoder is needed and the build option USE_JPEG=false is set.

On the other hand, if you build a linux_fb configuration, the JSR 135 implementation does not contain its own JPEG decoder and must be picked up from somewhere else. Therefore, set USE_JPEG to true and JPEG_DIR to the JPEG codec source code directory, most likely jwc/jpeg.

Building JSR 177

To properly build the Security and Trust Services APIs (JSR 177) optional package, you must set the USE_JSR_177 and JSR_177_DIR variables as described previously. You must also have the Java Card trademark Development Kit 2.2.1 installed on your build platform.

The Java Card Development Kit is available at http://java.sun.com/products/javacard/dev_kit.html.

Set JC_DIR to the location of your Java Card Development Kit 2.2.1 installation, like this:

JC_DIR=/java_card_kit-2.2.1

Building JSR 226

The JSR 226 SVG API uses a renderer called Pisces. When you set USE_JSR_226 to true, you must also set PISCES_DIR to point to the Pisces source files, usually jwc/pisces.

JSR 226 uses the XML parser that is part of JSR 172 (Web Services). If you plan to include JSR 226, you must also include JSR 172.

Working With Stubs

The Java Wireless Client software build system uses a top-level platform-specific makefile in midp/build, and OS-specific and compiler-specific makefiles in midp/build/common/makefiles.

The makefiles define all the variables (usually specifying directories) that are exported to the subsystem makefiles. They also define OS specific commands and subsystem targets.

This section shows you how to configure the Java Wireless Client software build system for your new platform. Because porting to a new platform begins with successfully building stubs (empty or generic platform-independent versions of functions), this section begins by showing you how to configure for a stubs build.

After you can build the stubs implementation for your platform, incrementally fill the stubs with working code and rebuild. Use the instructions at the end of this section to further modify the build system, if necessary, through each build cycle.

For more information, see the Porting Guide.

Configuring the Build System for Stubs

First, create a directory for your platform in midp/build.

Use the naming convention of operating system, CPU, and compiler, separated by underscores, for the directory. For example, if the OS is Symbian, the CPU is ARM, and the compiler is GCC, create the following directory:

midp/build/symbian_arm_gcc

Next, copy GNUmakefile and Options.gmk from linux_stubs_gcc into your new directory.

Modify definitions in your new GNUmakefile for your platform. TARGET_PLATFORM should stay as stubs. Modify the values in Options.gmk for your platform.

If you need platform-specific definitions, create stubs.gmk in your new
platform directory. Platform-specific definitions might mean extra include files, extra flags for your compiler, and so on. Use build/linux_qte_gcc/qte.gmk as a template for creating stubs.gmk.

Make sure to include stubs.gmk in your GNUmakefile.

Create compiler-jtwi.gmk, compiler.gmk, and os.gmk in midp/build/common/makefiles.

The file compiler-jtwi.gmk contains MIDP-specific directory and library definitions. See gcc-jtwi.gmk in midp/build/common/makefiles for comments and a list of definitions. Consider copying, renaming, and editing gcc-jtwi.gmk.

The file compiler.gmk contains generic compiler definitions. See gcc.gmk in the midp/build/common/makefiles for a list of required compiler definitions. Consider coping, renaming, and editing gcc.gmk.

The file os.gmk contains generic OS-specific definitions. See linux.gmk in the midp/build/common/makefiles for a list of required definitions. Consider coping, renaming, and editing linux.gmk.

Note - compiler and os must match the HOST_COMPILER and HOST_OS values in GNUmakefile.

You are now ready to launch the stubs build.

Updating the Build System for Filled-in Stub Functions

After you successfully build the stubs implementation, incrementally implement the empty platform-specific functions. After implementing a platform-specific function, rebuild stubs and, if required, modify the build system.

If you add a new native file as you implement a stub function, you must modify the corresponding subsystem's .cfg file. A .cfg file has definitions such as the source file path, extra include files, and a list of native files. Each subsystem has a stubs.cfg in its config directory. For example, the core subsystem has a stubs.cfg file in src/core/config.

Updating the Source Files and Build System after Porting

After you complete all of the stub functions, meaning you can build the entire system for your platform, consider renaming the stubs to match the name of your platform. It is not a functional change, but is a good way to indicate to yourself and any team members that the milestone of a full platform-specific build has been reached.

To rename stubs, change the TARGET_PLATFORM variable in the file GNUmakefile to the name of your platform. Then rename all directories named stubs to the name of your platform.