BlackBerry Ant Tools Code
Brought to you by:
jiggak
Menu
▾
▴
Tree [e01a4e] master / History
Read Me
********************************************************************************
* BlackBerry Ant Tools @VERSION@ *
********************************************************************************
Prerequisites:
--------------
- RIM JDE (tested with 4.1 and up)
- Java 1.5 or higher
- Apache Ant 1.7.x or higher
Using:
------
- Copy the bb-ant-tools.jar into the your Ant lib directory, in $HOME/.ant/lib,
or add bb-ant-tools.jar to the classpath in your build script.
- Add the <typedef> to your build script, eg:
<typedef resource="bb-ant-defs.xml" />
or
<typedef resource="bb-ant-defs.xml" classpathref="bb-ant-tools.classpath" />
- Enjoy (see examples below)
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
============
jdehome
----------------------------------------------------------------------------
Sets the JDE home directory. This attribute is required when the "jde.home"
property is not defined at the project level.
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.
srcdir
----------------------------------------------------------------------------
Directory containing source files. This attribute is required when the
nested <src> property is not used. An error is occurs if both the nested
<src> property and the "srcdir" attribute is specified.
destdir
----------------------------------------------------------------------------
Output directory of .cod file. When not defined, the base directory of the
Ant build file is used.
exepath
----------------------------------------------------------------------------
Explicitly define the directory containing the preverify command used by
the rapc compiler. When not defined, the systems default PATH is used.
output
----------------------------------------------------------------------------
Name of output file, eg: <output>.cod, <output>.cso, etc. This attribute
is 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.
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.
defines
----------------------------------------------------------------------------
':' or ';' delimited list of preprocessor tags. This attribute is optional.
See the note below regarding preprocessor usage.
quiet
----------------------------------------------------------------------------
Tells the rapc compiler to be less chatty. Optional, defaults to true.
verbose
----------------------------------------------------------------------------
Turn on verbose output of the rapc compiler. Optional, defaults to false.
nodebug
----------------------------------------------------------------------------
Turn off generation of .debug files. Optional, defaults to false.
nowarn
----------------------------------------------------------------------------
Disable warning messages. Optional, defaults to false.
warnerror
----------------------------------------------------------------------------
Treat all warnings as errors. Optional, defaults to false.
noconvert
----------------------------------------------------------------------------
Do not convert all images to PNG. Optional, defaults to false.
nopreverify
----------------------------------------------------------------------------
Do not call the preverify executable. Optional, defaults to false.
encoding
----------------------------------------------------------------------------
Set file encoding name for source files. Optional, uses system default.
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.
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".
Parameters specified as nested elements
=========================================
<define>
----------------------------------------------------------------------------
Zero or more preprocessor tag definitions nested as elements.
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 project attributes.
type
------------------------------------------------------------------------
Type of cod file to create. Valid values are "library", "cldc",
"midlet". When "midlet" is specified, the midletclass property is
required. The default is "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. If not set, the default is 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.
runonstartup
------------------------------------------------------------------------
Set to true if application should start when device starts.
startuptier
------------------------------------------------------------------------
Startup priority relative to other applications. The default value is
7, lower value = higher priority.
ribbonposition
------------------------------------------------------------------------
Position of icon in ribbon. The default is 0, higher values move the
icon closer to the top of the ribbon.
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.
file
------------------------------------------------------------------------
Properties file containing the project attributes. Property names
must match the names defined above.
<entry> - nested element of <jdp>
------------------------------------------------------------------------
Defines zero or more alternate entry points, CLDC applications only.
The <entry> element is a nested element of <jdp> and supports a subset
of project attributes.
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.
runonstartup
--------------------------------------------------------------------
Set to true if application should start when device starts.
startuptier
--------------------------------------------------------------------
Startup priority relative to other applications. The default value
is 7, lower value = higher priority.
ribbonposition
--------------------------------------------------------------------
Position of icon in ribbon. The default is 0, higher values move
the icon closer to the top of the ribbon.
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.
file
--------------------------------------------------------------------
Properties file containing the project attributes. Property names
must match the names defined above.
if
--------------------------------------------------------------------
Include entry point when the named property is set. Optional.
unless
--------------------------------------------------------------------
Include entry point when the named property is NOT set. Optional.
Preprocessor
==============
Apparently since version 4.0, rapc compiler has had support for a simple set
of preprocessor macros. To use the preprocessor you must:
* have version 4.x or higher of JDE
* 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 <define> elements.
See reference documentation for <rapc> task above.
Examples
==========
<!-- bare minimum usage -->
<rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}"
jdehome="${jde.home}" />
<!-- 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>
<!-- use fileset to select source files, import dependancy 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}">
<include name="**/*.java" />
<includs name="**/*.rrc" />
</fileset>
</src>
<import location="../libKickAss/ca_slashdev_libKickAss.jar" />
</rapc>
<!-- use the preprocessor -->
<rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}" defines="TAG1;TAG2">
<define tag="TAG3"/>
<define tag="TAG4"/>
</rapc>
<!-- set rollover icon in home screen (>= JDE 4.7) -->
<rapc output="ca_slashdev_MyKickAssApp" srcdir="${src.dir}">
<jdp icon="icon.png" focusicon="focus.png" />
</rapc>
<sigtool>
Sigtool task will launch the signature tool on a given cod file or set of
cod files. When the cod file is successfully signed, a file is created
along side the cod file to mark it as signed.
Parameters
============
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.
sigtooljar
----------------------------------------------------------------------------
Set the path to the signature tool jar file. When this attribute is
set the "jdehome" attribute is optional.
codfile
----------------------------------------------------------------------------
Single cod file to sign.
forceclose
----------------------------------------------------------------------------
Close signature tool even if signature failed. Default is false.
close
----------------------------------------------------------------------------
Close after signature request if no errors have occured. Default is true.
request
----------------------------------------------------------------------------
Request signature when application launches. Default is true.
password
----------------------------------------------------------------------------
Removes the interactive password prompt. This implicitly sets "close" and
"request" to true.
Parameters specified as nested elements
=========================================
Sigtool task supports selecting cod files using nested resource collections
such as <fileset> and <filelist>.
Examples
==========
<!-- sign single cod file -->
<sigtool jdehome="${jde.home}" codfile="build/ca_slashdev_MyKickAssApp.cod" />
<!-- 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>
<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.
Parameters
============
destdir
----------------------------------------------------------------------------
Destination director for .cod files and .alx file. If the directory does
not exist, it will be created. This attribute is required.
filename
----------------------------------------------------------------------------
Name of .alx file to generate. This attribute is required.
Parameters specified as 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).
id
------------------------------------------------------------------------
Unique id of the application, eg: com.mycompany.myapp. This attribute
is required.
name - application name.
description - application description
version - version number, eg: 1.0
vendor - vendor string, eg: My Company
copyright - copyright information
file
------------------------------------------------------------------------
Optionally specify a properties file of application attributes, must
match names defined above. *NOTE*: 'title' is recognized as an alias
for 'name' so properties files created for <jdp> type can be used here.
greaterthan
------------------------------------------------------------------------
Only install application on versions of the BlackBerry software greater
than the given version.
greaterthanequal
------------------------------------------------------------------------
Only install application on versions of the BlackBerry software greater
than or equal to the given version.
lessthan
------------------------------------------------------------------------
Only install application on versions of the BlackBerry software less than
the given version.
lessthanequal
------------------------------------------------------------------------
Only install application on versions of the BlackBerry software less than
or equal to the given version.
<codset>
------------------------------------------------------------------------
One or more nested elements of <application> element.
Cod files must be listed using nested resource collections such as
<fileset> and <filelist>.
Cod file sets can be used to target specific versions of the BlackBerry
software by setting either or both of the greaterthan and lessthan
properties. Both properties have the alternate inclusive version
greaterthanequal and lessthanequal.
dir
--------------------------------------------------------------------
Directory for cod files in destination directory.
greaterthan
--------------------------------------------------------------------
Only install cod files on versions of the BlackBerry software
greater than the given version.
greaterthanequal
--------------------------------------------------------------------
Only install cod files on versions of the BlackBerry software
greater than or equal to the given version.
lessthan
--------------------------------------------------------------------
Only install cod files on version of the BlackBerry software
less than the given version.
lessthanequal
--------------------------------------------------------------------
Only install cod files on version of the BlackBerry software
less than or equal to the given version.
Examples
==========
<!-- 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" />
<!-- 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" />
<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
============
input
----------------------------------------------------------------------------
Input .jad file. This attribute is required.
destdir
----------------------------------------------------------------------------
Destination directory for cod files and new jad file. This attribute is
required.
Parameters specified as 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 element of <jadtool>. Provides the ability to add and/or update
fields in the destination .jad file.
key
------------------------------------------------------------------------
Name of .jad property to add/change
value
------------------------------------------------------------------------
New value for .jad property
Examples
==========
<!-- not much too this task -->
<jadtool input="ca_slashdev_myapp.jad" destdir="ota">
<fileset dir="build" includes="*.cod" />
</jadtool>
<!-- override the name of the application -->
<jadtool input="ca_slashdev_myapp.jad" destdir="ota">
<fileset dir="build" includes="*.cod" />
<override key="MIDlet-Name" value="My Application Title"/>
</jadtool>
Licensing:
----------
This product is distributed under the GPL. Please read through the file
COPYING for more information about our license.
