Packaging and deploying apps

You can use the Momentics IDE for BlackBerry or the command line tools provided with the BlackBerry 10 Native SDK to package and run your app.

When you package an app, you create a .bar file. The .bar file is built using information from the BAR application descriptor 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.

Running your app

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 has no correlation to Development Mode on the device.
Run Release mode
Run release mode mimics the installation environment that users have when they get the application from BlackBerry World. For example, in release mode there are more restricted file system permissions. If your application uses a file that is available only in debug mode, then the application will not work when users download it from BlackBerry World.

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

Feature or Tool Development mode Run Release mode
Packaging The app is packaged with -devMode flag. The app is not packaged with -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.
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.
Application assets Read/write permission for devuser. Read-only permission for the app owner. No read permission for any other user.
Sandbox Read/write permission for devuser and app. Read/write permission for only the app. No tools can access the app, including the debugging tool.
Navigator No timeouts. No stopped processor. No pooling. Timeout on startup and shutdown. Stopped processor. Pooling support.
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 Test and debug.

To specify the run mode:

  1. On the toolbar, select the 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, expand the BAR Packages folder, and then open the Device-Release BAR file.
  4. In the BAR file, click Install.
  5. Test the app.

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\Research In Motion.
  • 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 use to communicate with the BlackBerry Signing Authority.

-proxyusername

user name

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

-proxypassword

password

The password to use when your proxy server requires authentication.

There are several command line tools you'll need to prepare your device for development, create and upload a debug token, and then package and deploy your app:
blackberry-debugtokenrequest
Creates debug tokens on your computer.
blackberry-deploy
Deploys applications (.bar files) to a device. Use this command to deploy a debug token as a .bar file.
blackberry-nativepackager
Packages your 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 command line tools, run the tool from the command line with no options.

Register your BlackBerry ID token from the command line

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

To register your BlackBerry ID token:
  1. Run the following blackberry-signer tool where:
    • <password> is a password that you specify for the keystore.
    • <bbidtoken.csk> is the pathname to the app signing .csk file 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 from 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. Change directory to where you installed the Momentics IDE.
  2. Run the following blackberry-debugtokenrequest tool where:
    • <csk_password> is the password for the keystore that you used when you registered.
    • <pathname_p12> is the pathname 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 following blackberry-deploy tool where:
    • <project.bar> is the .bar file for your project.
    • <yourDeviceIP> is the IP address of your device.
    • <yourDevPassword> is the password for your device.
    blackberry-deploy -installDebugToken <project.bar> 
                      -device <yourDeviceIP> 
                      -password <yourDevPassword>

Package and deploy your app from the command line

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

To package your app onto your device:
  1. Change directory to where your project and code are located.
  2. Run the following blackberry-nativepackager tool where:
    • <native-sample> is the name of your app.
    • <Device-Debug> 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 onto your device:
  1. Run the following blackberry-deploy tool where:
    • <IPnumber> 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 <IPnumber> 
                               -password <password> <package_bar_file>

You can deploy to more than one device using blackberry-debugtokenrequest. 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>

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 application is packaged and deployed on the target.
  1. Deselect 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 will be 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 application, then re-installs the BAR file on the target.
    Don't upload files, use application from target
    Launches the application on the target. You must have successfully deployed the application at least once in order to use this option.
    Only upload binary into existing application
    Installs only the binaries into the application folder on the target. You must have successfully deployed the application at least once in order to use this option.
    Only upload binary and libraries into existing application
    Installs the binaries and any libraries into the application folder on the target. You must have successfully deployed the application at least once in order to use this option.
  3. Click Apply to save any changes.

Last modified: 2014-06-24



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

comments powered by Disqus