This section describes the procedures for configuring
the build environment. Follow these steps to use the
MIDP build environment:
- 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.
- 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:
- Change the shell's current directory to the directory containing the platform-dependent makefiles.
% cd build/platform
- Build the MIDP target.
% gnumake clean all
Build Commands
The following table describes the main build commands for the MIDP build environment.
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. | This
is the fastest optimized executable.
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.
|