wiki:development_e10

Development Environment

Note: These instructions are applicable to the 2.0 branch. For the 1.0.x 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.
  •  Eclipse IDE
    • Download Eclipse 3.4.2 (Java or Java EE version)
    • Install normally, which usually just means unzipping somewhere and creating a shortcut. (Eclipse traditionally lacks an actual installer program.)
  •  BlackBerry JDE Plug-in for Eclipse
    • You can either use the Eclipse  update site, or manually download the plugin and any component packs you want.
      • In theory you need the 4.2.1 for the base application, though I've had some issues with it. (I just use the 4.5 component pack and try to avoid any API calls not available in 4.2.1, which is what the automated builds use.)
      • If you also want to work on support for newer devices, download those component packs as well. (Currently this just includes 4.7.)
    • Follow the  instructions on that page for installation.
  •  BlackBerry Smartphone Simulators

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
LogicMailInitAlternate entry point project
LogicMailTestsUnit test project
J2MEUnitUnit test library project
libBuild support files
.BlackBerryWorkspace configuration files

Note: The complex-looking organization of library and entry point projects is necessary for things to work smoothly with the Eclipse IDE plugin. 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."
    • If you installed the "Java EE" version, which defaults to the "Java EE" perspective, select "Window --> Open Perspective --> Java" to open the regular "Java" perspective.
  • Prepare the workspace for BlackBerry development
    • Select: File --> New --> Other...
    • In the New project wizard dialog, select "BlackBerry / BlackBerry Project" and click Next
    • Type "foo" for the project name, and click Finish
    • Right-click on "foo" in the "Package Explorer" pane, and click Delete
    • Check "Delete project contents on disk" and click OK
    • Note: These steps may seem unusual, but they are necessary to properly initialize the workspace. Directly importing the LogicMail projects upfront causes problems with this version of the plug-in. If imported as Java projects, the BlackBerry workspace will not initialize. If imported as BlackBerry projects, the plug-in will mangle the project configuration.
  • 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 the following five projects are checked: J2MEUnit, LogicMail, LogicMailStartup, LogicMailInit, LogicMailTests, then click Finish
    • If you get any warnings about restricted APIs, go to "BlackBerry --> Configure BlackBerry Workspace," navigate to "Code Signing," and make sure "RIM Runtime API" is checked.
    • If the project icons are not blue, or other strange things are happening, check the following:
      • Right click on the projects, and make sure that "Activate for BlackBerry" is checked
      • Make sure in the menu bar that "Project --> Build Automatically" is checked
      • Make sure that the selected component pack in the BlackBerry Workspace configuration is 4.5.0 or lower
      • Try cleaning and rebuilding a few times (this plug-in is still a bit flaky)

Developing for newer platforms

The current base version of the BlackBerry OS for LogicMail is 4.2.1, and no code in the base application source tree should reference anything not available in that API. To provide support for API features in newer versions of the BlackBerry OS, a series of platform support libraries have been created. These libraries will be created in an incremental fashion, with any given library depending on every platform library before it, to minimize code duplication. Since the first new platform to be supported is 4.7, these instructions are written in terms of that version. These instructions also assume you are already in Eclipse with the LogicMail workspace loaded.

  • Select: BlackBerry --> Configure BlackBerry Workspace
    • Go to: BlackBerry JDE --> Installed Components
    • Select: "BlackBerry JDE Component Package 4.7.0"
    • Click OK
  • 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
    • Check the following project: LogicMail_BB47 and click Finish
  • It may take some clean/rebuild fiddling to get everything working again, but you should now be able to build and test the newer API support.

Debugging in Eclipse

  • Go to: "Run --> Debug Configurations..."
    • Select "BlackBerry Simulator" and click the New button
    • Name the configuration something meaningful (i.e. "BlackBerry Simulator")
    • Go to the "Simulator" tab, if you want to set any options
      • You need to select a profile other than "Default simulator" to set options
      • 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"

Windows Vista 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 Vista 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.)