Development Environment

Note: These instructions are applicable to the latest 2.0 trunk and the latest RIM Eclipse Plug-in 1.1. For older versions of trunk (now tagged 1.9.0) and the 1.1 (1.1) branch, see this page. 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.5 along with the plug-in, so it is the only thing you need to download directly
  • Once installed, use the Eclipse update features to apply any pending updates
  • Add RIM's update site, and install additional component packs.
  • These instructions assume all the component packs are installed, but you can probably reconfigure things to work with just the included 5.0 component pack.

Getting the source code

Check out the LogicMail sources from the repository

• Using a standalone Subversion client, such as TortoiseSVN or the command-line "svn", check out the sources from the following path:
  • https://logicmail.svn.sourceforge.net/svnroot/logicmail/trunk
• The checkout should be done into a new directory, which I name "LogicMail" for convenience.

The sources will include the following subdirectories:

Name	Description
LogicMail	Main program library project
LogicMail_BB??	Platform support library project(s)
LogicMail_BB??T	Platform support library project(s) for touchscreen devices
LogicMailStartup	Main program entry point project
LogicMailTests	Unit test project
J2MEUnit	Unit test library project
lib	Build 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

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:

Configuration	JRE	Simulator	Projects
BlackBerry 8800 (4.5.0)	BlackBerry JRE 4.5.0	8800	LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit
BlackBerry 9700 (5.0.0)	BlackBerry JRE 5.0.0	8900	LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit, LogicMail_BB46, LogicMail_BB47, LogicMail_BB50
BlackBerry 9550 (5.0.0)	BlackBerry JRE 5.0.0	9500	LogicMail, LogicMailStartup, LogicMailTests, J2MEUnit, LogicMail_BB46, LogicMail_BB47, LogicMail_BB47T, LogicMail_BB50, LogicMail_BB50T

Debugging notes

• I've found that the 4.2.1 simulator does not work quite right, so I do my 4.2.1 testing on the 4.5.0 simulators
• All simulators from the same BlackBerry JRE version share the same directory on your hard drive, so you might want to manually clean out all LogicMail files when switching between touch and non-touch devices. (the factory classes should handle this case correctly, so you might not need to do this)

Windows Vista/7 Notes

• 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.)