A-HelloWorld-using-the-BlackBerry-NDK-CLI-tools

Using the BlackBerry PlayBook NDK command line tools - a "Hello Wold" example.

Please note that the below steps are generally valid for BlackBerry 10 as well, but are very different in details.

Introduction

This article assumes that you already have set your development environment. We will refer to the folder where Qt for BlackBerry 10 is installed $QTDIR. The BlackBerry NDK installation directory will be called $BBNDK_

Setting up the project directory

First, the directory where our HelloWorld application will reside needs to be created. We will also create a subdirectory called deploy. That is where we will place our Qt libs, splash screen and application icon.

 mkdir -p helloworld/deploy/lib
 cd helloworld/
 mkdir -p deploy/plugins/platforms
 mkdir -p deploy/imports

We will now copy the Qt libs to the deploy/lib directory:

 cp $QTDIR/lib/*.so.4 deploy/lib
 cp $QTDIR/plugins/platforms/libqqnx.so deploy/plugins/platforms
 Linux
 cp -R $QTDIR/import/* /deploy/imports
 # MacOS
 ditto $QTDIR/imports/ deploy/imports

Icon and splash screen

Our application icon must be 86-by-86 pixels . Any icon larger than that will not be displayed on the screen. Both PNG and JPG image formats are supported. We will also need a splash screen for our application. This is the image the Playbook will display while our application is being loaded. It will be displayed in landscape orientation. There is also the possibility of specifying two images, one for landscape and the other for portrait orientation. Just like the icon, the splash screen image can be either a PNG or a JPG file, with a size of 1024x600 pixels (on landscape orientation), the PlayBook screen resolution. We should also place them inside our deploy directory:

 cp icon.png splashcreen.png deploy/

The source code

#include <QApplication>
#include <QPushButton>

int main(int argc, char *argv[])
{
 QApplication app(argc, argv);

QPushButton button("Hello Playbook World!");

QObject::connect(&button, SIGNAL (clicked()), &app, SLOT (quit()));

button.show();

return app.exec();
}

Building

Building a Qt application for the Playbook is no different from building a desktop Qt application.

First, we ask qmake to create a .pro file for our project. Make sure you are calling the right version of qmake, the one residing inside

$QTDIR/bin<code>:
 <code> qmake -project

Now we generate the Makefile:

 qmake 

And simply call make:

 make

Packaging

Now we are almost there. In order to deploy our helloworld application to the Playbook, we need to package it. Playbook's package file format is referred to as "bar files". A bar file is nothing but a zip archive with an arbitrary directory structure and embedded meta-information . Luckily, we do not have to manually create this archive, for the BlackBerry NDK provides us with tools to do this. To package, we will use the blackberry-nativepackager command line utility. The first thing we need to do is create a bar file descriptor.

The BAR file descriptor

The BAR file descriptor is an XML file that contains the information needed by blackberry-nativepackager to generate a bar file. Here is how our looks like:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<qnx >
 <id>org.demo.helloworld</id>
 <name>Qt Hello World</name>
 <versionNumber>1.0.0</versionNumber>
 <description>A simple Hello World demo application</description>

<initialWindow>
 <systemChrome>none</systemChrome>
 <transparent>false</transparent>
 <autoOrients>true</autoOrients>
 <aspectRatio>landscape</aspectRatio>
 </initialWindow>

<env var="QML_IMPORT_PATH" value="app/native/imports"/>
 <env var="QT_PLUGIN_PATH" value="app/native/plugins"/>
 <env var="LD_LIBRARY_PATH" value="app/native/lib"/>

<arg>-platform</arg>
 <arg>qnx</arg>
 <author>KDAB</author>
 <authorId>gYAAgOFP83zwpwdTrWwjCuLaPac</authorId>
 <action system="true">run_native</action>
 <category>core.games</category>
 <asset entry="true" path="helloworld" type="Qnx/Elf">helloworld</asset>
 <asset path="deploy/splashscreen.png">splashscreen.png</asset>
 <asset path="deploy/icon.png">icon.png</asset>
 <asset path="deploy/lib">lib</asset>
 <asset path="deploy/plugins">plugins</asset>
 <asset path="deploy/imports">imports</asset>
 <icon><image>icon.png</image></icon>
 <splashscreen>splashscreen.png</splashscreen>
</qnx>

Make sure you change the elements asset path if the paths in your application are different than here as well as the author and authorID elements for later publishing.

Generating the BAR package

Now that we have created the bar-descriptor.xml file, and have created our bar file, we are ready to generate the actual bar file package. This assumes we already have the debug token set up and residing in ~/.rim

 blackberry-nativepackager -devMode -debugToken~/.rim/debugtoken1.bar -package helloworld.bar bar-descriptor.xml

Deploying and running

All we have to do is send our bar file to the Playbook using the blackberry-deploy utility:

 blackberry-deploy -installApp -device <device ip address> -password <device password> helloworld.bar

After the operation is completed, there should be a new icon on your PlayBook dashboard pointing to our HelloWorld application.

The console output of the application is saved in the /accounts/1000/appdata/*APPNAME*/logs/log file on the device.