Compiling Blackberry Webworks on WinXP

Developing for Blackberry can be a hazardous task to say the least. As Matthew Baxter-Reynolds points out in a hilarious yet accurate article for the Guardian:

…there is absolutely no way that building software for BlackBerry is appreciably easier today than developing bank software was in the 1960s on punched cards.

I definitely have beef with Blackberry, ranging from the tools to the level of support, but let’s keep things positive.
Problem: Re-compiling your project after you have made changes and then deploying to either a device or a simulator is a time-consuming process. Between signing, loading to the device and waiting for the device to restart, let’s call it 5 minutes.
Solution: Work with remote HTML5, JS and CSS3 while developing.

In fairness to Blackberry, they have provided a tutorial on how to do this. However, this method does not seem to work with IP addresses in the private range, so you’ll need network connectivity to develop in this way, and potentially expose your code to all and sundry. If you scroll down to the comments of that tutorial, you’ll see I didn’t find a solution to this IP issue, nor in their support forums – so if anyone knows a solution, please let me know!

How: This assumes you have installed the SDK and have a signing key configured for your AppWorld account.

  1. You have a folder with your config.xml as a bare minimum. I added an ‘images’ folder for the app icon. Add these files to a zip folder. An example of what your config.xml file might look like is below
  2. <?xml version="1.0" encoding="UTF-8"?>
    <widget xmlns="http://www.w3.org/ns/widgets" xmlns:rim="http://www.blackberry.com/ns/widgets" version="1.0.0.02">
      <name>Demonstration App</name>
      <author email="rg@richardgilmour.co.uk" href="http://richardgilmour.co.uk">Richard Gilmour</author>
        <!-- content specifies the start point of app-->
       <content src="http://richardgilmour.co.uk/examples/bb/bbww_remote_index/index.html"/>
       <!-- any script originating in the bbww_remote_index folder can use the whole webworks API -->
      <access subdomains="true" uri="http://richardgilmour.co.uk/examples/bb/bbww_remote_index">
      <feature id="blackberry.system" required="true" version="1.0.0.0"/>
      <feature id="blackberry.app" required="true" version="1.0.0.0"/>
      <feature id="blackberry.app.event" required="true" version="1.0.0.0"/>
      <feature id="blackberry.find" required="true" version="1.0.0.0"/>
      <feature id="blackberry.identity" required="true" version="1.0.0.0"/>
      <feature id="blackberry.invoke" required="true" version="1.0.0.0"/>
      <feature id="blackberry.invoke.BrowserArguments" required="true" version="1.0.0.0"/>
      <feature id="blackberry.io.dir" required="true" version="1.0.0.0"/>
      <feature id="blackberry.io.file" required="true" version="1.0.0.0"/>
      <feature id="blackberry.pim.Address" required="true" version="1.0.0.0"/>
      <feature id="blackberry.pim.Contact" required="true" version="1.0.0.0"/>
      <feature id="blackberry.system" required="true" version="1.0.0.0"/>
      <feature id="blackberry.system.event" required="true" version="1.0.0.0"/>
      <feature id="blackberry.utils" required="true" version="1.0.0.0"/>
      </access>
      <!-- application has access to all other domains for content -->
      <access subdomains="true" uri="*"/>
      <icon rim:hover="false" src="images/logo.png"/>
      <rim:loadingScreen backgroundColor="#000000" foregroundImage="" onFirstLaunch="true"/>
       <rim:orientation mode="portrait" />
       <!-- We will doing a load of reloading, so let's not cache so we can see the changes -->
       <rim:cache disableAllCache="true"/> 
    </widget>
    
  3. Next, navigate to your SDK directory in command prompt. In my case, this is C:\Program Files\Research In Motion\BlackBerry WebWorks SDK 2.3.1.5>
  4. Once you have done this, you need to tell the packaging tool where the zip is located and (optionally) where to put the packaged application. In my case, I entered bbwp c:\xbb\ww01\ww01.zip /s /g /o c:\xbb\ww01\build, although the /s and /o aren’t really necessary. The /g is only required if you want to install your package on a device. A list of parameters can be found here. If you are going to use a simulator, don’t sign the package as it won’t load properly. The commands and anticipated output are below:
  5. C:\Program Files\Research In Motion\BlackBerry WebWorks SDK 2.3.1.5>bbwp c:\xbb\ww01\ww01.zip /s /g /o c:\xbb\ww01\build
    [INFO]                  Parsing command line options
    [INFO]                  Parsing bbwp.properties
    [INFO]                  Validating application archive
    [INFO]                  Parsing config.xml
    [INFO]                  Populating application source
    [INFO]                  Compiling BlackBerry WebWorks application
    [INFO]                  Starting signing tool
    [INFO]                  Signing complete
    [INFO]                  Generating output files
    [INFO]                  BlackBerry WebWorks application packaging complete
    
    C:\Program Files\Research In Motion\BlackBerry WebWorks SDK 2.3.1.5>
    
  6. You should now have a ‘build’ folder containing at least two of the following folders; ‘OTAInstall’ and ‘StandardInstall’. If you are using the Blackberry Desktop Software, you can install the application to your device. In my case, I would point the ‘import files…’ file chooser to c:\xbb\ww01\build\StandardInstall\ww01.alx. Once the app is installed, you should be able to find it in the downloads folder.

Because the starting point for the app (index.html) is located away from the device you can continue to make edits without recompiling. What works for me personally is to set up an FTP connection in Aptana that will synchronize my local files with my server. If you want to download the compiled app, please send me an email. Alternatively, you can install the Ripple emulator into Chrome, and visit the app here.
Why not just use Ripple in the first place (see update below, ripple can speed up packaging/compiling process)? There are many reasons why I personally don’t do this (which I won’t go into here), but the main one is that Ripple doesn’t emulate BB OS5, which uses a non-webkit browser. You can read all about this issue here.

You can see the ‘app’ in action below (it just uses the WebWorks API to get the phone model at the moment).

Update (26-12-2012): Manually zipping, using the command-line to compile and the using Blackberry Desktop software to push the app to a device can be timely and fiddly. I’d suggest using the Chrome Ripple extension for compiling and launching to simulators. If launching to a device, use the JavaLoader from the command line once you have compiled and signed your app.

C:\Program Files\Research In Motion\BlackBerry WebWorks SDK 2.3.1.5\bin>JavaLoader load <path to Standard Install .cod file> 

When I have more time, I intend to write an article about using ripple.