Building the Mobile Information Device Profile


This section describes the procedures for configuring the build environment. Follow these steps to use the MIDP build environment:

  1. Select the appropriate configuration options.

    The table in the next section describes the configuration options that are available at build time. Many of these options provide a mechanism for balancing memory consumption against functionality.

  2. Run the MIDP build environment to generate a MIDP.

    The MIDP build environment is based on a set of makefiles that compile the different Java and C files and generate a specific configuration of the MIDP for a target system. These makefiles assume GNU makefile syntax.

Configuring the MIDP Build Environment

The MIDP build environment has a mechanism for building different configurations of the MIDP that adhere to this specification and provide different levels of API functionality.

Configuration Options

This section describes the configuration options that a licensee can select to use the MIDP to build a specific configuration of the MIDP. The table below describes these configuration options. See Build Procedures for a description of how to use these configuration options with the gnumake command.

MIDP Build Environment Configuration Options
Option Type Default Description
ALT_BOOTDIR string Microsoft Windows 2000:
  C:/JDK1.3

Solaris:
  /usr/local/java/jdk1.3

The location of the top-level directory of a separate JDK used to build the MIDP.
KVM_DIR string $(TOPDIR)../kvm
The default is $(MIDP_DIR)/../kvm
The location of the top-level directory of a separate KVM used to build the MIDP. (Set in Platform.gmk.)
ROMIZING boolean true If true, then the class files in classes.zip are ROMized by converting them to an object file format for linking with the KVM image.
DEBUG boolean false If DEBUG is true, the object file is compiled with debugging symbols.
ENABLE_DEBUGGER boolean false If true, compile all Java classes with debugging information. This will allow Java source-level debugging with a Java debugger. If false, then no debugging information will be compiled into the Java classes.
INCLUDE_ALL_CLASSES boolean true If true, then the implementation will include support for all classes from the CLDC reference implementation. If false, then the implementation will include only the interfaces and classes defined in the CLDC specification.
INCLUDEDEBUGCODE boolean false If true, then include extra code to allow tracing of the VM internals. NOTE: This has the side effect of slowing down the VM and slightly increasing its size.
ENABLEPROFILING boolean false If true, and INCLUDEDEBUGCODE is also true, then a message is printed on exit from the midp giving VM statistics such as count of garbage collections, memory usage and so forth.
INCLUDE_I18N boolean true If false, the implementation will not include internationalization support. (This reduces the build size by approximately 35K on Windows platforms, and approximately 90K on Solaris platforms.)
INCLUDE_HTTPS boolean false If false, the implementation will not include HTTPS support. (This reduces the build size by approximately 87K on Windows platforms, and approximately 102K on Solaris platforms.)

Build Procedures

The following sections describe how to use and modify the MIDP build environment.

Building a MIDP Target

The table above describes a set of macro definitions that are contained in the MIDP build environment's makefiles. The values of these macro definitions can be changed to select different configuration options by passing command-line options to the gnumake command. The example below builds the MIDP with a configuration option.

To build an optimized version of the MIDP with ROMized class files:

  1. Change the shell's current directory to the directory containing the platform-dependent makefiles.
    % cd build/platform 
  2. Build the MIDP target.
    % gnumake clean all 

Build Commands

The following table describes the main build commands for the MIDP build environment.

This is the fastest optimized executable.
Command Description
gnumake all Builds the default build target based on the current set of configuration options, e.g., DEBUG=false, GCC=false, INCLUDE_ALL_CLASSES=true.
gnumake INCLUDEDEBUGCODE=true
              DEBUG=true
Builds a version of the MIDP in build/platform directory that contains debug capabilities. This includes the bin/midp_g executable with symbol tables.
gnumake ENABLE_DEBUGGER=true Compiles the Java class files with debug information to allow source-level debugging. Builds a version of the MIDP in build/platform directory. This includes the bin/midp executable and, for non-ROMized builds, a classes.zip file containing debugging information.
gnumake docs_html Uses javadoc to build HTML API reference files. These include the MIDP and CLDC class library.
gnumake clean Removes all the class files, object files, and other temporary build files from the MIDP build environment.
gnumake reallyclean Removes everything in the gnumake clean target in addition to removing all supplementary tools such as the preverifier, Java CodeCompact, etc.
gnumake insanelyclean Removes everything in the gnumake reallyclean target in addition to removing all crytographic object files.
WARNING: Do NOT use this target unless you have the SSL source files (only supplied under special agreement with Sun Microsystems). If you run gnumake insanelyclean and you do not have access to the cryptographic source, you will NOT be able to rebuild the MIDP executable.
gnumake example Builds all example files.
gnumake games
gnumake demos
gnumake manyballs
gnumake auction
gnumake pushpuzzle
gnumake stock
gnumake photoalbum
Builds a specific example package.

Adding Extra Files

The MIDP build environment was designed with two main goals: maximum flexibility with minimum complexity. One of the more flexible features of the MIDP build environment revolves around the addition of extra files not contained in the reference source distribution.

Adding Class Files

There are two basic types of classes in the MIDP source: platform-generic and platform-specific. Depending on the type of classes to be added to the build, different build variables must be updated in the file build/share/makefiles/Defs.gmk.

To add classes that are platform-specific, update the variable "PLATFORM_INCLUDE_CLASSES."

To add classes that are platform-generic, update the variable  "MIDP_INCLUDE_CLASSES."

For example:
 
  PLATFORM_INCLUDE_CLASSES += classes/com/MyCompany/productY/foo.java 
  MIDP_INCLUDE_CLASSES += classes/com/MyCompany/midp/bar.java  

Adding Object Files

Object files can also be added to the list of object files managed by the MIDP build environment. This is the normal way to add native method implementations to the MIDP build environment. Again, depending upon the type of object file (platform-specific or platform-generic) different makefile variables in the file makefiles/Defs.gmk need to be updated. For platform-specific object files, update the variable " PLATFORM_INCLUDE_SRC." For platform-generic object files, update the variable " MIDP_INCLUDE_SRC."

For example:
  
  PLATFORM_INCLUDE_SRC += productY_natives.c
  MIDP_INCLUDE_SRC += common_natives.c  

Advanced Build Targets

The following build targets are not used in general by each developer. They are special-purpose targets used in generating release documentation and bundles for external use.

Documentation Targets

The build targets for documentation targets are included into the top level makefile from build/share/makefiles/Docs.gmk.

  • docs_html

    Build the full set of Javadoc HTML pages combining the CLDC and MIDP interfaces into a single browsable structure. This is most useful for MIDlet developers.

  • docs_mid

    The MIDP-only target excludes the CLDC classes. This is useful when only the MIDP classes and interfaces are needed. Unfortunately, this build target creates Javadoc files that do not include CLDC linkage, such as the inheritance of HttpConnection to the generic connection interfaces.

  • docs_mif

    The MIF doclet target is used in production of the public specification. It generates both the individual class file documentation and the full package documentation. The generated files are typically copied into a directory with the front matter of the specification and then edited for consistency, e.g., page numbering, page layout, etc.

  • docs_all

    A complete set of Javadoc can be generated from the RI. This produces Javadoc that include all private fields and methods from the source in the RI bundle.

Release Bundles

Several variants of the MIDP reference implementation are expected for different audience needs. The following targets have been created to meet the needs of the expert group deploying the specification and the initial reference implementation.

  • midp-src

    The source bundle includes the reference implementation source code.

  • midp-docs

    The documentation bundle includes the combined CLDC and MIDP Javadoc files.

  • midp-dist

    This release bundle includes full source for the MIDP reference implementation and can be customized by Java licensees.


Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303, U.S.A. All rights reserved. This product is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Sun, Sun Microsystems, the Sun Logo, Java, and the Java Coffee Cup Logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Federal Acquisitions: Commercial Software -- Government Users Subject to Standard License Terms and Conditions. DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.