Sunday, September 20, 2009

Using ANT to build BlackBerry J2ME application - source code build

Source code build using rapc compiler

We have to use BlackBerry JDE rapc compiler to build the J2ME application for BlackBerry. But the problem is that JDE only generate the make file, which is awkward. I did some research and found a solution using ANT. I would like to share this experience with the BlackBerry Developer who wants to build the application easily.

Here is the sample of ant build script for midlet:

<target name="build" >

<apply executable="${rim.blackberry.home}/bin/rapc.exe" parallel="true">

<arg value="-quiet"/>

<arg value="import=${rim.blackberry.home}/lib/net_rim_api.jar" />

<arg value="codename=${cod.name}" />

<arg value="-midlet"/>

<arg value="jad=${cod.name}.jad"/>

<fileset file="${cod.name}.jad"/>

<fileset file="resources.jar" />

<fileset dir="${src.dir}" />

</apply>

</target>

The above script is equivalent to the following command:

rapc.exe -quiet import=net_rim_api.jar codename=MIDletDemo -midlet jad=MIDletDemo.jad resource.jar file1.java file2.java … filen.java


Note:

1. Here I use Ant apply task, http://ant.apache.org/manual/CoreTasks/apply.html

Apply task allow us to pass a fileset, and it will pass each file one by one to the rapc.exe. Please note that here we choose parallel="true" attribute, it means the command execute only once, which is just what we want rapc.exe do that for us.

2. jad file issue, we know that rapc will add several blackberry customized attributes into the jad file. If we don’t pass the jad file into rapc, the rapc will generate a fresh new jad file for you; if you provide the jad file each time, the rapc will keep the jad file and only update some RIM specific attributes in the jad file. So I will suggest it is better pass your jad file into the build process.

3. resource file issues. Rapc.exe is strange, when you pass the resource file (image, text file, etc) outside of the project folder, it will lost the path information for each resource file, every file will be copied in the root directory of the jar file, only exception is resource file is in the subfolder of the project. The solution for this is first archive all your resource file into a jar file, resources.jar for example, and then pass this resources.jar into rapc. This time it will work, all the path information for each file will be kept. Please remember that please remove the Thumb.db file under the your image folders. Because I found some time my build jar file is much bigger than the jar file generated by JDE, when I expand the jar file, I realize that the thumb.db file was included.

Here is the ant example for zip resource:

<target name="zip_resources">

<jar destfile="resources.jar">

<fileset dir="../res" >

<exclude name="**/Thumbs.db"/>

</fileset>

</jar>

</target>


Building CLDC RIMlet is similar with the midlet, you don’t need pass the “-midlet” argument to the rapc.exe, here is the example:

<target name="build" depends="clean">

<apply executable="${rim.blackberry.home}/bin/rapc.exe" parallel="true">

<arg value="-quiet"/>

<arg value="import=${rim.blackberry.home}/lib/net_rim_api.jar" />

<arg value="codename=${cod.name}" />

<fileset dir="." includes="*.java" />

<fileset dir="." includes="*.rapc" />

<fileset dir="./img" includes="*.png" />

</apply>

</target>


Note for RIMlet build:

1. You need to pass the rapc file( generated by JDE) to build the RIMlet, or you will find your app can not be launched when you load the cod file on the phone; but I also found that you can also pass jad file to the rapc.exe, it also work.

Further thinking

1. Passing jar file instead of java file, what if we first archive the source code into a jar file, then pass it to rapc.exe, will it work? If this works, then we don’t need the ant apply task, the ant task will become more easier.

2. Use rapc.jar instead of rapc.exe, I noticed that in the \bin folder of BlackBerry JDE home directory, there is a rapc.jar file, can we use it. I checked several different J2ME build open source code, I found bb-ant uses rapc.jar, and J2ME Polish also uses rapc.jar file. I will test it later, if it works, which means the ant build script can be run at unix platform as well!

3. Check bb-ant tools

4. Check ANTENNA tool

Useful References

1. Ant apply Task

http://ant.apache.org/manual/CoreTasks/apply.html

2. Article: BlackBerry Development: using Apache Ant

http://www.ddj.com/mobile/48800167

3. bb-ant open source project

http://bb-ant-tools.sourceforge.net/

4. ANTENA open source project

http://antenna.sourceforge.net/