J2ME CDC 1.0
Porting Guide

Building CVM and CDC/Foundation

Target Environments
System Requirements
Linux Build Information
VxWorks Build Information
Compiler Warnings
Build Options
Compiling Applications for CDC/Foundation

Target Environments

This release of CVM and CDC/Foundation supports two different target environments:

VxWorks^® real-time operating system on Intel^® Pentium hardware

Linux operating system, also operating on Pentium hardware.

System Requirements

Linux System Requirements

The Linux configuration can be built and executed on the same system. Its requirements are:

Red Hat Linux 6.2 or greater
x86-compatable hardware capable of running this platform. This information is available from the hardware support page of the Red Hat web site.
Java 2 SDK, Standard Edition, v1.3 or later
Configured for multicast (required for execution)
80 - 100 Mbytes of disk space to build CVM plus CDC or Foundation

VxWorks Build Requirements

The build environment for the VxWorks target is the Tornado^TM development system, running in the Solaris^TM Operating Environment. It requires:

Java 2 SDK, Standard Edition, v1.3 or later
Tornado 2.0 development system
Solaris 7 Operating Environment or later
SPARC hardware
128 MB of RAM (256 MB recommended)

VxWorks Target System Requirements

Pentium hardware
VxWorks 5.4 operating system
32 MB of RAM
Must be on the same network as the host system
For information about Tornado and VxWorks, see the Wind River Systems Web site. For information about Pentium hardware, see the Intel Web site.

Linux Build Information

Before You Build

The instructions in Linux Build Procedure assume that you have already downloaded and unzipped the CDC or Foundation distribution. The directories in the instructions are relative to the directory in which you unzipped the CDC or Foundation distribution.
The Red Hat Linux system includes GNU development tools to use in building the CDC/Foundation reference implementation. The C compiler should be version egcs-2.91.66 or later, and make version 3.78 or later.
To run CVM plus CDC/Foundation requires configuring the system for multicast. This can be done each time Linux boots, or can be added to the /etc/sysconfig/init file. The commands, which must be executed by the root user are:

/sbin/ifconfig eth0 allmulti
/sbin/ifconfig lo allmulti
/sbin/route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0
/sbin/route add -net 224.0.0.0 netmask 240.0.0.0 dev lo

Linux Build Procedure

To build CVM plus CDC, complete the following step(s):

On the host system, change directories to build/linux, and enter the following command:
make CVM_DEBUG=true
This produces the file build/linux/bin/cvm, which is an executable image, as well as build/linux/lib/cdc.jar, which is a JAR archive to be used for the CVM's boot classpath. The default boot classpath is ../lib/cdc.jar. The build also produces build/linux/testclasses.jar, a collection of simple tests.

Change directory into the bin directory using:
cd bin

Test for rudimentary operation of the system using:
./cvm -Djava.class.path=../testclasses.jar HelloWorld
This step should print Hello world. to your screen, indicating a successful build.

To build the Foundation implementation, modify the first step above to use the J2ME_CLASSLIB build option:
make CVM_DEBUG=true J2ME_CLASSLIB=foundation
This will produce build/linux/bin/cvm and build/linux/lib/foundation.jar, and set the default boot classpath accordingly.

Tornado/VxWorks Build Information

Before You Build

The instructions in Tornado/VxWorks Build Procedure assume that you have already downloaded and unzipped the CDC or Foundation distribution. The directories in the instructions are relative to the directory in which you unzipped the CDC or Foundation distribution.
The Tornado development system includes GNU development tools to use in building the reference implementation. If you already have GNU make installed on your system, it must be GNU version 3.74 or later to build the reference implementation. Or you can use the copy under your Tornado directory, in tornado2/host/$(WIND_HOST)/bin/make. Type make -version to verify that GNU make is in your command path.
If you do not have Tornado installed on your host system, you can download the Tornado/VxWorks evaluation bundle for the CDC at the following URL: www.wrs.com/j2me-cdc/.
Before building the reference implementation, complete the following steps:

On the host system, edit build/vxworks/config_vxworks.mk to provide the following:

Target IP address
Host IP address
Host name
Base directory for Tornado software (wind_base)

You may need to change additional values.

Create or edit the .rhosts file in your home directory, and add the target system name to the file.

Tornado/VxWorks Build Procedure

To build the reference implementation, complete the following steps:

On the host system, change directories to build/vxworks, and enter the following command:
make CVM_DEBUG=true

This may produce some compiler warnings about incompatabilities of argument lists for some system library functions. These may be ignored.
The products of this step are the files build/linux/bin/cvm.o, which is a relocatable file to be bound into the vxWorks kernel, and build/linux/lib/cdc.jar, which is a JAR archive to be used for the CVM's boot classpath. The default boot classpath is ../lib/cdc.jar. The build also produces build/linux/testclasses.jar, a collection of simple tests.
In build/vxworks, enter the following command:
gnumake download_image
Note: Steps 3 through 5 assume the presence of a floppy drive on your Solaris system. If your system does not have a floppy drive, you need to review the steps involved in the make targets "boot_disk" and "boot_rom" in the file build/vxworks/rules_vxworks.mk, and adapt them to your host system. Once you have created the boot disk, proceed with step 6.

Insert a diskette into the floppy drive of your host system. Format the diskette using fdformat. The diskette is automatically ejected when formatting is done. Reinsert the diskette.

In build/vxworks, enter the following command:
gnumake boot_disk
The diskette is automatically ejected after the command is carried out. Reinsert the diskette.

In build/vxworks, enter the following command:
gnumake boot_rom

Insert the diskette into a floppy drive on the target system, and boot the target system.

On the target console, enter the following command:
cd "top_dir/build/vxworks/bin"
where top_dir is the network directory in which you unzipped the CDC distribution.

On the target console, enter the following command:
runJava "-Djava.class.path=top_dir/build/vxworks/testclasses.zip HelloWorld"
where top_dir is the network directory in which you unzipped the CDC distribution. This step should print Hello world. to your screen, indicating a successful build.

To build the Foundation implementation, modify the first step above to use the J2ME_CLASSLIB build option:
make CVM_DEBUG=true J2ME_CLASSLIB=foundation
This will produce build/vxworks/bin/cvm.o and build/vxworks/lib/foundation.jar, and set the default boot classpath accordingly.
Note: For convenience, you may want to edit your home/.wind/startup file (where home is your home directory) on the host system to add the commands in steps 7 and 8.

Compiler Warnings

When compiling CVM, a certain number of warning messages are produced by the C compiler. This is especially noticeable when the target is VxWorks. All such compiler warnings produced by all supported tool sets have been investigated and found to be benign. There are similar "notes" produced by javac concerning deprecated methods that are also benign.

Build Options

[[[Add JwME_LIB??]]]

The following tables describe the CVM configuration options that developers may want to use with the make utility. Use of any other CVM configuration options is not supported. The default values are set in build/share/defs.mk.

Option Default Description

CPU PENTIUM The target CPU. This option is specific to VxWorks targets.

CVM_DEBUG false If true, builds the debug version of the CVM. If false, builds the non-debug CVM.

CVM_DEBUG_ASSERTS $(CVM_DEBUG) If true, then enable asserts.

CVM_DEBUG_CLASSINFO $(CVM_DEBUG) If true, builds the CVM with the ability to interpret class debugging information in the class files. Also causes preloaded classes to include debugging information if they were compiled with it. Note that the build must also have CVM_JAVAC_DEBUG set to true, for this option to have any effect.

CVM_DEBUG_DUMPSTACK $(CVM_DEBUG) If true, then include support for the CVMdumpStack and CVMdumpFrame functions. The CVMdumpStack function is useful for dumping a stack if CVM has crashed.

CVM_DEBUG_STACKTRACES true If true, then include code for doing Throwable.printStackTrace and Throwable.fillInStackTrace. If false, then the printStackTrace function prints only a "not supported" message. This function can be used in both debug and non-debug builds. To reduce the footprint of non-debug builds, set this option to false.

CVM_GCCHOICE generational Sets the garbage collector type to use. Valid values include: generational, marksweep, semispace.

CVM_JAVAC_DEBUG true If true, runs javac with the -g option to compile classes with debugging information such as line numbers. If false, runs javac with the -g:none option

CVM_JVMDI false If true, builds the CVM with JVMDI support. If false, builds the CVM without JVMDI support.

CVM_NO_LOSSY_OPCODES $(CVM_JVMDI) If true, field-related opcodes whose arguments would ordinarily be quickened into offsets instead have their arguments quickened into constant pool references, to ensure that the fieldblock for the field is available. This is required to allow the debugger to set field watchpoints. Note that this works either with or without classloading enabled, and affects both JavaCodeCompact and quicken.c.

CVM_OPTIMIZED !$(CVM_DEBUG) If true, turns on C compiler optimizations.

CVM_PRELOAD_LIB false If true, preloads the CDC class library.

CVM_SYMBOLS true If true, includes debugging and symbol information for C (the -g option), even if the build is optimized.

CVM_TERSEOUTPUT true If true, avoids printing messages that show each build step. If false, prints messages that show each build step.

J2ME_CLASSLIB cdc Controls the class library produced by the build. Choices are cdc and foundation.

Compiling Applications for CDC or Foundation

It is important the applications to be run on CDC or Foundation be compiled against the appropriate library. By default, the SDK1.3 compiler will compile against the SDK1.3 libraries. This would allow compilation of applications using library elements not part of CDC or Foundation, and would prevent compilation of applications using any of the CLDC components of CDC.
This problem can be avoided using the javac -bootclasspath compiler option. For example, to compile the source file MyApp.java against the CDC platform for the VxWorks build, this command could be used:
javac -bootclasspath top_dir/build/vxworks/lib/cdc.jar MyApp.java

Contents | Prev | Next

Option	Default	Description
`CPU`	`PENTIUM`	The target CPU. This option is specific to VxWorks targets.
`CVM_DEBUG`	`false`	If `true`, builds the debug version of the CVM. If `false`, builds the non-debug CVM.
`CVM_DEBUG_ASSERTS`	`$(CVM_DEBUG)`	If `true`, then enable asserts.
`CVM_DEBUG_CLASSINFO`	`$(CVM_DEBUG)`	If `true`, builds the CVM with the ability to interpret class debugging information in the class files. Also causes preloaded classes to include debugging information if they were compiled with it. Note that the build must also have `CVM_JAVAC_DEBUG` set to `true`, for this option to have any effect.
`CVM_DEBUG_DUMPSTACK`	`$(CVM_DEBUG)`	If `true`, then include support for the `CVMdumpStack` and `CVMdumpFrame` functions. The `CVMdumpStack` function is useful for dumping a stack if CVM has crashed.
`CVM_DEBUG_STACKTRACES`	`true`	If `true`, then include code for doing `Throwable.printStackTrace` and `Throwable.fillInStackTrace`. If `false`, then the `printStackTrace` function prints only a "not supported" message. This function can be used in both debug and non-debug builds. To reduce the footprint of non-debug builds, set this option to `false`.
`CVM_GCCHOICE`	`generational`	Sets the garbage collector type to use. Valid values include: `generational`, `marksweep`, `semispace`.
`CVM_JAVAC_DEBUG`	`true`	If `true`, runs `javac` with the `-g` option to compile classes with debugging information such as line numbers. If `false`, runs `javac` with the `-g:none` option
`CVM_JVMDI`	`false`	If `true`, builds the CVM with JVMDI support. If `false`, builds the CVM without JVMDI support.
`CVM_NO_LOSSY_OPCODES`	`$(CVM_JVMDI)`	If `true`, field-related opcodes whose arguments would ordinarily be quickened into offsets instead have their arguments quickened into constant pool references, to ensure that the fieldblock for the field is available. This is required to allow the debugger to set field watchpoints. Note that this works either with or without classloading enabled, and affects both `JavaCodeCompact` and `quicken.c.`
`CVM_OPTIMIZED`	`!$(CVM_DEBUG)`	If `true`, turns on C compiler optimizations.
`CVM_PRELOAD_LIB`	`false`	If `true`, preloads the CDC class library.
`CVM_SYMBOLS`	`true`	If `true`, includes debugging and symbol information for C (the -g option), even if the build is optimized.
`CVM_TERSEOUTPUT`	`true`	If `true`, avoids printing messages that show each build step. If `false`, prints messages that show each build step.
`J2ME_CLASSLIB`	`cdc`	Controls the class library produced by the build. Choices are `cdc` and `foundation`.