C H A P T E R 2 - Quick Start: Building on Windows for Windows

C H A P T E R 2

Quick Start: Building on Windows for Windows

This chapter describes building on Windows for Windows. It covers building and running your very own Java Wireless Client software stack. The purpose of this chapter is to whisk you through the build process for the entire Java Wireless Client software stack. Later chapters describe all the options for each part of the build.

This chapter presents example scripts that help you set up your environment and run the different parts of the build. The scripts are available in docs/build-scripts/win32-x86. Once you have everything set up, run the scripts to perform the build. Work along as you read through the chapter to understand how it all fits together.

Setting Up on Windows

Consult the Release Notes for the very latest information on tool versions.

The core of the Java Wireless Client software build on Windows is Microsoft's compiler, cl.exe. Use Microsoft Visual C++ 6.0 Professional Edition. Although other development packages from Microsoft include the compiler, they are incompatible in various ways and cannot be used without modifying the build system or source code.

To use the compiler, you need to add it to your PATH environment variable and update the INCLUDE and LIB variables to appropriate values. Microsoft provides a batch file to set PATH, INCLUDE, and LIB to appropriate values. This batch file is vcvars32.bat.

GNU Make and other UNIX system-style tools are available for Windows in a package called Cyg4Me. Get it here:

ftp://ftp.sunfreeware.com/pub/freeware/contributions/cygwin/cyg4me1_1_full.zip

Cyg4Me is a specialized version of a more widely known package, Cygwin. Use Cyg4Me rather than Cygwin.

Setting the PATH

You will need to set your path so that all of the tools are available. Here is an example batch file.

@echo off

REM Path to vcvars

set VCVARS=d:\PROGRA~1\MICROS~2\VC\vcvarsall.bat

REM JDK with backward slashes.

set JDK_DIR_win32=d:\j2sdk1.4.2_13

REM JDK with forward slashes (used in later scripts).

set JDK_DIR=d:/j2sdk1.4.2_13

REM Cyg4Me

set CYG4ME=d:\Applications\cyg4me

REM *********************************************

REM Set up PATH, INCLUDE, and LIB for C++ compiler.

call %VCVARS%

REM Add JDK.

set PATH=%JDK_DIR_win32%\bin;%PATH%

REM Add Cyg4me as the first PATH element.

set PATH=%CYG4ME%\bin;%PATH%

This batch file is docs/build-scripts/win32-x86/setpath.bat. Edit it so the values for the following variables are correct for your build system:

VCVARS points to the vcvars32.bat file provided with Microsoft Visual C++.

JDK_DIR_win32 is the JDK directory with backward slashes, Windows-style.

JDK_DIR is the JDK directory with forward slashes.

CYG4ME points to your installation of Cyg4Me.

After you set the values appropriately, run the batch file like this:

D:\jwc\docs\build-scripts\win32-x86>setpath

Setting environment for using Microsoft Visual C++ x86 tools.

D:\jwc\docs\build-scripts\win32-x86>

Run the scripts in the rest of this chapter from the same command line.

The Windows build is sensitive with respect to paths. Be careful when you define them, as certain forms of paths succeed in some parts of the build and fail in others. Follow the supplied scripts as closely as possible until you are comfortable with the build system.

In addition, the length of the paths you are using might also cause trouble in the build. Place the Java Wireless Client software source code in a location with a short path. The examples in this book are based on having the entire source code tree in d:\jwc.

Verifying Windows Setup

These examples show how to find out if you have set your PATH correctly and have the right tools available:

GNU Make

D:\jwc\docs\build-scripts\win32-x86>make --version

GNU Make version 3.78.1, by Richard Stallman and Roland McGrath.

Built for Windows32

Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99

    Free Software Foundation, Inc.

This is free software; see the source for copying conditions.

There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR

A PARTICULAR PURPOSE.

Report bugs to <bug-make@gnu.org>.

C/C++ compiler

D:\jwc\docs\build-scripts\win32-x86>cl

Microsoft (R) 32-bit C/C++ Optimizing Compiler Version

    14.00.50727.42 for 80x86

Copyright (C) Microsoft Corporation.  All rights reserved.

usage: cl [ option... ] filename... [ /link linkoption... ]

JDK software. Verify that java and javac are both from the same location using which. Don't be confused by the cygdrive designation, just make sure that which reports the same directory for java and javac.

D:\jwc\docs\build-scripts\win32-x86>java -version

java version "1.4.2_13"

Java(TM) 2 Runtime Environment, Standard Edition

    (build 1.4.2_13-b06)

Java HotSpot(TM) Client VM (build 1.4.2_13-b06, mixed mode)

D:\jwc\docs\build-scripts\win32-x86>javac

Usage: javac <options> <source files>

where possible options include:

...

D:\jwc\docs\build-scripts\win32-x86>which java

/cygdrive/d/j2sdk1.4.2_13/bin/java

D:\jwc\docs\build-scripts\win32-x86>which javac

/cygdrive/d/j2sdk1.4.2_13/bin/javac

Setting Up For the Build

The remainder of the build scripts presented in this chapter operate using Cyg4Me's shell, not the Windows command line. However, you will execute the scripts from the Windows command line, using sh to invoke the Cyg4Me shell. You'll see examples as you read the rest of the chapter.

Each of the build scripts in the rest of this chapter operate by setting up, doing some work, and cleaning up.

The setting up script is setup.sh and the cleaning up script is teardown.sh.

setup.sh looks like this:

export Acme=d:/jwc

export Scripts=`pwd`

export Output=$Acme/output

export Log=$Acme/log.txt

rm -f $Log

This script is available as docs/build-scripts/win32-x86/setup.sh.

The Acme variable is the top level of the Java Wireless Client software. Adjust the value to point to the top level of your own installation. Don't run this script yet. It is used by the build scripts in the rest of this chapter.

teardown.sh looks like this:

cat $Log

cd $Scripts

You do not need to modify this script.

Building the JavaCall API

Three variables must be defined to build the JavaCall API.

Two of these variables point to the JavaCall API source code, which is split into a base (open source) component and a product (commercial) component. Use JAVACALL_DIR to point to the base JavaCall API directory, usually javacall. Next, point JAVACALL_PROJECT_DIR to the javacall-com directory.

The third variable, JAVACALL_OUTPUT_DIR, tells the build system where to put the output of the JavaCall API build.

You need to run the build from javacall-com/configuration/irbis/win32_x86.

Here is a simple script to build the JavaCall API, build-javacall.sh:

. setup.sh

cd $Acme/javacall-com/configuration/irbis/win32_x86

make \

  JAVACALL_DIR=$Acme/javacall \

  JAVACALL_PROJECT_DIR=$Acme/javacall-com \

  JAVACALL_OUTPUT_DIR=$Output/javacall \

$1

if [ $? -ne 0 ]; then

  echo "javacall_status=failed" >> $Log

else

  echo "javacall_status=OK" >> $Log

fi

. $Scripts/teardown.sh

You should be able to run this script unmodified. This script uses the setup.sh and teardown.sh scripts from the previous section.

Go ahead and give it a whirl. Remember, you are still using the Windows command line, but you're going to invoke the script using Cyg4Me's sh shell. Messages display as the build progresses, with a success message at the very end.

D:\jwc\docs\build-scripts\win32-x86>sh build-javacall.sh

javautil_jad_parser.c

javautil_string.c

javautil_unicode.c

...Generating Library: d:/jwc/output/javacall/lib/javacall.lib

...compiling resources ...

d:\Applications\cyg4me\bin\make.exe:

javacall_status=OK

D:\jwc\docs\build-scripts\win32-x86>

The output goes in $Acme/output/javacall. Take a look:

D:\jwc\docs\build-scripts\win32-x86>ls d:\jwc\output\javacall

ext_lib  inc  lib  obj

D:\jwc\docs\build-scripts\win32-x86>

Building PCSL

The next step is to build PCSL. You have to tell PCSL the target platform and where to put output files. Because you are building PCSL on top of the JavaCall API, which is built on top of Windows (i386) using Visual C++ or Visual Studio (vc), the PCSL_PLATFORM variable should be javacall_i386_vc.

JAVACALL_OUTPUT_DIR needs to be set so that the PCSL build can find the JavaCall API files that it needs. Usually, JAVACALL_OUTPUT_DIR will still be set from your JavaCall API build.

Tell PCSL where to put its output files with the PCSL_OUTPUT_DIR variable.

Here is a script, build-pcsl.sh, that performs the build:

. setup.sh

cd $Acme/pcsl

make \

  JAVACALL_OUTPUT_DIR=$Output/javacall \

  PCSL_PLATFORM=javacall_i386_vc \

  PCSL_OUTPUT_DIR=$Output/pcsl \

$1

if [ $? -ne 0 ]; then

  echo "build-pcsl=failed" >> $Log

else

  echo "build-pcsl=OK" >> $Log

fi

. $Scripts/teardown.sh

This script uses the same setup.sh and teardown.sh scripts as before. Again, you can use build-pcsl.sh without modifying it.

Run the script the same way you ran the JavaCall API build script:

D:\jwc\docs\build-scripts\win32-x86>sh build-pcsl.sh

building memory module...

d:\Applications\cyg4me\bin\make.exe[4]: Entering directory `d:/jwc/pcsl/memory/heap'

d:\Applications\cyg4me\bin\make.exe[4]: Leaving directory `d:/jwc/pcsl/memory/heap'

d:\Applications\cyg4me\bin\make.exe[3]: Leaving directory `d:/jwc/pcsl/memory'

d:\Applications\cyg4me\bin\make.exe[2]: Leaving directory `d:/jwc/pcsl/string/utf16'

d:\Applications\cyg4me\bin\make.exe[1]: Leaving directory `d:/jwc/pcsl/string'

build-pcsl=OK

D:\jwc\docs\build-scripts\win32-x86>

At the end is a message about the success of the PCSL build.

Browse through the output files in output/pcsl if you want to see the results of the build.

Building CLDC

CLDC is built on top of PCSL and the JavaCall API. Tell CLDC to use PCSL by setting ENABLE_PCSL to true, and specify where to find PCSL with PCSL_OUTPUT_DIR.

Tell the CLDC build system where to find the JavaCall API with JAVACALL_OUTPUT_DIR.

In addition, the CLDC build system expects you to define several environment variables.

JDK_DIR is the location of the Java Development Kit software.

JVMWorkSpace is the cldc directory.

The output of the CLDC build will be placed in JVMBuildSpace.

The following script, build-cldc.sh, runs the CLDC build.

. setup.sh

cd $Acme/cldc/build/javacall_i386_vc

make \

  JDK_DIR=$JDK_DIR \

  ENABLE_PCSL=true \

  PCSL_OUTPUT_DIR=$Output/pcsl \

  JAVACALL_OUTPUT_DIR=$Output/javacall \

  JVMWorkSpace=$Acme/cldc \

  JVMBuildSpace=$Output/cldc \

$1

if [ $? -ne 0 ]; then

  echo "cldc_status=failed" >> $Log

else

  echo "cldc_status=OK" >> $Log

fi

. $Scripts/teardown.sh

Run it with sh build-cldc.sh. After a few minutes and a success message at the end of the build, you can browse the output in output/cldc.

Building Java Wireless Client Software

The last step in creating a Java Wireless Client software stack is building MIDP and optional APIs. This chapter describes how to build MIDP only. Later chapters describe how to include optional APIs in this part of the build and describe the many variables you can use to change how Java Wireless Client software is built.

For now, build MIDP using the CLDC, PCSL, and the JavaCall API output you already generated.

You need JDK_DIR defined, just as it was for the CLDC build. In addition, you must tell the MIDP build where to find the JavaCall API, PCSL, and CLDC:

Define JAVACALL_PLATFORM as win32_i386_vc and use JAVACALL_OUTPUT_DIR to point to the output of the JavaCall API build.

Set PCSL_OUTPUT_DIR.

Set CLDC_DIST_DIR to the dist directory of the CLDC build you wish to use. In this case, it will be %Output%/cldc/javacall_i386_vc/dist.

The first thing that happens with the MIDP build is that tools are created for use later in the build. Use TOOLS_DIR to point to the tools directory.

Finally, set MIDP_OUTPUT_DIR to the location that contains the output of the build when it is complete.

Run the build from the midp/build/javacall directory. Here is a script, build-sjwc.sh, that sets the necessary variables and runs the MIDP build:

. setup.sh

cd $Acme/midp/build/javacall

make \

  JDK_DIR=$JDK_DIR \

  JAVACALL_PLATFORM=win32_i386_vc \

  JAVACALL_OUTPUT_DIR=$Output/javacall \

  PCSL_OUTPUT_DIR=$Output/pcsl \

  CLDC_DIST_DIR=$Output/cldc/javacall_i386_vc/dist \

  TOOLS_DIR=$Acme/tools \

  MIDP_OUTPUT_DIR=$Output/midp \

$1

if [ $? -ne 0 ]; then

  echo "sjwc_status=failed" >> $Log

else

  echo "sjwc_status=OK" >> $Log

fi

. $Scripts/teardown.sh

Run this script with sh build-sjwc.sh. Wait until you see the message sjwc_status=OK at the end of the build. Congratulations! You've just built a complete MIDP stack.

Running Java Wireless Client Software

Now what do you do with it?

To run the Java Wireless Client software stack in a simulated device, change directories to output\midp\bin\i386. Now run usertest.

A simulated device is displayed.

FIGURE 2-1 Simulated Device

You can install and test MIDlets on this simulated device. See the Tools Guide for complete details.