Managing Wireless Builds with Ant

Print-friendly Version

Download the example build.xml file.

The Java 2 Platform Micro Edition Wireless Toolkit (J2MEWTK) provides a complete set of tools to develop Java applications for CLDC/MIDP devices, including a simple development environment called KToolBar, which developers can use to build and package MIDlets. An alternative for managing builds is the Apache Ant tool, which is part of Apache's Jakarta project. This article shows you how to use Ant in place of KToolBar to develop MIDlets.

Why use Ant?
KToolBar is great for most projects. It lets you build, compile, debug, run, and package MIDlets very easily, but if you really want complete control over your builds, only a full-featured tool like Ant will do. Adding steps like obfuscation, multiple levels of debugging or optimization, custom packaging, or dealing with other third-party products requires customization - and customization is where Ant really shines. Ant's XML-based configuration files provide an open, standard way of defining builds which is much more flexible and less error-prone than makefiles. Using the same build tool for all your projects simplifies your life and keeps things easier to manage. Many developers (especially Java developers) are already using Ant.

A Simple Wireless Build
When you run Ant, by default it looks for a build file named build.xml. A useful build.xml might begin its life looking something like this:

<project name="MyProject" default="compile" basedir="..">
<property name="midp" value="/lang/j2mewtk"/>
<property name="midp_lib" value="${midp}/lib/midpapi.zip"/>

<target name="compile" depends="init">
<mkdir dir="build/classes"/>
<javac destdir="build/classes" srcdir="src"
bootclasspath="${midp_lib}" target="1.1"/>
</target>

<target name="init">
<tstamp/>
</target>
</project>

This file would work for a simple project, with /myproject/src containing the source files and /myproject/build containing the build.xml file. This example only compiles your source files though, and doesn't take care of some of the other steps that creating a MIDlet entails. We'll get there shortly...

The first three lines set up some properties that will be used throughout the build process:

• Line #1 gives our project a name, and sets the default target to be "compile." This setting just indicates that if we run "ant" with no parameters it will try to build the "compile" target first. We also specify the base directory for the project to be the parent (default) directory.
• Line #2 sets the "midp" property. Ant needs to know where the wireless toolkit is installed because it needs to find the MIDP classes, the preverifyer, the emulator, and other pieces of the wireless toolkit.
• Line #3 sets the "midp_lib" property. Ant needs the location of the MIDP classes for compilation.

The compile target simply specifies how to compile this MIDlet. It uses Ant's javac task to specify the source and destination directories for class files, to identify the bootclasspath (the path to the MIDP classes), and to set the target VM to be version 1.1. This target also creates a "classes" directory under the "build" directory for your compiled classes.

Notice that the compile target depends on the init target, so when Ant runs this build.xml it calls the init target first, then the compile target. The init target typically takes care of any needed housekeeping, so it should appear in the depends clause of all other targets. In this case it simply sets the timestamp formats, but we could also have it create directories or perform other preliminary tasks.

Preverification MIDlet classes must be preverified before they can be run - a step not needed in most other Java development. To preverify your classes after compilation, simply add a "preverify" target to your build file:

<target name="preverify" depends="compile">
<mkdir dir="build/preverified"/>
<exec executable="${midp}/bin/preverify">
<arg line="-classpath ${midp_lib}"/>
<arg line="-d build/preverified"/>
<arg line="build/classes"/>
</exec>
</target>

This target instructs the preverify command to verify all the classes in build/classes, and place the verified classes in build/preverified.

Obfuscation
MIDlet developers often use an obfuscator to reduce the sizes of MIDlet class files. Calling the obfuscator is typically as simple as adding another target to your build file. Obfuscation is done before preverification, so make sure your depends attributes are in the right order.

<target name="obfuscate" depends="compile">
<mkdir dir="build/jax"/>

<java fork="yes" classname="com.ibm.jax.Batch"
classpath="${jax};${midp_lib}">
<sysproperty key="HOME" value="build"/>
<sysproperty key="MIDP_HOME" value="${midp}"/>
<arg line="build/myprog.jax"/>
</java>

<mkdir dir="build/obfuscated"/>
<unjar src="/mobility/midp/articles/ant/build/jax/myprog_jax.zip"
dest="build/obfuscated"/>
</target>

This example uses Ant's java task to call the JAX obfuscator, which relies on several environment variables and the myprog.jax configuration file. For this example, you'll also need to set the jax property at the beginning of your build.xml file:

Packaging
Once your classes are compiled, obfuscated, and preverified you must package them in a jar file. Again, you simply create another target to create the jar file. Ant's jar task takes a few parameters and creates the jar file from your verified classes. You need to create a .jad file as well, which in this example is simply copied over from the bin directory.

<target name="dist" depends="preverify">
<mkdir dir="build/bin"/>
<jar basedir="build/preverified"
jarfile="build/bin/MyProj.jar"
manifest="bin/MANIFEST.MF">
<fileset dir="res"/>
</jar>
<copy file="bin/MyProj.jad"
tofile="build/bin/MyProj.jad"/>
</target>

One inconvenience of using Ant is that you must create the MANIFEST.MF and .jad files yourself. KToolBar performs those chores automatically.

Application Execution
Once your MIDlet is packaged you're able to run it or deploy it.

<target name="run">
<exec executable="${midp}/bin/emulator">
<arg line="-Xdescriptor:build/bin/MyProj.jad"/>
</exec>
</target>

This example uses Ant's exec task to call the emulator application with the appropriate .jad file. If all goes well, your MIDlet should run in the emulator.

Conclusion
This article looked at some of the common tasks needed to build a wireless application, and how you can use Ant to specify those tasks. Ant is extremely customizable. For more information on built-in tasks and more configuration options see the included documentation. For more build.xml examples see the references below.

References - and Acknowledgments
Special thanks to Jonathan Knudsen and the guys over at jxme.jxta.org for their help with this article. The following projects have some great examples of Ant build files in a J2ME context:

• Jonathan Knudsen's Peek and Pick application
• JXTA for J2ME (CLDC / MIDP ) Also check out the Jad.java file , a custom Ant extension that simplifies packaging by automatically inserting the correct jar file size.
• The Java BluePrints Smart Ticket demo application