Build Recipe: Linux/x86 Host Environment

Once you have downloaded the source code for phoneME Advanced, you can use the build system included with it to build different executable versions of a CDC Java runtime environment. These different versions can include different peformance features, API options or target platforms.

The following sections show how to setup the CDC build system on a Linux/x86 host platform, and then build different versions of the CDC Java runtime environment that will also run on a Linux/x86 platform. We call this running the CDC Java runtime environment on a host platform. A later section describes how to build different versions of the CDC Java runtime environment that run on alternate devices like advanced phones.

This guide only covers the basic build procedures and build options. See the CDC Build System Guide for more information about build options, build system organization and tool setup issues. See CDC Build System: Target Devices for information on how to build executable versions of the CDC Java runtime environment for various embedded target devices.

Build System Setup

Install the Linux Build Tool Packages

Note: Currently, most of the active testing for CDC build system for phoneME Advanced technology has been based on Ubuntu 6.0.6.

The CDC build system included with the source code for the phoneME Advanced can run on many different Linux distributions. To run the CDC build system, you will need certain Linux developer tools like a C/C++ compiler as well as the Java developer tools included in the Java SE SDK.

A reasonable guideline is that a recent, common Linux distribution should include the tools needed by the CDC build system. However, some user-oriented Linux distributions like Ubuntu may not include the necessary tools by default. So this guide includes tables that provide guidelines for acquiring the necessary tools based on the Debian Package Management System used by Ubuntu and Debian.

Note that the source code and build system for this release have been tested with earlier versions of gcc as well, in particular 3.3.x and 3.4.x. In particular, gcc 4.x is more restrictive than earlier versions. So it may in some cases be necessary to use the -fpermissive flag or downgrade to an earlier compiler version.

Install the Java Build Tools

Download and install the Java SE SDK, version 1.4.2. The examples below are based on installing the Java developer tools in /usr/java/j2sdk.

Note that many Linux distributions include alternate implementations of these Java developer tools. We have only tested and run the CDC build system with the Java developer tools provided by Sun.

A Simple Example Build: CDC

Once you've set up the CDC build system by installing the necessary build tools in the default locations, then you can perform a simple build process to validate the build system. The build process is launched by a top-level GNUmakefile in the target build directory. The name of the target build directory is based on the combination of the operating system, CPU and product name. For example, the target build directory for Ubuntu is cdc/build/linux-x86-generic.

The simplest build target is CDC without any profile. This is a "headless" implementation that we'll use to run a basic HelloWorld application.

Build the Executable

The CDC build system is launched with a single make command.

% make

The build system will display a log of the build process. If the build is successful, it will display something like:

...
make[1]: Entering directory `/home/developer/phoneme-advanced/build/linux-x86-generic'
make[1]: Nothing to be done for `tools'.
make[1]: Leaving directory `/home/developer/phoneme-advanced/build/linux-x86-generic'

If the build fails at some point, your build tools are probably misconfigured or not compatible. The first step is to look at the definitions of

Test the Executable

When the build process completes successfully it generates an executable CDC Java runtime environment. The component files of the CDC Java runtime environment are located in the target build directory. The runtime files are in the bin and lib directories with some additional demo programs in testclasses.zip.

Here is the command-line for running a simple test application.

% bin/cvm -cp testclasses.zip HelloWorld

More Build Options

The CDC build system includes many build options and targets:

• API choices. The Java ME platform has a configurable API architecture which allows designers to select standardized APIs that are appropriate for a given target device. The CDC white paper describes these API choices in more detail. For now, it's important to understand that these choices are made available through the build system as build options. For example, the choice between which Java ME profile to use is controlled by the J2ME_CLASSLIB build option.

• Testing features. Some build options are intended only for development and testing purposes. These include CVM_TRACE for tracing VM events and CVM_JVMDI for enabling Java debugging.

• Performance features. And finally, some build options are intended for performance. For example, CVM_PRELOAD_LIB uses JavaCodeCompact to preload the Java class library so that it can execute out of ROM. And CVM_JIT builds an executable with a JIT.

• Convenience features. By default, the generated files are built in the target build directory. CVM_BUILD_SUBDIR=true and CVM_BUILD_SUBDIR_NAME=name tell the build system to deposit the generated files in another directory.

The CDC Build System Guide provides tables that describe each build option.

Building Foundation Profile

Foundation Profile (FP) is a more complete API specification for headless devices. The steps described above can be easily modified to build an executable for FP. All you have to do is add J2ME_CLASSLIB=foundation build option to the build options in the GNUmakefile.

Here is the command-line for running a test application.

% bin/cvm -cp testclasses.zip Test

Note: The CDC build system caches some generated build files. So after changing build flags, it's important to perform a "make clean" operation.

Building Personal Basis Profile for Linux/x86

The CDC build system has many build options for building versions of the CDC Java runtime environment with additional API capabilities. For example, Personal Basis Profile (PBP) is an API specification for providing GUI capabilities. While PBP is not itself a GUI framework, it provides an infrastructure for implementing lightweight GUI widget toolkits like Swing and support for the xlet application model.

This build example will show how to build the CDC Java runtime environment with a PBP implementation based on the Qt GUI framework.

Setup the Build System

The build system requirements for PBP are the same as the base requirements described earlier with the addition of the Qt3 development libraries.

Note: The version of Qt described above and available through the Ubuntu package management system is for desktop application development. Later, in the section on Building MIDP for Qt Embedded we'll use Qt Embedded which is built and used in a different way. PBP can be built using both Qt and Qt Embedded while currently, MIDP can only be built using Qt Embedded.

Build the Executable

Building PBP requires a few additional build options. You can put these make variables on the make command-line or add them to the GNUmakefile.

Test the Executable

Here is the command-line for running a PBP test application.

% bin/cvm -cp democlasses.jar basis.DemoFrame

Building MIDP for Qt Embedded

phoneME Advanced includes the first release of MIDP on CDC technology and a lot of work has been done to make the build systems and implementations compatible and sharable.

Setup the Build System

1. Checkout the pcsl, midp and jpeg components from the project source code repository.

   % cd phoneme-advanced
   % svn checkout https://phoneme.dev.java.net/svn/phoneme/components/pcsl/trunk pcsl
   % svn checkout https://phoneme.dev.java.net/svn/phoneme/components/midp/trunk midp
   % svn checkout https://phoneme.dev.java.net/svn/phoneme/components/jpeg/trunk jpeg
   

2. Install the Debian package for the gawk tool.

   Debian Package Version gawk 1.3.1

3. Build and install the Qt Embedded Library. See the Qt Build Notes in the phoneME Advanced Twiki.

Build the Executable

Use the following build options:

For example, here's a working build script with most of the build options defined explicitly. Note the different values for QT_TARGET_DIR and QTEMBEDDED.

#!/bin/sh

make \
  CVM_HOST_TOOLS_PREFIX=/usr/bin/ \
  CVM_TARGET_TOOLS_PREFIX=/usr/bin/ \
  JDK_HOME=/usr/java/j2sdk1.4.2_15 \
  CVM_JIT=true \
  CVM_PRELOAD_LIB=true \
  CVM_BUILD_SUBDIR_NAME=cdc-midp \
  J2ME_CLASSLIB=basis \
      QT_TARGET_DIR=/home/developer/qt-embedded/target \
      QTEMBEDDED=true \
      USE_QT_FB=false \
  USE_JPEG=true \
  USE_MIDP=true

Test the Executable

Note: This test procedure is based on using the qvfb virtual framebuffer. The qt3-dev-tools-embedded package contains a prebuilt binary executable version of this developer tool.

Running a test midlet is a two-stage process:

1. Launch the qvfb virtual framebuffer.

   % qvfb -width 640 -height 442 -depth 16 -qwsdisplay :0
   

2. Run the test midlet. Here's an example test script based on a HelloWorld midlet:

   #!/bin/sh
   
   export LD_LIBRARY_PATH=$HOME/qt-embedded/target/lib
   CDC_RUNTIME=$HOME/phoneme/cdc/build/linux-x86-generic/cdc-midp
   CDC_HELLO=$HOME/midlets/hello
   
   $CDC_RUNTIME/bin/cvm \
     -Dmicroedition.profiles=MIDP-2.1 \
     -Dsun.midp.library.name=midp \
     -Dsun.midp.home.path=$CDC_RUNTIME/midp/midp_linux_fb_gcc \
     -Dcom.sun.midp.mainClass.name=com.sun.midp.main.CdcMIDletSuiteLoader \
     sun.misc.MIDPLauncher \
       -midppath $CDC_RUNTIME/midp/midp_linux_fb_gcc/classes \
       -suitepath $CDC_HELLO/HelloWorld.jar -1 HelloWorld
   

Building an Optional Package

phoneME Advanced includes support for several optional packages. The effort to integrate these optional packages into the project source code repository so that they can be shared and built in the phoneME Feature and phoneME Advanced projects is under way. The example optional package here (jsr172) is really a placeholder to demonstrate build system functionality.

Setup the Build System

Checkout the abstractions component and any optional package component from the project source code repository.

% cd phoneme-advanced
% svn checkout https://phoneme.dev.java.net/svn/phoneme/components/abstractions/trunk abstractions
% svn checkout https://phoneme.dev.java.net/svn/phoneme/components/jsr172/trunk jsr172

Build the Executable

Use the following build options:

Test the Executable

Currently, optional package support is only available to demonstrate a level of completeness for the framework. It can be built, but not tested at runtime.