Packaging

Lean how to package an HTML5 application to be installed on to a QNX CAR system.

To package and compile your application, you must run the BlackBerry WebWorks Packager (BBWP), which is included with the BlackBerry 10 WebWorks SDK. The BlackBerry WebWorks Packager takes your application archive file or folder location, compiles it, packages it, and then creates the file needed for deployment.

When you compile an app by using the BlackBerry WebWorks SDK, all of your app's resources, including its start page (index.html), its configuration document file (config.xml), its launch icon (icon.png), and other resources, are used to create a .bar file. You can install the resulting .bar file on a device, such as the Panda device for your "Hello World" app.

When you compile an app, the BlackBerry WebWorks Packager performs the following actions:

  1. Validates the contents of the application's archive (.zip) file or the app's folder location.
  2. Creates an output target folder and cleans up any old files (if necessary).
  3. Creates a source target folder (if specified) and cleans up any old files (if necessary).
Note:

If your operating system is Windows 7 or Windows Vista, you may need to ensure that bbwp and Java are running with administrator access. Otherwise, these executables will not have access to run, and you will encounter errors when you try to build your app.

If you're using version control or Mac OS, any hidden files (a filename that begins with a dot) will cause the packaging tool to create a .bar file that will likely fail (silently) upon launch.

Make sure that your configuration document file (config.xml) entry point file (index.html) and JavaScript file for WebWorks (webworks.js) are located in the project root.

To package your "Hello World"app using WebWorks:
  1. Compress all of the files in your app into a zip archive, called HelloWorld.zip, with the index.html, config.xml, and a launch icon (icon.png) are at the root of the archive (not in a subdirectory).

    The contents of the HelloWorld directory are copied into the .zip archive.

    Note:

    Don't zip the HelloWorld directory folder; open the folder and zip the contents.

    When you create the zip archive, make sure that you don't include any hidden files that may have been generated, such as .git, .svn, and .DS_Store. For Linux, you can run zip with the option -x to exclude hidden files. For example, the following example will exclude all .svn files from the ZIP archive: 

    cd HelloWorld
zip -r HelloWorld.zip * -x '*.svn*'
  2. In a command terminal, you'll execute one of the following tools:
    • bbwp (Linux)
    • bbwp.bat (Windows)

    These files are found at the root of the WebWorks archive you downloaded earlier.

    For example:

    • # ~/path/BBWP-<version>/bbwp -d HelloWorld.zip (Linux)
    • C:\path\BBWP-<version>\bbwp.bat -d HelloWorld.zip (Windows)

    The -d is optional and it enables debug mode, which turns on the Web Inspector. For example, the following output is the typical result from this process: 

     ~/dev/BBWP-1.0.2.9/bbwp -d HelloWorld.zip 
      [INFO]    Populating application source
      [INFO]    Parsing config.xml
      [WARN]    Build ID set in config.xml [version], but signing key file was not found: author.p12
      [WARN]    Build ID set in config.xml [version], but no signing password was provided [-g]. Bar will be unsigned
      [INFO]    Generating output files
      [WARN]    Failed to find debug token
      [INFO]    Info: Package created: /home/mylocation/simulator/HelloWorld/HelloWorld.bar
      [WARN]    Failed to find debug token
      [INFO]    Info: Package created: /home/mylocation/device/HelloWorld/HelloWorld.bar
      [INFO]    BAR packaging complete

    At a command prompt, navigate to the installation folder for the BlackBerry 10 WebWorks SDK. For Windows: cd C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK <version>, and for Mac OS: cd "/Developer/SDKs/Research In Motion/BlackBerry 10 WebWorks SDK <version>".

    Note: Warnings related to signing keys are normal when packaging apps without signing certificates. After packaging, an installable BAR file is created and can be found at: path/HelloWorld/device/HelloWorld.bar.

    If you encounter any problems packaging your apps, please refer to the HTML5 WebWorks Developer site.

    After packaging, the generated HelloWorld.zip and HelloWorld.bar files for your app can be found at: device/HelloWorld/

Parent topic: Deploying "Hello World"