Collection of ant tasks for building blackberry application

Collection of ant tasks for building blackberry applications. Home Documentation Support SourceForge Project Page Downloads Credits Documentation Requirements Reference <rapc><sigtool><alx><jadtool> Preprocessor Examples Requirements RIM JDE (tested with 4.1 and up) Java 1.5 or higher Apache Ant 1.7.x or higher 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 (&gt;= 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 (&gt;= 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 Sets the JDE home directory. This attribute is required when the jde.home property is not defined at the project level. 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 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 version 4.0, rapc compiler has had support for a simple set of preprocessor macros. To use the preprocessor you must: enable processing on a per file basis by placing //#preprocess in the very first line of each .java file use //#ifdef <tag>, //#ifndef <tag> to begin a block of text that will be conditionally compiled if the TAG is defined or undefined respectively use //#else after //#ifdef <tag> or //#ifndef <tag> close conditional blocks with //#endif Preprocessor defines can be specified as a colon or semi-colon delimited list as an attribute of the <rapc> tag OR zero or more nested elements. Examples Example 1 <!-- bare minimum usage --> <rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}" jdehome="${jde.home}"></rapc> Example 2 <!-- uses jde.home property from project, specifies app title, vendor, etc --> <property name="jde.home" location="c:/jde4.1"></property> ... <rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}"><jdp title="Kick Ass App" vendor="Slashdev" version="1.0" type="cldc"></jdp></rapc> Example 3 <!-- use fileset to select source files, import dependency lib --> <property name="jde.home" location="c:/jde4.1"></property> ... <rapc output="ca_slashdev_MyKickAssApp"><jdp title="Kick Ass App" vendor="Slashdev" version="1.0" type="cldc"></jdp><src><fileset dir="${src.dir}"><includes name="**/*.java"></includes><includes name="**/*.rrc"></includes></fileset></src><import location="../libKickAss/ca_slashdev_libKickAss.jar"></import></rapc> Example 4 <!-- use the preprocessor --> <rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}" defines="TAG1;TAG2"><define tag="TAG3"></define><define tag="TAG4"></define></rapc> Example 5 <!-- sign single cod file --> <sigtool jdehome="${jde.home}" codfile="build/ca_slashdev_MyKickAssApp.cod"></sigtool> Example 6 <!-- jde.home property from project, fileset selects multiple cod files --> <property name="jde.home" location="c:/jde4.1"></property> ... <sigtool password="1234"><fileset dir="build" includes="*.cod"></fileset></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"></fileset></codset></application></alx><zip destfile="release.zip" basedir="release"></zip> 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"></fileset></codset><!-- 4.1 up to but not including 4.2 --><codset greaterthanequal="4.1" lessthan="4.2"><fileset dir="build41" includes="*.cod"></fileset></codset><!-- 4.2.0 only --><codset greaterthanequal="4.2.0" lessthan="4.2.1"><fileset dir="build42" includes="*.cod"></fileset></codset><!-- 4.2.1 and above --><codset greaterthanequal="4.2.1"><fileset dir="build421" includes="*.cod"></fileset></codset></application></alx><zip destfile="release.zip" basedir="release"></zip> Example 9 <!-- jadtool task is pretty simple --> <jadtool input="ca_slashdev_myapp.jad" destdir="ota"><fileset dir="build" includes="*.cod"></fileset></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"></fileset><override key="MIDlet-Name" value="My Title"></override></jadtool> Site powered by: | Markdown | MagpieRSS Tasks </rapc></tag></tag></tag></tag></jadtool></override></filelist></fileset></jadtool></filelist></fileset></application></codset></jdp></alx></application></codset></application></alx></filelist></fileset></sigtool></jdp></jdp></entry></jdp></import></src></src></filelist></fileset></src></src></define></src></src></jdp></rapc></sigtool></rapc></jadtool></alx></sigtool></rapc>