Chapter   12

Building Your Port

The MIDP build environment is a set of makefiles, the Java™ platform tools, and the free tools from the CygWin project such as gcc and make. For more information on CygWin tools, see:

http://sources.redhat.com/cygwin

The tools and makefiles work together to create a specific target. A target is a name in a makefile that is associated with a file or set of related files on which a set of commands will be run. The commands will typically act on the target’s files to create, update, or delete them.

The build environment provides configuration options to enable you to customize the target. For example, configuration options control whether to include debugging symbols. These configuration options are macros in the makefiles.

Gnumake accepts targets and configuration options on the command line using the general syntax:

make [target ...] [config_option=value ...] 

The make command has more options, however. See your make documentation for more information. Instead of being a make tutorial, this section shows you how to use the tool in the context of the MIDP build environment.

This chapter contains advice to help you build different versions of the midp executable command. It contains the sections:

The Build Process
Adding Files to the Build
Removing Unused Code

12.1 The Build Process

This section covers the makefiles that the make command uses, how to run a build, and how the full build works. It contains the sections:

Makefiles
Build Instructions
Example Commands
Build Steps for the Target all

12.1.1 Makefiles

The Release Contents contains a list of all files in the build. The table in this section shows only the makefiles, along with a brief description of their purposes, in roughly the order that they are used in the build. In the table, midpInstallDir is the directory that holds your MIDP installation. In addition, when a file is in a shared directory, the table shows the directory with Windows-style separators (\).

GNUmakefile 

Platform.gmk 

Defs.gmk 

midpInstallDir\build\share\makefiles\ 

Defs.gmk 

midpInstallDir\build\share\makefiles\kvm\ 

Defs-pre.gmk 

Defs-post.gmk 

MIDP.gmk 

midpInstallDir\build\share\makefiles\ 

CancelImplicits.gmk 

midpInstallDir\build\share\makefiles\ 

Tools.gmk 

midpInstallDir\build\share\makefiles\ 

VM.gmk 

midpInstallDir\build\share\makefiles\kvm\ 

Example.gmk 

midpInstallDir\build\share\makefiles\ 

Docs.gmk 

Release.gmk 

midpInstallDir\build\share\makefiles\ 

Testbeans.gmk 

midpInstallDir\build\share\makefiles\ 

For more information on the targets in these makefiles, see Appendix A, "Build Targets.” For more information on the definitions, see Appendix B, "Configuration Options.”

12.1.2 Build Instructions

To build the MIDP executable or documentation bundle:

If the target that you use creates a MIDP executable, it will be placed in the following directory:

midpInstallDir\build\win32\kvm\bin on a Microsoft Windows 2000 platform
midpInstallDir/build/linux/kvm/bin on a Linux platform
midpInstallDir/build/solaris/bin in the Solaris™ Operating Environment.

12.1.3 Example Commands

The following list describes common functionality requirements and the combinations of targets and configuration-options that provide them.

Getting better status text in the command window as the VM runs — The following command builds a MIDP executable that writes more text to the command window, such as stack traces when a method throws an exception:

   c:\midp2.0fcs\build\win32\kvm> make INCLUDEDEBUGCODE=true 

The command uses the default build target, all and creates the MIDP executable midp.

Debugging capabilities for native code — The following command builds a MIDP executable with debugging capabilities. It enables you to build an executable that you can attach to with the C debugger that corresponds to your compiler (for example, gdb if you compiled with gcc).

   c:\midp2.0fcs\build\win32\kvm> make DEBUG=true 

The command uses the default build target, all and creates the MIDP executable midp_g.

Debugging capabilities for Java class files — The following command compiles the Java class files with information that enables source-code debugging. It enables you to build an executable that you can attach through the KVM debug proxy.

   c:\midp2.0fcs\build\win32\kvm> make ENABLE_DEBUGGER=true 

The command uses the default build target, all and creates the MIDP executable midp.

Creating a MIDP Executable but no examples — The following command provides a faster build time because it creates the MIDP executable but does not build the examples:

   c:\midp2.0fcs\build\win32\kvm> make midp 

The command creates the MIDP executable midp.

Checking that your Java programming language code (Java code) compiles — The following command creates new, preverified Java class files, and recreates the classes.zip file:

   c:\midp2.0fcs\build\win32\kvm> make classes.zip 

The command does not create the MIDP executable.

12.1.4 Build Steps for the Target all

When you build the MIDP Reference Implementation with the target all, GNUmake performs the following steps:

Builds the preverifier
Creates the ROMizer
Compiles and preverifies Java code
Creates the classes.zip file
Reads classes.zip and generates ROMjavaplatform.c
Builds the extractOffsets tool
Uses the extractOffsets tool to generate header files with offsets into the classes of the Java programming language
Compiles CLDC and MIDP C files
Links the CLDC and MIDP C file
Creates the MEKeyTool and JadTool utilities
Creates the MidpInstallDir/build/appdb directory
Compiles, preverifies, and packages the examples (except the HelloMIDlet, which is left for the reader of Creating MIDlet Suites to do).

12.2 Adding Files to the Build

The MIDP build environment allows you to add new class files and object files to the build that are not part of the source distribution. To add the files, you must update the contents of the Defs-pre.gmk file. (See TABLE 7 for more information on this file.)

This section shows you how to update the file in the topics:

Adding Java Programming Language Files
Adding C Files

12.2.1 Adding Java Programming Language Files

You can add two types of classes written in the Java programming language to the build: platform-specific and platform-generic.

If you add platform-specific classes, they must be in PLATFORM_CLASS_DIR, which has the default value midpInstallDir/src/platform/classes. There is no required location for platform-generic classes.

The two types of classes are held in different variables in the Defs-pre.gmk file:

PLATFORM_INCLUDE_CLASSES — Holds the file names of platform-specific classes. The filenames that are the value of this variable have the form

   $(PLATFORM_CLASS_DIR)/packageName/className.java 

Note that these file names use a slash (“/”) delimiter, even on Windows 2000.

MIDP_INCLUDE_CLASSES — Holds the file names of platform-generic classes.

To add a file to one of these variables, add a line that has the following syntax to the Defs-pre.gmk file:

VARIABLE_NAME += fileName 

For example, to add the platform-specific class com.MyCompany.productY.Foo, you would update the PLATFORM_INCLUDE_CLASSES variable like this:

PLATFORM_INCLUDE_CLASSES += classes/com/MyCompany/productY/foo.java  

Similarly, to add the platform-generic class com.MyCompany.midp.bar, you would update the MIDP_INCLUDE_CLASSES variable like this:

MIDP_INCLUDE_CLASSES += classes/com/MyCompany/midp/bar.java 

The classes will be included in the build the next time you use the default target, all.

12.2.2 Adding C Files

You can add two types of C language files to the build: platform-specific and platform-generic. Different variables in Defs-pre.gmk hold these two kinds of files:

PLATFORM_INCLUDE_SRC — Holds the names of platform-specific C files
MIDP_INCLUDE_SRC — Holds the names of platform-generic C files

To add a file to one of these variables, add a line that has the following syntax to the Defs-pre.gmk file:

VARIABLE_NAME += fileName 

For example, to add the platform-specific file, productY_natives.c, you would update the PLATFORM_INCLUDE_SRC variable like this:

PLATFORM_INCLUDE_SRC += productY_natives.c 

Similarly, to add the platform-generic file, common_natives.c, you would update the MIDP_INCLUDE_SRC variable like this:

MIDP_INCLUDE_SRC += common_natives.c 

This is the normal way to add native method implementations to MIDP. The files will be included in the build the next time you use the default target, all.

12.3 Removing Unused Code

Removing unused code can improve the footprint of your port. This section covers two areas where you might find code to remove: configuration code and code made obsolete by your customization.

The MIDP Reference Implementation uses a configuration mechanism to select among alternate behaviors at runtime. In commercial ports of the RI, many of these design choices will have been made. (For example, whether the device has a color or grey scale screen.) You can eliminate the branches created by the configuration options that your device does not use. To locate these branches, look for calls to the Configuration.getProperty method. The list of classes that include optional behavior based on calls to access configuration parameters is:

com.sun.midp.Main
com.sun.midp.io.j2me.http.Protocol
com.sun.midp.io.j2me.https.Protocol
com.sun.midp.io.j2me.socket.Protocol
com.sun.midp.io.j2me.comm.Protocol
com.sun.midp.lcdui.InputMethodHandler
com.sun.midp.lcdui.Resource
com.sun.midp.midlet.Scheduler
com.sun.midp.midletsuite.Installer
javax.microedition.lcdui.Display

In addition, if you have customized the MIDP Reference Implementation (for example, by re-implementing one or more components in native code), there could be Java programming language or C code that is no longer used. Some examples have already appeared in the text, such as in Section 6.3 "Using Native Widgets for MIDP Screens" . You can use the examples in this guide as a starting point for a more thorough search.

Porting MIDP MIDP Reference Implementation, Version 2.0 FCS

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.