Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Testing and debugging your app

Debugging apps using debug packages (Mac)

You can download a debug package that allows you to debug your app on a BlackBerry device that is connected to your Mac computer by a USB cable. If a debug package does not exist for the version of the BlackBerry Device Software that you require, you can create a debug package manually from the Windows version of the corresponding BlackBerry Smartphone Simulator.

A debug package contains the following files:

  • debug_manifest.xml
  • .debug files
  • Readme.rtf

Debug an app by using a debug package

Download a debug package from http://us.blackberry.com/sites/developers/resources/macdebug.html  that matches the version of the BlackBerry Device Software that is installed on your BlackBerry device. You must have the latest version of the BlackBerry Desktop Software installed on your computer.

  1. Extract the contents of the debug package to a folder on your hard disk.
  2. Connect the BlackBerry device to your computer by using a USB cable.
  3. If the BlackBerry Desktop Software is open, close it.
  4. In Eclipse, right-click a BlackBerry application project and click Debug As > BlackBerry device.
  5. When prompted, navigate to the location where you extracted the debug files and select that folder to continue the debug process.

Create a debug package manually

Visit www.blackberry.com/developers/simulators to download the Windows version of the BlackBerry Smartphone Simulator that matches the version of the BlackBerry Device Software that is installed on your device. You must install the BlackBerry Smartphone Simulator in a Windows environment, for example by using VMware on a Mac or on a computer that is running Windows.

You can create a debug package from the Windows version of a BlackBerry Smartphone Simulator. You can use the debug files to debug your BlackBerry device application on a BlackBerry device that is connected to your Mac computer by a USB cable.

  1. In a Windows environment, extract the simulator bundle to a folder on your hard disk.
  2. In the <device>.xml file, verify that the <platformVersion> attribute matches the version of the BlackBerry Device Software on the device.
  3. In the folder where you extracted the simulator bundle, add the following files to a .zip file:
    • .../Debug/...<subdirectory>/*.debug
  4. Name the .zip file debug_x.x.x.xxx_yyyy.zip where x.x.x.xxx is the version of the BlackBerry Device Software and yyyy is the model number of the device, for example debug_6.0.0.246_9800.zip.
  5. Extract the debug_x.x.x.xxx_yyyy.zip file to a folder on your Mac computer.

Configuring the BlackBerry Smartphone Simulator (Windows)

Settings for the BlackBerry Smartphone Simulator are associated with a launch configuration. Each launch configuration is associated with a set of projects and a specific version of the BlackBerry Device Software.

Specify configuration settings for the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To work with a new launch configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Simulator tab.
  5. Click the General tab.

Specify the appearance of the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To work with a new launch configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Simulator tab.
  5. Click the View tab.

Specify debugging preferences for the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Simulator tab.
  5. Click the Debugging tab.

Specify network settings for the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Simulator tab.
  5. Click the Network tab.

Specify ports for the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To work with a new launch configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Simulator tab.
  5. Click the Ports tab.

Specify memory settings for the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Simulator tab.
  5. Click the Memory tab.

Specify advanced features for the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, select New.
  4. Click the Simulator tab.
  5. Click the Advanced tab.

Specify a BlackBerry device for a BlackBerry Smartphone Simulator launch configuration

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, select New.
  4. Click the Simulator tab.
  5. Click the General tab.
  6. In the Device drop-down list, select a BlackBerry device.

Specify a BlackBerry Smartphone Simulator that is installed outside of the Eclipse environment

You can download and install a BlackBerry Smartphone Simulator that is compatible with the BlackBerry JRE of your BlackBerry application project outside of the Eclipse IDE and use it in the BlackBerry Java Plug-in for Eclipse. To download a BlackBerry Smartphone Simulator installation file, visit www.blackberry.com/developers/simulators.

  1. On the Run menu, click Run Configurations or Debug Configurations.
  2. Click the configuration that you want to use, or create a new configuration.
  3. Click the Simulator tab.
  4. In the Device drop-down list, click a BlackBerry device from the BlackBerry Smartphone Simulator set that you installed.
  5. Click Run or Debug.

Run an app in the BlackBerry Smartphone Simulator

The BlackBerry Smartphone Simulator orBlackBerry device displays icons on the Home Screen or in the Downloads folder for all of the apps that are installed. When you select an icon, the name of the application appears at the bottom of the BlackBerry device screen.

  1. In the Package Explorer view, right-click a project.
  2. Click Run As > BlackBerry Simulator.
  3. In the BlackBerry Smartphone Simulator, click the application icon.

Testing your app with the BlackBerry Smartphone Simulator (Windows)

Testing a BlackBerry device application that uses an HTTP connection

You can test applications that require an HTTP connection (for example, email) by using a BlackBerry device that is registered on a wireless network in the BlackBerry MDS Connection Service.

Start the BlackBerry MDS Connection Service when you start the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Complete one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, select New.
  4. Click the Simulator tab.
  5. Click the General tab.
  6. Select the Launch Mobile Data System Connection Service (MDS-CS) with simulator check box.
  7. Click Apply.

Open a website in the BlackBerry Browser when the BlackBerry Smartphone Simulator BlackBerry device starts

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, select New.
  4. Click the Simulator tab.
  5. Click the General tab.
  6. Select the Launch Mobile Data System Connection Service (MDS-CS) with simulator check box.
  7. In the Launch app or URL on startup field, type the web address.
  8. Click Close.
  9. Click Yes.

Start a BlackBerry device application when the BlackBerry Smartphone Simulator or a BlackBerry device starts

  1. In Eclipse, on the Run menu, click Debug Configurations or Run Configurations.
  2. Perform one of the following tasks:
    • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration.
    • To create a new launch configuration, right-click BlackBerry Simulator, select New.
  3. Click the Simulator tab.
  4. Click the General tab.
  5. In the Launch app or URL on startup field, type the name of the .cod file of the application.
  6. Click Close.
  7. Click Yes.

View output from the BlackBerry Smartphone Simulator

  1. In Eclipse, on the Window menu, click Show View > Console.
  2. In the Console view, select Display Selected Console.
  3. From the console drop-down list, click BlackBerry Simulator Console Output.

Add a BlackBerry device application to the BlackBerry Smartphone Simulator launch configuration

  1. On the Run menu, click Debug Configurations or Run Configurations.
  2. Expand the BlackBerry Simulator item.
  3. Perform one of the following tasks:
    • To work with an existing configuration, under BlackBerry Simulator, click a configuration.
    • To create a new configuration, right-click BlackBerry Simulator, and click New.
  4. Click the Projects tab.
  5. Click the BlackBerry device application that you want to add.
  6. Click Close.
  7. Click Yes.

Debug a BlackBerry device application on a BlackBerry Smartphone Simulator that is running

  1. On the Run menu, click Debug Configurations.
  2. Right-click Running BlackBerry Simulator, and click New.
  3. In the Name field, type a name.
  4. Click Debug.

Add a .jar file, that was created without using RAPC, to the BlackBerry Smartphone Simulator or a BlackBerry device

When your BlackBerry application project imports a .jar file that was created without using RAPC, you can add the .class files to your BlackBerry application project and install the .class files in the BlackBerry Smartphone Simulator or on a BlackBerry device.

  1. In the Package Explorer view, right-click a BlackBerry application project.
  2. Click Properties.
  3. Click Java Build Path.
  4. On the Libraries tab, click Add JARs or Add External JARs.
  5. Navigate to the .jar file that you want to add, and click Open.
  6. On the Order and Export tab, select the .jar file and click OK.
  7. Package the BlackBerry application project and run the application on the BlackBerry Smartphone Simulator or the BlackBerry device.

The .class files are zipped into the .cod file of the BlackBerry application project and installed on the BlackBerry Smartphone Simulator or on a BlackBerry device.

Run a MIDlet application in the BlackBerry Smartphone Simulator

You must have a .jad and .jar file pair to add to the BlackBerry application project.

You can import a MIDlet .jar file into a BlackBerry application project and run the MIDlet application in the BlackBerry Smartphone Simulator. You can import only one MIDlet .jar file into the BlackBerry application project. You must manually add any dependent library (.cod) files to the BlackBerry Smartphone Simulator.

  1. Create a new BlackBerry application project, and add the .jad and .jar files to the project.

    Do not place the files in a source folder.

  2. In the Package Explorer view, right-click the BlackBerry application project.
  3. Click Properties.
  4. Click Java Build Path.
  5. On the Libraries tab, click Add JARs or Add External JARs.
  6. Navigate to the MIDlet .jar file that you want to add and click Open.
  7. On the Order and Export tab, select the MIDlet .jar file and click OK.
  8. Package the BlackBerry application project and run the application in the BlackBerry Smartphone Simulator.

    The .class files are zipped into the .cod file of the BlackBerry application project and added to the BlackBerry Smartphone Simulator.

Hot-swap a BlackBerry device application

You must install the BlackBerry Java SDK 5.0 or later on your computer.

  1. In Eclipse right-click a BlackBerry application project.
  2. Click BlackBerry > Load Project on Device.
  3. Complete one of the following tasks:
    • Click Run As > BlackBerry Simulator.
    • Click Debug As > BlackBerry Simulator.
  4. In the BlackBerry Smartphone Simulator, click the icon to run the application.
  5. In Eclipse, make changes to the application that is running. Save the changes.
  6. Complete one of the following tasks:
    • Right-click the BlackBerry application project, and click BlackBerry > Load Project on Device.
    • On the Run menu, click Run As > BlackBerry Simulator.
    • On the Run menu, click Debug As > BlackBerry Simulator.

The changes to the BlackBerry device application appear in the BlackBerry Smartphone Simulator.

Restore the default settings for the BlackBerry Smartphone Simulator

  1. On the BlackBerry menu, click Clean Simulator.
  2. Expand the BlackBerry JRE that you want to restore the default settings for.
  3. Select the appropriate check boxes.
  4. Click OK.

Set preferences for running an app in debug mode

  1. In Eclipse, on the Window menu, click Preferences.
  2. Expand BlackBerry Java Plug-in.
  3. Click Debug.
  4. In the Warning section, select the Prompt for missing debug files check box if you want to be notified about missing files.
  5. Click Apply.
  6. Click OK.

Set preferences for downloading missing debug files

  1. On the Window menu, click Preferences.
  2. Click BlackBerry Java Plug-in.
  3. In the Download debug files section, select one of the following options:
    • Prompt: To be notified about any missing debug files.
    • Yes: To automatically download any missing debug files without being prompted.
    • No: When you try to debug, you will be prompted with an error about missing core files.

Debug an app on a BlackBerry device

  1. Connect the BlackBerry device to your computer using a USB cable.
  2. Open the BlackBerry Desktop Software.
  3. Install the application on the BlackBerry device.
  4. In Eclipse, on the Run menu, click Debug Configurations.
  5. Right-click BlackBerry Device, and click New.
  6. In the Name field, type a name.
  7. Click the BlackBerry Device tab.
  8. In the BlackBerry Device configuration section, perform one of the following actions:
    • Select Attach to any connected to attach to any BlackBerry device that is connected.
    • Select Attach to specific device. Select a BlackBerry device from the Attach to BlackBerry Device drop-down list.
  9. Click Debug.
  10. If prompted, click Yes to download the debug files.

Load an app on a BlackBerry device

  1. Connect the BlackBerry device to the computer by using a USB cable. Note: Connect only one BlackBerry device at a time.
  2. In Package Explorer view, right-click a BlackBerry application project.
  3. Click BlackBerry > Load Project on Device.

Install or remove an app on a BlackBerry device from the command line

You can use a command line tool called Javaloader.exe to install and remove an app on a BlackBerry device by using a USB connection without using descriptor files or web pages. Javaloader.exe can be useful when you install or remove an app frequently during testing and development.

  1. Connect the BlackBerry device to the computer by using a USB cable.
  2. At a command prompt, navigate to the following folder: <...>\Eclipse\plugins\net.rim.ejde.componentpackx.x.x_x.x.x.x\components\bin, where x.x.x_x.x.x.x is the version number of a BlackBerry Java SDK.
  3. Type javaloader to view the syntax of the tool.