BlackBerry 10 Platform Guide

This guide shows how to set up your development environment to build and deploy Cordova apps for BlackBerry 10 devices. For previous versions of BlackBerry, you need to use a different set of command-line tools, described in BlackBerry Platform Guide.

Requirements

The development environment is available on Windows, Mac and Linux.

Developers should use the cordova utility in conjunction with the BlackBerry Native SDK. See The Command-Line Interface for information how to install cordova, add projects, then build and deploy for each platform.

Install the BlackBerry Native SDK

The BlackBerry Native SDK is available from developer.blackberry.com. Following installation, you need to add its command-line tools to your system path.

On Windows:

  • Go to My Computer → Properties → Advanced → Environment Variables.

  • Append the Native SDK's install directory to the PATH, for example:

    ;C:\bbndk\host_10_2_0_132\darwin\x86\usr\bin\

On Mac and Linux:

  • Edit the ~/.bash_profile file, adding a line such as the following, depending on where the Native SDK was installed:

    $ export PATH=${PATH}:/Applications/Momentics.app/host_10_2_0_15/darwin/x86/usr/bin/

  • Run the following to apply the change in the current session:

    $ source ~/.bash_profile

Set up for Signing

If you wish to test on a device or distribute apps through BlackBerry World, your system must be setup for code signing.

To obtain a signing key, go to the [BlackBerry Keys Order Form] (https://www.blackberry.com/SignedKeys/codesigning.html).

Select the first checkbox: "for BlackBerry10 apps developed using BlackBerry NDK" and then sign in or create a BBID.

Enter a password and click "Get Token" to download bbidtoken.csk. Save this file to the default location for your OS which will be displayed on the download page.

The final step is to generate a signing certificate:

$ blackberry-keytool -genkeypair -storepass <password> -author 'Your Name’

Create a Project

Use the cordova utility to set up a new project, as described in The Command-Line Interface. For example, in a source-code directory:

$ cordova create hello com.example.hello
$ cd hello
$ cordova platform add blackberry10
$ cordova build

Deploy to Emulator

If you wish to run a device emulator, download and install the BlackBerry 10 Simulator.

Before testing an app on either an emulator or a device, you need to enable development mode.

Launch the emulator image, then choose Settings from the home screen:

Navigate to the Security and Privacy → Development Mode section and enable the option:

Then, run the emulate command to view the app:

$ cordova emulate blackberry10 --devicepass <password>

Deploy to Device

To deploy to a device, make sure it is plugged into your computer and development mode is enabled.

Then, run the run command to view the app:

$ cordova run blackberry10 --devicepass <password>

If a debug token is not yet set up for the device, an error message prompts you to provide the password you defined when configuring your computer to sign applications.

$ cordova run blackberry10 --devicepass <password> --keystorepass <signing password>

Debugging with WebInspector

When debugging on the device or an emulator, you may run WebInspector remotely to view the application's internal state. A prompt displays the URL that allows you to connect to your app with a standard web browser. For more information, see Debugging using WebInspector.

Building a Release Version

By default, running the cordova build command creates an unsigned .bar package file suitable for testing on a device or simulator.

Use --release to create a release version suitable for distribution through BlackBerry World.

$ cordova build --release --keystorepass <signing password>

The --keystorepass option specifies the password you defined when configuring your computer to sign applications.

Deploy to Other Locations

The instructions above assume a device is plugged in via USB or a simulator is running on the local machine. It is also possible to deploy to other locations.

An additional set of command-line utilities are included when you set up the BlackBerry 10 platform for your project. The following command, in this case invoked from the project top-level directory, associates a target named emu with an IP address.

  • On Windows:

    $ platforms\blackberry10\cordova\target.bat add emu 192.168.2.24 -t simulator

  • On Mac/Linux:

    $ platforms/blackberry10/cordova/target add emu 192.168.2.24 -t simulator

Once the target is defined, you can provide it to the run command using --target:

$ cordova run blackberry10 --target=emu