Blog Not just another WordPress weblog


BlackBerry WebWorks application – build and deploy KitchenSink

BlackBerry WebWorks provides the flexibility for developers to build native applications using JavaScript, HTML 5 and CSS. The JavaScript library included in the project provides a bridge to all pretty much all native JavaME based API set.

Including any custom JAR is also very straightforward. The applications built using the SDK are stand alone, meaning the assets required by the HTML are not fetched from a remote server. The application lives on the device and packaged with the WebKit engine container to be viewed by the "headless browser".

Building applications on Mac has always been a challenge and WebWorks is no difference. Here is a step by step guide to deploy the KitchenSink application for BlackBerry smartphones on Mac OS X.

I am copying full path to all projects in this post. Path and naming conventions are not absolute for a successful deployment however.

Get the smartphone SDK: - this link lists a few SDKs including BlackBerry 10 and Tablet OS. I am using the smartphone SDK 2.3.1. Path to the SDK in my machine is

/Developer/SDKs/Research\ In\ Motion/BlackBerry\ WebWorks\ SDK\

Get KitchenSink source: - I use XAMPP for web development and save all WebWorks projects in the htdocs folder. It is not necessary to have your source accessible via web server at all. I put all necessary source code in a "www" folder. All compiled and signed code goes in the "output" folder.

Get certificates to sign your code:
WebWorks uses a lot of secure APIs which enables the platform to communicate with hardware and other cryptic API set. To run the application on a device you would require to sign your code.

You would receive a few emails which will include .csi files. The files are usually named client-RBB-XXXXXXXXXX.csi, client-RCR-XXXXXXXXXX.csi and client-RRT-XXXXXXXXXX.csi. XXXXXXXXXX will be a number set by the BlackBerry code signature service. Use this help form if you are lost signing your code at any time.
Save the files in the "bin" folder of your SDK and go there from terminal. Now run

java -jar SignatureTool.jar client-RBB-XXXXXXXXXX.csi

You would need to run the signature tool on each of the RBB, RCR and RRT file.

java -jar SignatureTool.jar client-RCR-XXXXXXXXXX.csi
java -jar SignatureTool.jar client-RTT-XXXXXXXXXX.csi

Start building:

1. Package: First step to build a WebWorks application is packaging the source. You need to package the source into a ZIP file. Archiving the source from the GUI does not work! Apparently the GUI archiver puts different headers that the SDK does not understand. Also it will package the .DS_Store and any hidden .git and .svn folders, if the application is under version controlling.

Go to the www folder and run the following to zip the source code.

zip -r ../output/ * -x "*.DS_Store"

If you need to ignore other files and folders add the name after another -x option. e.g. to ignore file you would run

zip -r ../output/ * -x "*.DS_Store" -x ""

2. Build: To build the application you would need to run the bbwp from the SDK folder. You can also run jar located in the bin folder. You can specify bbwp properties from the file. I am specifying the bbwp to use version 6.0 of the RIM api by updating the jar location from "jar" attribute to "lib\6.0\net_rim_api.jar". You can copy the net_rim_api.jar from any BlackBerry JDE and place it under the lib folder. The name of the file is generic, so placing under folders by the version number, e.g. 6.0, 7.0, is probably a good idea.

Go to your project root e.g. "/Applications/XAMPP/htdocs/webworks/KitchenSink/" and create a folder called "output" Run the following command in terminal to build your WebWorks application

java -jar /Developer/SDKs/Research\ In\ Motion/BlackBerry\ WebWorks\ SDK\ /Applications/XAMPP/htdocs/webworks/KitchenSink/output/ -g macros05 -o /Applications/XAMPP/htdocs/webworks/KitchenSink/output/

This will create 2 folders named "OTAInstall" and "StandardInstall". If you want to download the application via the device's web browser, you would need to point the browser to the .jad folder. You can use the BlackBerry desktop software to install the application as well. You would need to point the installer to the .alx file in the "StandardInstall" folder in this case. I find the desktop software being very slow and buggy.

3. Deploy: The WebWorks includes a tool called javaloader to deploy signed applications to device and emulators. Deploying to device is pretty straight forward. Connect the device to your machine via USB and run following command in the terminal

/Developer/SDKs/Research\ In\ Motion/BlackBerry\ WebWorks\ SDK\ load /Applications/XAMPP/htdocs/webworks/KitchenSink/output/StandardInstall/KitchenSink.cod

This will install the application and restart your device.

I have put together a simple script which does all of the packaging, building and deployment. You can also use Ripple emulator to package and build your application. The reference guide is here.