Package and deploy your app

To package and run your app, you can use the Momentics IDE for BlackBerry or the command-line tools that are provided with the BlackBerry 10 Native SDK.

When you package an app, you create a .bar file. The .bar file is built using information from the bar-descriptor.xml file and the compiled binaries from the project or code base. You can run your app after you deploy the .bar file to a device or simulator.

Choose a deployment mode

You can run your app in development mode or in release mode:

Development mode
In development mode, the package is defined during packaging and cannot be changed later. The only way to change the package is to uninstall the app. This development mode isn't related to Development Mode on the device.
Run release mode
Run release mode mimics the installation environment that users have when they get the app from BlackBerry World. For example, in release mode, there are more restricted file system permissions. If your app uses a file that is available only in debug mode, then the app will not work when users download it from the BlackBerry World storefront.

The following table shows how features and tools behave differently in development mode and run release mode:

Feature or tool Development mode Run release mode
Packaging The app is packaged with the -devMode flag. The app is not packaged with the -devMode flag.
Signing The app cannot be signed. The app must be signed.
Package ID The default package ID starts with testDev (unless you specify the static ID that the signing tool assigned). The package ID is assigned by the Signing Authority service.
User ID (UID) and group ID (GID) UID=100

GID=900-999 (A maximum of 100 development apps are allowed.)

The UID and GID are unique for each app.
Assets Read-write permission is given to devuser. Read-only permission is given to the app owner. No read permission is given to any other user.
Sandbox Read-write permission is given to devuser and app. Read/write permission is given to only the app. No tools can access the app, including the debugging tool.
Navigator No timeouts. No stopped processor. No pooling. There is a timeout on startup and shutdown. The processor can be stopped. Pooling is supported.
Running, debugging, or testing When you run or debug an app, the IDE packages the app in development mode, even if you select the Device-Release configuration. You cannot debug the app.

For information about testing the app, see Debugging a C/C++ app.

To specify the deployment mode:

  1. On the toolbar, in the Launch configuration drop-down list, select a launch configuration.
  2. In the Launch mode drop-down list, select Run or Run Release.
  3. In the Launch target drop-down list, select a device or simulator.

Create a release build

To test your app in release mode, export the release build, install the .bar file package, and then test the app.

  1. On the File menu, click Export > BlackBerry > Release Build.
  2. Click Next, and then follow the instructions in the wizard.
  3. In the Project Explorer view, expand the BAR Packages folder, and then open the Device-Release .bar file.
  4. In the .bar file, click Install.
  5. Test the app.

Configure packaging options

You can use the configuration settings on the Upload tab to define both the name of the folder that will contain the .bar file and the way that your app is packaged and deployed on the target.

  1. Clear the Use default folder for BAR package check box, then click Browse and browse to the folder that will contain the .bar file.
  2. In the Deployment section, select a deployment option.
    The deployment options define how the .bar file is uploaded and deployed on the target. The following options are available:
    Install application from a BAR file
    Installs the .bar file on the target. This is the default deployment option.
    Uninstall, then install application from a BAR file (clean install)
    Uninstalls previous versions of the app, then re-installs the .bar file on the target.
    Don't upload files, use application from target
    Launches the app on the target. To use this option, you must have deployed the app successfully at least once.
    Only upload binary into existing application
    Installs only the binaries into the app folder on the target. To use this option, you must have deployed the app successfully at least once.
    Only upload binary and libraries into existing application
    Installs the binaries and any libraries into the app folder on the target. To use this option, you must have deployed the app successfully at least once.
  3. Click Apply.

Package and run using the command line

You can package and run your app outside of the Momentics IDE by using command-line tools.

Before you can package and run your app using the command line, there are a few things you need to do:

  • Determine the location of your APPDATA environment variable. In Windows, you can enter echo %APPDATA% at a command prompt. The location should be similar to C:\Users\<username>\AppData\Local\BlackBerry.
  • Create a BlackBerry ID token.
  • Set Development Mode on your device to On.
  • Connect your device to your computer or start your simulator.

For details, see Set up your environment.

If you connect to the Internet through a proxy server, append the following additional options to the blackberry-keytool commands.

Option Description

-proxyhost <host>

The network host that provides the proxy service. The host parameter can be an IP address or a fully-qualified domain name.

-proxyport <port>

The port number that the blackberry-signer and blackberry-debugtokenrequest tools use to communicate with the Signing Authority Service.

-proxyusername

<user_name>

The user name to use when the proxy server requires authentication.

-proxypassword

<password>

The password to use when the proxy server requires authentication.

There are several command-line tools that you need to prepare your device for development, create and upload a debug token, and package and deploy your app:

blackberry-debugtokenrequest
Creates debug tokens on your computer.
blackberry-deploy
Deploys apps (.bar files) to a device. Use this command to deploy a debug token as a .bar file.
blackberry-nativepackager
Packages the compiled binaries for your app as a .bar file.
blackberry-signer
Digitally signs your app, which is necessary before you publish and distribute your app. You can also use this command to authenticate your BlackBerry ID token.

You can find these tools in the usr/bin subfolder where you installed the BlackBerry 10 Native SDK. To make it easier to run the tools, add the path to the usr/bin subfolder where you installed the Native SDK to the PATH environment variable for your operating system.

For more information about a command-line tool, run the tool from the command line with no options.

Register your BlackBerry ID token using the command line

You need to register with the Signing Authority Service using the BlackBerry ID token for app signing by using the blackberry-signer tool. You need to register your signing token once.

To register your BlackBerry ID token:

  • At the command prompt, run the blackberry-signer tool with the following options:
    • <password> is a password that you specify for the keystore.
    • <bbidtoken.csk> is the path name to the app signing .csk file that you downloaded when you created your BlackBerry ID token.
blackberry-signer -storepass <password>
                <bbidtoken.csk>
After you register using the blackberry-signer tool, the following files are created in the AppData folder:
  • author.p12
  • barsigner.csk
  • barsigner.db

The message "Successfully registered with the server" is displayed and an email is sent to you. It is a good idea to back up your signing token.

Create and upload a debug token using the command line

If you are working with a device and not the simulator, you need to add a debug token to your device to run an unsigned app.

To create and upload a debug token:

  1. At the command prompt, change directory to where you installed the Momentics IDE.
  2. Run the blackberry-debugtokenrequest tool with the following options:
    • <csk_password> is the password for the keystore that you used when you registered.
    • <pathname_p12> is the path name to the .p12 file.
    • <device_pin> is the hex value of the PIN for your device. Add the prefix 0x. To find the PIN of a device, open the Settings app on your device, tap About, and then select Hardware in the Category drop-down list. Record the value from the PIN field.
    • <password> is the password for the keystore that you used when you registered.
    • <project.bar> is the .bar file for your project.
    blackberry-debugtokenrequest -cskpass <csk_password>  
                                 -keystore <pathname_p12>  
                                 -deviceID <device_pin> 
                                 -storepass <password> <project.bar>  
  3. Run the blackberry-deploy tool with the following options:
    • <project.bar> is the .bar file for your project.
    • <device_ip> is the IP address of your device.
    • <device_password> is the password for your device.
    blackberry-deploy -installDebugToken <project.bar> 
                      -device <device_ip> 
                      -password <device_password>

Package and deploy your app using the command line

Before you package and deploy your app, make sure that you have compiled your code as binaries.

To package your app:

  1. At the command prompt, change directory to where your project and code are located.
  2. Run the blackberry-nativepackager tool with the following options:
    • <native_sample> is the name of your app.
    • <build_config> is the build configuration.
       blackberry-nativepackager -package <native_sample.bar> bar-descriptor.xml 
                                 -configuration <Device-Debug> 

    You can change the build configuration from Device-Release or Device-Debug (a BlackBerry device) to Simulator to run your app on a simulator.

To deploy your app on your device:

  1. Run the blackberry-deploy tool with the following options:
    • <device_ip> is the IP address of your device.
    • <password> is the password for your device.
    • <package_bar_file> is the name of the .bar file that was created during the packaging process.
    blackberry-deploy -installApp -launchApp -device <device_ip> 
                               -password <password> <package_bar_file>

You can deploy your app to more than one device using the blackberry-debugtokenrequest tool. For example, you can run the following command:

blackberry-debugtokenrequest -storepass <KeystorePassword> 
-devicepin <PIN device 1> -devicepin <PIN device 2> 
-devicepin <PIN device n> <debug_token_file_name.bar>

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus