Initial Setup
As with any new language or platform, you will need to install some new software and set up your computer appropriately. There are many different ways to run a successful BlackBerry project. RIM supports only Windows development, but it has done a good job of releasing tools that enable development on a variety of configurations. This section will focus on what I have found to be the simplest and most effective setup for independent development, with occasional notes for alternative choices you might consider.

Getting Java
You will be developing in Java for the BlackBerry, but before we get that far, we need to make sure Java on your desktop is running properly. RIM uses Java for their  toolchain—the set of programs that will convert your application source files into a format that can run on the mobile device. Additionally, our Eclipse IDE requires a Java runtime environment.

To see if Java is installed, open a command prompt. You can do this by clicking  Start ➞Run, typing cmd, and pressing enter. A black-and-white command prompt window will appear. Type java -version. You should see something like the following:

To install Java, go to http://java.sun.com and look for the Java SE download. You only need to install the Java Runtime Environment (JRE). However, if you plan on doing other Java development besides BlackBerry, you can download the full Java Development Kit (JDK), which also includes the JRE.

Tip: When installing any development software, I suggest you pick an install path that has no spaces in it. For example, instead of installing to c:\Program Files\Java, install toc:\dev\java. This will save you time in the future, as some Java programs and other useful utilities have a hard time working with files that have spaces in their name. Follow this rule for all the other downloads in this chapter, as well.

Once you have downloaded and installed the JRE, try opening another command prompt and typing java -version again. If it still doesn’t recognize the command, you probably need to add Java to your PATH environment variable. In Windows XP, you can access this by right-clicking on My Computer, selecting Properties, clicking the Advanced tab, and then clicking Environment Variables. Make sure the path to your

Goldilocks and the Three IDEs
Once upon a time, a developer was evaluating which IDE to use when writing BlackBerry apps. First she tried the RIM JDE. “Oh my!” she exclaimed. “This IDE is much too ugly!” Then she tried Netbeans. “This IDE doesn’t understand BlackBerry,” she complained. Finally, she installed Eclipse with the BlackBerry Plug-in. “Ahhh,” she smiled. “This IDEis just right!”

The reality is that you can develop in any IDE that you want. The question is how much time and effort you will invest in getting everything to work right. I’ve found that Eclipse is the best platform for doing serious development, and it has only gotten better and easier since RIM released their official Plug-in. I will be using Eclipse for my examples in the rest of this book, and I recommend installing it unless you are already doing
BlackBerry development in another environment. To get started, go to http://eclipse.org. I suggest you download a recent release of the Eclipse IDE for Java EE Developers. Depending on what other kinds of development you do, you may choose to use another package. This is fine, but Eclipse EE contains the most options and will give you the greatest flexibility.

Caution: As of this writing, there are compatibility issues with Eclipse 3.5 (Galileo) and the BlackBerry JDE Plug-in for Eclipse. If you experience problems, use the older 3.4 (Ganymede) version of Eclipse. This is currently located in the Downloads page of the Eclipse web site,where you can select ‘‘Older Versions.’’ You can safely install multiple versions of Eclipse intoseparate directories on your computer.

Eclipse doesn’t have a standard Windows installer. Instead, you simply unzip it to a folder on your computer. You could put it somewhere like c:\dev\eclipse. To make it easier to launch, you can right-click and drag the eclipse.exe icon to your desktop or task bar in order to create a shortcut. When you first launch Eclipse, it will ask you to choose a workspace. You can create one wherever you like. Do not check the option for “Use this as the default and do not ask me again.” One quirk of BlackBerry development is that each BlackBerry app you develop will require its own separate workspace, so you will be switching workspaces
as you go through this book.

Plugged In
I have been a fan of Eclipse for many years now, in large part because of its very flexible and powerful Plug-in system. Plug-ins allow developers to tune their workspace for their specific tasks, without needing the bother of relearning a new tool for each new task. There are currently two ways to install the Plug-in. The first is to go to BlackBerry’s developer web page (currently located at http://na.blackberry.com/eng/developers/) and download the Plug-in as an EXE file. This is the simplest approach, as you cansimply download the large file, run it, and then restart Eclipse. The other way to install the Plug-in is directly through Eclipse. I recommend taking this pproach, as it allows you more control over what you install and provides a better way to getupdates. In Eclipse, click the Help menu, then Software Updates. Click the Available Software tab,then click Add site. For the location, enter http://www.blackberry.com/go/eclipseUpdate.The BlackBerry Update Site will display. Several options are available. At a minimum,you will need to select the BlackBerry JDE Plug-in for Eclipse and at least one
BlackBerry Component Pack.

Note: You may be asked to enter a user name and password. You can register for a free developer account on the BlackBerry web site if you have not already done so. This prompt may appear multiple times, so continue entering the account name and password until it goes away. The servers hosting the Plug-in are sometimes temperamental and will fail with unhelpful messages; other times, the installation may appear to hang when it is actually progressing. If you cannot install through Software Updates, you can try again later, or install the EXE file directly as described above.


Tip: You can find the software version on your BlackBerry by selecting Options, and then About. It should be a value like ‘‘4.5.0.81’’. When selecting a component pack, only the first two numbers are important. The rest will be used to select an appropriate simulator. You should restart Eclipse once the install is complete. After it restarts, you will see a new BlackBerry menu option at the top. You will also have access to two new debug configurations: BlackBerry Device and BlackBerry Simulator. Figure 1-1 shows what your Eclipse environment should look like once you have installed the Plug-in and started a new project.

If you are developing for a personal BlackBerry device, you probably already have the BlackBerry Desktop Manager and the BlackBerry Device Manager installed. If not, installing them is very easy. Go to http://www.blackberry.com and look for the “Desktop Software” download. You may need to select your provider and download the appropriate version for them. You will need to fill out a short form with your name and contact information. Run the downloaded setup file. You may be prompted to install additional software, such as the .NET Framework runtime. Once it’s complete, reboot your computer if prompted. The next time you connect your BlackBerry device to the computer, Windows should automatically install the drivers to access it. You can launch the BlackBerry Desktop Manager by going to your Start menu and
looking under BlackBerry. Depending on your installation choices, the manager may automatically start when you log in to Windows. Figure 1-2 shows the BlackBerry Desktop Manager running.
Simulator Files
Downloading the proper simulator files for the devices you plan to run on is essential, because different types of devices will have different screen sizes and input modes. Even if you have two devices with the same model number, they will behave differently depending on what software version they are running. Simulators are not just important for testing on the computer, though. They also contain essential information for
debugging on the actual device. If you have the physical device you will be using, find the device software version by visiting Options, then About. You will be looking for a version that matches all parts of
the version number. For example, if your device has version 4.5.0.81, only use 4.5.0.81, not another version that starts with 4.5.0. You can download simulator packs from the BlackBerry web site. The exact location will change, so your best bet is to visit the Developers page and look around for the BlackBerry Smartphone Simulators. You will see many, many choices. Pick the one that matches your exact version number and
device model and, if applicable, carrier. You’ll need to click through another web

form—get used to it, as there is no way to save your information. Download the simulator file, then run it to install. You can install to any directory you like.

To switch to using a new simulator in Eclipse, follow these steps, and restart Eclipse if
you are ever prompted to do so.

1. Click the Window menu, then Preferences.
2. Expand the BlackBerry JDE menu and select Installed Components.
3. From the drop-down list, select the component pack that corresponds
to your device version. For example, pick 4.5 for a device with version
4.5.0.81. If you don’t see your component pack listed, install it following
the instructions in the section titled “Plugged In” earlier in this chapter.
4. Click the MDS Simulator option and navigate to the MDS directory that
matches the component pack from Step 3.

Note: The directory will be located under your Eclipse install folder. The path should look something like eclipse\plugins\net.rim.eide.componentpack4.x.x_4.6.x.xx\ components\MDS.

5. Click OK. If you already have a project in Eclipse, you will be prompted
to rebuild it.
6. Click Run, then Debug Configurations.
7. Create a new BlackBerry Simulator configuration.
8. Click the Simulator tab.
9. From the Profile drop-down, select the item that corresponds to the
simulator you installed.

You will now be able to use your device’s proper simulator, and you will have access to high-quality on-device debugging.

The Keys to Development
So far, you have installed everything you need to get started writing BlackBerry software. There’s a catch, though: RIM has marked some of their APIs as restricted, and if your program uses any of these APIs, it will not run on the device unless it has been code signed.

Code signing is covered in more detail in Chapter 9. For now, just be aware that this is often a necessary step in development. It can take from a few days to a few weeks to receive code signing keys, so start this early.

You apply for the keys from the BlackBerry developer web site. Once again, you will need to fill out a form with information. As part of the form, you will be asked for an email address. Be aware that RIM will send multiple emails to this address every time you sign
an application. Also, keep in mind that you must sign an application every time you make a change and load it on the device. It isn’t unusual for a large RIM app to generate 50 or more emails on a single signing. Therefore, I strongly urge you to enter an unmonitored email address here, or one where you can automatically delete emails from the signing server. If you use your personal email address instead, it will make your life
miserable.

The form also includes a question about Certicom cryptography keys. Certicomcryptography is covered in more detail Chapter 5; for now, you can just say “No” here.You should also pick a unique 10-digit PIN. There is a nominal charge for receiving codesigning keys, currently $20. You will need one set of keys for each computer you will usefor development. The RIM servers sometimes have problems; if you aren’t able to complete your order online, you can choose to fax it in instead.

Eventually, you should receive an email from RIM with three key files and instruction on installation. Follow the email instructions. If you run into problems during your installation, follow the links in the email for more support. Once you have installed and registered the keys, you will be all set. You have a limited number of signatures, but the limit is absurdly high, so you don’t need to worry about ever running out.

You will initially install the signing keys for a particular version of BlackBerry device software, such as 4.5 or 6.1. At first, you will only be able to sign applications built for that particular device type. There are two fixes for this, though: first, you can safely use an old version of the RIM signing tool on newer versions of device software. In other
words, you can use the 4.5 signing tool on builds for 6.1, but not vice versa. Second,you can copy the files SignatureTool.jar, sigtool.db, sigtool.set, and sigtool.csk from one version of the desktop software to another. This also works to sign applications using both the BlackBerry Eclipse Plug-in and another environment on the same computer.

Tip: If you installed the BlackBerry Plug-in, your SignatureTool should be located in a directory like C:\dev\eclipse\plugins\net.rim.eide.componentpack4.5.0_4.5.0.16\ components\bin.

That’s it for setup! You now have all the tools you will need to write,debug, and install your own BlackBerry apps.