wiki:development

Development Environment

Note: These instructions are applicable to trunk, using and the RIM BlackBerry Java Plug-in for Eclipse v1.5. I should also mention that the fully integrated development environment requires MS Windows. However, it should be possible to just build the application using  Apache Ant on any platform supported by Java and a J2ME preverify binary. Those instructions are out of scope for this page, however.

Tools

The first step is to download and install the following tools:

  •  Subversion
    • I recommend  TortoiseSVN for general use in Windows.
    • You may want to also download the main command-line client from the above web page, as other tools might need it.
  •  BlackBerry Java Plug-in for Eclipse
    • This download includes a full  Eclipse 3.6 along with the plug-in, so it is the only thing you need to download directly. However, if you prefer Eclipse 3.7 (like me), you can install it normally then add the plug-in via RIM's Eclipse update site.
    • Once installed, use the Eclipse update features to apply any pending updates
    • Add RIM's  update site, and install additional component packs.
      • The LogicMail code currently assumes the following component packs are installed: 4.5.0, 4.6.0, 4.7.0, 5.0.0, 6.0.0
      • If you don't want to install all of these component packs, you may need to exclude some library projects and/or reconfigure some BlackBerry JDK dependencies.
      • RIM has recently decided to remove the component packs for anything below 5.0, except for 4.5, from their update site. See this  forum post for some details. If you don't mind warning messages, the easiest solution is to just configure the 4.6 and 4.7 support library projects to use 5.0 when in eclipse. Otherwise, you'll need to track down the relevant Eclipse plugin component packs from other sources.

Getting the source code

Check out the LogicMail sources from the repository

The sources will include the following subdirectories:

NameDescription
LogicMailMain program library project
LogicMail_BB??Platform support library project(s)
LogicMailStartupMain program entry point project
LogicMailTestsUnit test project
J2MEUnitUnit test library project
libBuild support files

Note: The complex-looking organization of library and entry point projects is necessary for things to work smoothly with the Eclipse Plug-in. The actual official Ant-based builds pull the various collections of source code together and produce simple monolithic COD stacks.

Setting up the Eclipse IDE

  • Start Eclipse
    • Choose the new directory used above for the checkout for your "workspace" directory
    • Eclipse should come up with a fresh layout, so click the icon to "Go to the workbench."
  • Configure Eclipse
    • Select: Window --> Preferences
      • BlackBerry Java Plug-in --> Code Signing
        • Check all boxes
      • Java --> Code Style --> Formatter
        • Create new profile based off default
        • Change tab policy to "Spaces only"
  • Import the LogicMail projects
    • Select: File --> Import...
    • In the Import dialog, select "General / Existing Projects into Workspace" and click Next
    • Set the root directory by clicking Browse... and choosing the workspace directory (it should be the one selected by default)
    • Make sure that all projects are checked
    • Click Finish
  • Fix broken references to analytics libraries*
    • Right-click on the project called "LogicMailStartup", and select "Properties"
      • Java Build Path --> Libraries
      • Click on the library name starting with: "AnalyticsService"
      • Click the button: "Remove"
      • Click "OK"
    • Look for any source files in "LogicMailStartup" with "Webtrends" in their name, and delete them

(*) If you want analytics support, see "lib/README.txt" for information on the necessary libraries.

Debugging in Eclipse

Debug configuration

  • Go to: "Run --> Debug Configurations..."
    • Select "BlackBerry Simulator" and click the New button
    • Name the configuration something meaningful (i.e. "BlackBerry 8800 (4.5.0)")
    • Go to the "Projects" tab, and select the projects necessary for the BlackBerry OS you are testing on
    • Go to the "JRE" tab, and select the BlackBerry OS version you want to test on
    • Go to the "Simulator" tab
      • Select the Device you want to test on
      • Useful options include:
        • Debugging --> Interrupt debugger on potential deadlock
        • View --> Disable automatic backlight shutoff
        • Memory --> Use PC filesystem for SD Card files (less important, unless you want easy access to local mail folder files)
    • Click Apply then Close
  • Go to: "Run --> Debug"
  • Wait for the simulator to launch, and have fun!
  • To do any actual debugging, select: "Window --> Open Perspective --> Debug"

Configuration samples

Here are some useful sample configurations:

ConfigurationJRESimulatorProjects
BlackBerry 8800 (4.5.0)BlackBerry JRE 4.5.08800LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit
BlackBerry 9700 (5.0.0)BlackBerry JRE 5.0.09700LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit,
LogicMail_BB46,
LogicMail_BB47,
LogicMail_BB50
BlackBerry 9550 (5.0.0)BlackBerry JRE 5.0.09550LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit,
LogicMail_BB46,
LogicMail_BB47,
LogicMail_BB50
BlackBerry 9800 (6.0.0)BlackBerry JRE 6.0.09800LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit,
LogicMail_BB46,
LogicMail_BB47,
LogicMail_BB50,
LogicMail_BB60

Debugging notes

  • The simulator  code hot swap feature in the latest version of the Eclipse plugin does not work correctly on a complex application like LogicMail. Startup code and controlled access code fails in strange ways.

Windows Vista/7 Notes

  • These tips are now most likely out of date, and no longer necessary.
  • Make sure your user has Full Control permissions to whatever directories Eclipse and other BlackBerry development tools are installed into.
  • If the simulator fails to launch and is stuck at approximately 19% progress, open the task manager and kill any stray instances of "BbDevMgr.exe"
  • On x64, exit the simulator by selecting the Disconnect icon on the "Debug" perspective, as it will not exit normally. (If you try to exit it normally, you will have to kill "fledge.exe" in the task manager, and may have to restart Eclipse to debug again.) The latest update to the Eclipse plugin fixes this issue, for the most part, but you'll still run into it if you run the simulator outside of Eclipse.