When working with Java Micro Edition, every step of the build process can become a tedious series of command line calls. Compiling source files, running the J2ME pre‑verifier, packaging classes and resources into a JAR, generating a JAD file, and finally deploying to a device or emulator are tasks that are easy to make mistakes on, especially when they must be repeated for multiple projects or for frequent builds during development. Apache Ant solves this problem by providing a declarative, XML‑based build system that can automate all of these steps with a single command. Ant is not a build‑in‑IDE feature; it is a standalone tool that reads a build description file (build.xml) and executes a series of tasks in the order you specify.
Because Ant is written in Java itself, it is cross‑platform and runs on any environment that can run a JVM. This makes it a natural fit for J2ME developers who may need to build on Windows, Linux, or macOS, or even in a CI/CD pipeline that runs on a server. The fact that Ant scripts are plain XML files also means they are version‑controlled, searchable, and editable with any text editor. Once you have a well‑structured build.xml, adding a new source file or a new resource does not require you to remember any additional commands; you simply place the file in the correct folder and run the appropriate target again.
One of Ant’s strengths is its extensibility. The standard distribution includes a rich set of built‑in tasks such as javac, jar, exec, copy, and delete. For J2ME projects, Ant can also invoke the J2ME pre‑verifier, launch the device emulator, or call a third‑party obfuscator. If you need a custom step, you can write a small Java class that implements the Task interface, package it into a JAR, and reference it in your build file. This flexibility means Ant can evolve with your build needs, whether you are compiling a single MIDlet or a suite of them.
From a maintenance standpoint, Ant’s build file keeps all build logic in one place. A developer who joins the project can glance at the build.xml and immediately see the directories used for source, resources, compiled classes, pre‑verified classes, and final deploy artifacts. The script can also enforce naming conventions or directory layouts through properties, reducing the chance of a broken build caused by a misplaced file. Because the build file is declarative, the actual steps are hidden behind the scenes, allowing developers to focus on writing Java code rather than wrestling with command syntax.
In short, Ant turns a collection of manual steps into a repeatable, auditable, and platform‑independent process. The benefits are especially pronounced in J2ME development, where the build chain includes steps that are rarely used by other Java platforms, such as the pre‑verification and JAD generation. By centralizing those steps in Ant, teams can reduce build errors, speed up development cycles, and keep their builds consistent across environments.
Getting Started: Installing and Configuring Ant
Before you can write a build.xml file, you need to have Ant on your machine. The Ant project releases a ZIP archive that contains all the necessary binaries and libraries. Download the latest stable version from the official website,
This message indicates that Ant has started correctly and is looking for the build file in the current directory. It also shows that the PATH variable is set properly. At this point you can create a trivial build.xml file to confirm that Ant can parse XML and execute a target. For example, create a file with the following content:
Save the file in the same directory and run ant again. You should see the line Hello, Ant! printed to the console, followed by Build succeeded.. This confirms that Ant is fully functional on your machine and ready for more complex builds.
While the default build.xml is fine for simple experiments, real J2ME projects usually have a more elaborate structure. Ant scripts can also be split into multiple files and included with the <import> or <include> tags, which is useful for sharing common settings across several MIDlets or libraries. However, for the purposes of this guide we will keep everything in a single file for clarity.
Building Your First MIDlet – HelloWorld
To illustrate Ant’s capabilities, let’s walk through building a minimal J2ME HelloWorld MIDlet. The Java source is straightforward: it displays a text box with the message “Hello MIDlet” and includes an exit command that closes the application. The source file lives under src/hello/Hello.java, mirroring the package declaration package hello;. Resources such as images or configuration files can be placed in the res directory; for this example the res folder is empty.
Before writing the build.xml, create the following directory layout at the root of your project:
Prompt
/src</p>
<p>/res</p>
<p>/bin
The /bin directory is reserved for the final JAD and JAR files produced by the build. The /src folder contains all Java source files, organized by package. The /res folder will hold any non‑Java assets you need to ship with the MIDlet. When Ant runs, it will generate additional temporary directories – build, deploy, obf – inside the project root. These are created automatically by the build script and are not required to exist beforehand.
Now create a build.xml file in the project root. The file starts with a <project> tag that declares the project name, default target, and base directory. Inside the project, we first define a set of properties. Properties are key‑value pairs that can be reused throughout the script. For example, we set ${program_name} to Hello and ${package_name} to hello. These properties help keep the script flexible; if you rename the MIDlet, you only need to change the property values instead of hunting for hard‑coded strings.
We also declare the location of the J2ME SDK (MIDP) and the obfuscator library. In this example, the MIDP SDK is located at e:/j2mewtk and the ProGuard jar is at e:/proguard1.5.1/lib/proguard.jar. Adjust these paths to match your environment. The script uses the ${midp_home} property to reference the SDK’s lib/midpapi.zip file, which contains the required API classes for compilation.
Next, we define properties that hold directory names. Ant can reference these properties as ${src}, ${res}, ${build}, ${obf}, and ${deploy}. These directories are used by the various targets that follow. For example, the clean target deletes the build, deploy, and obf directories to ensure a clean state before a new build.
The clean target is straightforward; it uses the delete task to remove directories. Ant’s delete task can delete files or directories recursively, which is useful for cleaning build artifacts. The init target depends on clean and then creates the necessary directories (build, deploy, obf) using the mkdir task. By keeping directory creation in a separate target, we can reuse it whenever a new build is started.
The compile target is where the Java source gets turned into class files. Ant’s javac task compiles the src directory and outputs the compiled classes into ${build}/classes. The bootclasspath attribute points to the MIDP API zip, ensuring that the compiler sees the correct Java ME classes. The target="1.1" attribute tells the compiler to target Java ME 1.1 bytecode.
After compiling, the preverify target runs the J2ME pre‑verifier. The pre‑verifier validates that the bytecode is legal for the target device, performs additional optimizations, and writes the results to ${build}/preverified. Ant’s exec task runs the pre‑verifier binary from the MIDP SDK, passing the necessary arguments: the classpath, output directory, and input directory. If the pre‑verifier finds errors, Ant reports them on the console and the build fails, preventing a corrupt JAR from being generated.
Once the classes are pre‑verified, the dist target packages them into a JAR file. The jar task sets the basedir to the preverified classes directory, and writes the resulting JAR to ${build}/bin/${program_name}.jar. It also copies the bin/MANIFEST.MF file, which contains the MIDlet‑suite information. Resource files (e.g., PNG images) can be included using a fileset that matches the package path. Finally, the target copies the JAD file to the same directory, ensuring that the JAD and JAR are co‑located for deployment.
At this point the build has produced an unobfuscated JAR and JAD that are ready for deployment. If obfuscation is desired, the obfuscate target runs ProGuard against the newly created JAR. ProGuard’s configuration keeps the MIDlet class and any public classes that extend MIDlet, preventing them from being renamed or removed. The obfuscated JAR is placed in ${obf}. Because the pre‑verification step already ran against the original classes, we must pre‑verify the obfuscated classes again. The preverifyobf target creates a new preverified directory, runs the pre‑verifier against the extracted classes from the obfuscated JAR, and stores the result in ${build}/preverifiedobf
After the second pre‑verification, the distobf target re‑packages the obfuscated, pre‑verified classes into a new JAR that replaces the original JAR in ${build}/bin. It also copies the JAD file. The original, unobfuscated JAR is preserved as ${build}/bin/${program_name}-orig.jar for reference or rollback. This step ensures that the final artifact contains only the obfuscated code, improving protection against reverse engineering and reducing the application size.
The deploy target simply copies the final JAD and JAR files from ${build}/bin to the ${deploy} directory. Depending on your workflow, you can modify this target to push the files directly to an OTA server or a shared folder. The run target launches the J2ME emulator using the exec task. It passes the descriptor flag pointing to the JAD file, which in turn loads the JAR and starts the MIDlet on the virtual device. This single target lets you test the application without leaving the Ant command line.
Finally, to make common sequences easier, we define composite targets such as all-obf that depends on the entire chain: init, compile, preverify, dist, obfuscate, preverifyobf, distobf. Running ant all-obf builds the entire project, including obfuscation, in one go. After the build, you can run ant deploy to copy the final files to the deployment folder, and ant run to launch the emulator. This approach reduces the number of commands you need to remember and guarantees that each step is executed in the correct order.
Running, Testing, and Deploying Your App with Ant
Once the build.xml is in place, the workflow for creating a new MIDlet or re‑building an existing one becomes a matter of executing a single Ant target. The default target in the example is clean, but most developers prefer to use all-obf or all-non-obf as the main entry point. A typical day might look like this: you modify a Java file, you run ant all-obf, you test the emulator with ant run, you iterate on the code, and once the MIDlet is ready you deploy it to a device or OTA server with ant deploy. Because Ant executes each task in the order they are declared, you never need to remember which step must happen before the next.
During development, the pre‑verification step is invaluable. The J2ME pre‑verifier checks for bytecode that will not run on the target device, such as illegal field accesses or unsupported instructions. If it finds an issue, Ant prints a clear error message that points to the offending class and line number. Fixing the error in the source and re‑running ant all-obf will regenerate the pre‑verified classes, so you get immediate feedback. This tight loop is a major advantage over manual command line testing.
Testing the MIDlet in an emulator is straightforward once the run target is defined. The target simply executes the emulator binary from the J2ME SDK and supplies the JAD descriptor. The emulator loads the JAR, starts the MIDlet, and displays the UI exactly as it would appear on a physical device. If you need to test on different device profiles (e.g., a 160×240 screen versus a 240×320 screen), you can pass additional arguments to the emulator via the exec task. These arguments can be made optional by adding a property that defaults to the most common configuration.
Deploying the final artifact is equally simple. The deploy target copies the JAD and JAR to the deploy directory. From there you can copy the files to a physical device via USB, upload them to an OTA server, or simply share them with a colleague. If you are working in a team, you can even publish the deploy directory to a shared network drive, allowing everyone to test the latest build without building it themselves.
Because Ant’s tasks are independent, you can also mix and match. For example, if you only need to re‑compile a single file, you can run ant compile and skip the pre‑verification step. Or if you want to test a new resource file, you can run ant dist to re‑package the JAR without re‑compiling. This granularity gives you fine‑grained control over the build pipeline without sacrificing automation.
When you scale up to a project with multiple MIDlets, the same build.xml can be reused with minimal changes. Simply set ${program_name} and ${package_name} to the new MIDlet’s names, add the new source files to src, and run ant all-obf again. The script will create new JARs and JADs for each MIDlet without requiring any additional configuration. This reuse saves time and reduces the chance of mistakes that come from writing separate scripts for each project.
Advanced Tips and Common Pitfalls
While the basic build.xml covers most scenarios, real-world projects often encounter edge cases that require additional care. Below are several practical suggestions to help you avoid common pitfalls and make the most of Ant in J2ME development.
Keep Properties Centralized. The power of Ant lies in its ability to use properties. When you add a new tool - such as a different obfuscator or a custom pre‑verification script - add its path to a single property instead of scattering literal paths throughout the build file. If the tool’s location changes, you modify one line and the entire script follows. In larger projects, consider extracting the property definitions into a separate build.properties file and loading it with <property file="build.properties"/>. This separation keeps the main build file clean.
Use Absolute Paths Cautiously. Ant’s src, build, and other directory properties are relative to the project’s base directory, which is set to by default. If you move the project folder, the relative paths remain valid. However, when you hard‑code absolute paths - especially for external tools like the J2ME SDK - you risk breaking the build on a different machine. To mitigate this, wrap such paths in properties and provide a default value that works on most setups. Then, allow the developer to override the property via the command line, e.g., ant -Dmidp_home=/opt/j2mewtk all-obf
Leverage the depends Attribute. Ant’s depends attribute ensures that a target runs only after another target has finished. This is useful for cleaning, initializing, and packaging steps. In our example, init depends on clean to guarantee that the build directories are fresh. Likewise, distobf depends on preverifyobf to ensure that the obfuscated classes are verified before packaging. Misusing dependencies can lead to silent failures, so double‑check that the dependency chain reflects the actual build order.
Debugging Build Failures. If Ant reports a build error, the console output typically includes the target name and the line number in the build.xml where the error occurred. Use this information to locate the problematic task. If a javac error appears, check that the source files are in the correct package and that the bootclasspath includes the right MIDP jar. For pre‑verification errors, ensure that the classpath is correct and that no illegal bytecode was introduced during compilation. Turning on Ant’s verbose mode (ant -v) prints detailed information about each task, which can be invaluable when diagnosing complex issues.
Testing on Multiple Devices. J2ME applications often need to run on devices with different screen sizes, memory limits, and feature sets. Ant’s exec task can pass device‑specific parameters to the emulator or the pre‑verifier. Create separate targets for each device profile and parameterize the differences using properties. This approach lets you automate tests across multiple configurations with a single command such as ant test-all, where test-all depends on a series of device‑specific test targets.
Incremental Builds. Ant can be configured to skip tasks when inputs have not changed, reducing build times. For example, the javac task supports the useAntFile attribute to generate a dependency file, or you can use the if attribute to conditionally execute a target only if a source file is newer than the output. While the default build.xml re‑builds everything on each run, adding incremental checks can save significant time in large projects.
Version Control the Build Script. Treat the build.xml as a first‑class citizen in your source repository. Any change to the build logic should be reviewed and tested before merging. A stable build script protects the entire team from unexpected failures caused by a rogue developer’s shortcut.
By following these best practices, you can maintain a clean, efficient, and reliable build process that scales with the size of your project and the number of MIDlets you manage.
No comments yet. Be the first to comment!