Documentation

Requirements

Important! The Java JDK's bin directory must be in your systems PATH environment variable.

For windows:

set PATH=%PATH%;%JAVA_HOME%\bin

For Unix:

export PATH=$PATH:$JAVA_HOME/bin

Reference

The <rapc> and <sigtool> tasks will first try to get the "jde.home" property from the project. If this property is not set, then the "jdehome" attribute must be explicitly set for these tasks.

<rapc>

Runs the rapc compiler. The rapc task runs the compiler in much the same way as the RIM JDE. The JDE project/workspace files are however not used for building cod files. The nested <jdp> element is used to specify all cod file properties.

The rapc task behaves similar to the javac task in that it will check the modified time of the source files and compare it to the modified time of the cod file. It will compile if one or more of the source files is newer than the existing cod file.

Parameters

Attributes Description Required
jdehome Sets the JDE home directory. This attribute is required when the jde.home property is not defined at the project level. Optional
jdkhome Sets an alternative JVM home directory. Use this to override the version of the JVM used to execute the rapc compiler. When this attribute is not defined, the systems default JVM is used. Optional
exepath Explicitly define the directory containing the preverify command used by the rapc compiler. When not defined, the systems default PATH is used. Optional
srcdir Directory containing source files. This attribute is required when the nested <src> property is not used. An error occurs if both the nested <src> property and the srcdir attribute is specified. Optional
destdir Output directory of .cod file. When not defined, the base directory of the Ant build file is used. Optional
output Name of output file, eg: [output].cod, [output].cso, etc. Required
import Path of .jar files to import. Path strings consist of relative or absolute path names delimited by a ';' (Windows) or ':' (Unix) character. The rapc task will always add the net_rim_api.jar file by default. This attribute is optional. Optional
importref Path of .jar files to import given as a reference to a path defined elsewhere. The rapc task will always add the net_rim_api.jar file by default. This attribute is optional. Optional
defines ':' or ';' delimited list of preprocessor tags. See the note below regarding preprocessor usage. Optional
quiet Tells the rapc command to be less chatty, default to false. Optional
verbose Turn on verbose output of the rapc compiler, default is false. Optional
nodebug Turn off generation of .debug files, default is false. Optional
nowarn Disable warning messages, default is false. Optional
warnerror Treat all warnings as errors, default is false. Optional
noconvert Don't convert images to png, default is false. Optional
nopreverify Do not call the preverify executable, default is false. Optional
generatesourcelist Generate list of source files in text file. Set this to true when java returns "CreateProcess error=87" on Windows. Optional, defaults to false. Optional
sourcelistfile Set the name of the source list file. Use this to override the name of the file created when generatesourcelist is set to true. The default file name is sources.txt. Optional

Nested elements

<define>

Zero or more preprocessor tag definitions nested as elements.

Attributes Description Required
tag Name of preprocessor tag eg: THE_DEFINED_TAG. Required
if Define tag only when the named property is set. Optional
unless Define tag only when the named property is NOT set. Optional

<src>

Path like structure of files to compile. The <src> element can contain <fileset>, <filelist>, or any other path like element. A path defined elsewhere can be referenced by setting the refid attribute of <src>. If the srcdir attribute was not defined, the <src> element must contain one or more resources to compile.

<import>

Path like structure of jar files to import. The rapc task will always add the net_rim_api.jar file by default. This parameter is optional.

<jdp>

Collection of cod file properties. Optionally, place the cod properties in a properties file and set the file attribute. The property names must match the attribute names in the table below.

Attributes Description Default
file Properties file containing the project attributes. Property names must match the names defined below.
type Type of cod file to create. Valid values are "library", "cldc", "midlet". When "midlet" is specified, the midletclass property is required. "cldc"
title Module title. The title appears below the icon and in the applications list on the device.
vendor Company name. The vendor string appears in the applications properties on the device.
version Module version number. Version number strings must contain only numbers and dots. 0.0
description Module description. The description string appears in the application properties on the device.
arguments Space delimited list of arguments passed to the main method.
midletclass Fully qualified class name of the class extending javax.microedition.midlet.MIDlet.
systemmodule Set to true for a system module. System modules run in the background and do not have an icon on the home screen. false
runonstartup Set to true if application should start when device starts. false
startuptier Startup priority relative to other applications. Valid values are 0-7, lower value = higher priority. 7
ribbonposition Position of icon in ribbon. Higher values move the icon closer to the top of the ribbon. 0
nameresourcebundle Name of resource bundle that contains the module title, eg: ca.slashdev.MyAppResources
nameresourceid The id of the resource that contains the module title, eg: 1234.
icon Ribbon icon. Path must be relative to destdir, eg: ../img/ribbon1.png Use a comma delimited list to set multiple icons.
focusicon Ribbon focus icon (>= JDE 4.7). Path must be relative to destdir, eg: ../img/focus1.png. Use a comma delimited list to set multiple focus icons.

<entry>

Nested element of <jdp>. Contains attributes for specifying an alternate entry point for CLDC applications. It contains a subset of attributes available in <jdp>. Optionally, place entry point properties in a properties file and set the file attribute. The property names must match the attribute names in the table below.

Attributes Description Default
file Properties file containing the project attributes. Property names must match the names defined below.
title For non-system modules, defines the title for the ribbon icon.
arguments Space delimited list arguments passed to the main method.
systemmodule Set to true for a system module. System modules run in the background and do not have an icon on the home screen. false
runonstartup Set to true if application should start when device starts. false
startuptier Startup priority relative to other applications. Valid values are 0-7, lower value = higher priority. 7
ribbonposition Position of icon in ribbon. Higher values move the icon closer to the top of the ribbon. 0
nameresourcebundle Name of resource bundle that contains the module title, eg: ca.slashdev.MyAppResources
nameresourceid The id of the resource that contains the module title, eg: 1234.
icon Ribbon icon. Path must be relative to destdir, eg: ../img/ribbon1.png Use a comma delimited list to set multiple icons.
focusicon Ribbon focus icon (>= JDE 4.7). Path must be relative to destdir, eg: ../img/focus1.png. Use a comma delimited list to set multiple focus icons.
if Include entry point when the named property is set.
unless Include entry point when the named property is NOT set.

<sigtool>

Sigtool task will launch the signature tool on a given cod file or set of cod files. If a single cod file is specified, then a file will be created along side the cod file to mark it as signed.

Parameters

Attributes Description Required
jdehome Set the JDE home directory. This attribute is required when the jde.home property is not defined at the project level and the sigtooljar attribute has not been set. Optional
sigtooljar Set the path to the signature tool jar file. When this attribute is set the jdehome attribute is optional. Optional
codfile Single cod file to sign. Optional
forceclose Close signature tool even if signature failed. Default is false. Optional
close Close after signature request if no errors have occurred. Default is true. Optional
request Request signature when application launches. Default is true. Optional
password Removes the interactive password prompt. This implicitly sets "close" and "request" to true. Optional

Nested elements

Sigtool task supports selecting cod files using nested resource collections such as <fileset> and <filelist>.

<alx>

Alx task creates a directory structure of cod files and an .alx file. The purpose of the task is to generate a directory that can be easily zipped for creating an installation package. Therefore cod files are always copied to the destination directory.

The task fully supports generating expressions that limit which files will be selected by the application loader (Loader.exe) based on OS version.

To target a specific version of the BlackBerry software set either or both both of the greaterthan and lessthan attributes in the <application> or <codset> tags.

Parameters

Attributes Description Required
destdir Destination director for .cod files and .alx file. If the directory does not exist, it will be created. Required
filename Name of .alx file to generate. Required

Nested elements

<application>

Nested elements of <alx>. The id attribute is required. The remaining attributes are for information purposes only in the application loader program (Loader.exe).

Attributes Description Required
id Unique id of the application, eg: com.mycompany.myapp. Required
file Optionally specify a properties file of application attributes, must match names defined below. NOTE: 'title' is recognized as an alias for 'name' so properties files created for <jdp> type can be used here. Optional
name Application name. Optional
description Application description. Optional
version Version number, eg: 1.0 Optional
vendor Vendor string, eg: My Company. Optional
copyright Copyright information. Optional
greaterthan Only install application on versions of the BlackBerry software greater than the given version. Optional
greaterthanequal Only install application on versions of the BlackBerry software greater than or equal to the given version. Optional
lessthan Only install application on versions of the BlackBerry software less than the given version. Optional
lessthanequal Only install application on versions of the BlackBerry software less than or equal to the given version. Optional

<codset>

One or more nested elements of <application> element.

Cod files must be listed using nested resource collections such as <fileset> and <filelist>.

Attributes Description Required
dir Directory for cod files in destination directory. Optional
greaterthan Only install cod files on versions of the BlackBerry software greater than the given version. Optional
greaterthanequal Only install cod files on versions of the BlackBerry software greater than or equal to the given version. Optional
lessthan Only install cod files on version of the BlackBerry software less than the given version. Optional
lessthanequal Only install cod files on version of the BlackBerry software less than or equal to the given version. Optional

<jadtool>

Simple task that takes an input .jad file and rewrites it with one or more new cod files. The .jad file is updated with accurate .cod file sizes and SHA1 checksums.

The cod files are copied to the directory where the .jad file is created. If the cod file contains siblings, the cod file is automatically extracted.

Parameters

Attributes Description Required
input Input .jad file. Required
output Set output .jad file name. Use name of input file by default. Optional
destdir Destination directory for cod files and new jad file. Required

Nested elements

Jadtool task supports selecting cod files using nested resource collections such as <fileset> and <filelist>. At least one cod file must be selected.

<override>

Nested elements of <jadtool>. Provides the ability to add and/or update fields in the destination .jad file.

Attributes Description Required
key Name of .jad property to add/change Required
value New value for .jad property Required

Preprocessor

Apparently since JDE v4.0, rapc compiler has had support for a simple set of preprocessor macros. To use the preprocessor you must:

Examples

Example 1

<!-- bare minimum usage -->
<rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}" jdehome="${jde.home}" />

Example 2

<!-- uses jde.home property from project, specifies app title, vendor, etc -->
<property name="jde.home" location="c:/jde4.1" />
...
<rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}">
        <jdp title="Kick Ass App" vendor="Slashdev" version="1.0" type="cldc" />
</rapc>

Example 3

<!-- use fileset to select source files, import dependency lib -->
<property name="jde.home" location="c:/jde4.1" />
...
<rapc output="ca_slashdev_MyKickAssApp">
       <jdp title="Kick Ass App" vendor="Slashdev" version="1.0" type="cldc" />
       <src>
          <fileset dir="${src.dir}">
         <includes name="**/*.java" />
         <includes name="**/*.rrc" />
      </fileset>
   </src>
   <import location="../libKickAss/ca_slashdev_libKickAss.jar" />
</rapc>

Example 4

<!-- use the preprocessor -->
<rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}" defines="TAG1;TAG2">
   <define tag="TAG3"/>
   <define tag="TAG4"/>
</rapc>

Example 5

<!-- sign single cod file -->
<sigtool jdehome="${jde.home}" codfile="build/ca_slashdev_MyKickAssApp.cod" />

Example 6

<!-- jde.home property from project, fileset selects multiple cod files -->
<property name="jde.home" location="c:/jde4.1" />
...
<sigtool password="1234">
    <fileset dir="build" includes="*.cod" />
</sigtool>

Example 7

<!-- simple example, create zip file -->
<alx destdir="release" filename="myapp.alx">
   <application id="ca.slashdev.myapp" name="My App">
      <codset>
         <fileset dir="build" includes="*.cod" />
      </codset>
   </application>
</alx>
<zip destfile="release.zip" basedir="release" />

Example 8

<!-- cod files for specific versions of OS -->
<alx destdir="release" filename="myapp.alx">
   <application id="ca.slashdev.myapp" name="My App">
      <codset>
         <fileset dir="build" includes="*.cod" />
      </codset>
      <!-- 4.1 up to but not including 4.2 -->
      <codset greaterthanequal="4.1" lessthan="4.2">
         <fileset dir="build41" includes="*.cod" />
      </codset>
      <!-- 4.2.0 only -->
      <codset greaterthanequal="4.2.0" lessthan="4.2.1">
         <fileset dir="build42" includes="*.cod" />
      </codset>
      <!-- 4.2.1 and above -->
      <codset greaterthanequal="4.2.1">
         <fileset dir="build421" includes="*.cod" />
      </codset>
   </application>
</alx>
<zip destfile="release.zip" basedir="release" />

Example 9

<!-- jadtool task is pretty simple -->
<jadtool input="ca_slashdev_myapp.jad" destdir="ota">
   <fileset dir="build" includes="*.cod" />
</jadtool>

Example 10

<!-- override the name of the application title in Options/Applicaions -->
<jadtool input="ca_slashdev_myapp.jad" destdir="ota">
   <fileset dir="build" includes="*.cod" />
   <override key="MIDlet-Name" value="My Title" />
</jadtool>