Login procedures have been improved. Check this page for details.

Qt Even More Everywhere: PlayBooks, QNX Embedded and Beyond

Unofficial Qt ports to QNX have been around for a number of years. In addition to internal Trolltech/Nokia devs numerous partners touched the code (ICS, Digia, KDAB) Today you can run Qt 4.8 on your PlayBook or embedded QNX device (in beta quality with release versions soon to follow). The embedded QNX is already merged into Qt in the Qt project repo and has commercial support by Digia so that's not what we'll focus on here.

The most exciting recent news is that RIM has done a port for the BB10 operating system and it works today on the QNX-based PlayBook. The PlayBook is a great inexpensive hardware platform to show off Qt applications. We've tried it out and it works...with a few tricks. The tooling is not integrated into Qt Creator yet so you are stuck with command line tools. Deployment is not trivial as it requires debug tokens/certificates from RIM. This takes some time to get sideloading figured out but it's no more challenging than deploying to Symbian. Once you've got Qt built and sideloading figured out you can develop and deploy additional apps relatively easily.

Some final notes before you begin: We've cross-compiled Qt and run the tools on Ubuntu, ArchLinux and Mac successfully. We haven't tried the Windows version but it's said to work. The tools and platform themselves are also changing: there's a 1.x and a 2.x beta NDK, and there's also 1.x OS platform and 2.x PlayBook OS beta platform. We built Linux with 1.x and 2.x versions of NDK and OS and Mac with versions 2.x of each. No promises on what variations you might experience but give it a shot and let us know how it goes!

Qt 4.8 on PlayBook OS Version 2.x using NDK 2.x

Download and install BlackBerry Native Development Kit

1. Download from https://bdsc.webapps.blackberry.com/native/download/

2. Execute ./installer-bbndk-2.0.0-linux-7971-201202171813-201202181253.bin (or latest version)

Configure Host & Target

1. Request signing keys on BlackBerry website

2. Activate the development mode: Settings -> Security -> Development Mode -> On

3. Connect the PlayBook to Linux using:

• USB cable. On Playbook:
  Settings -> Storage & Sharing -> USB Connection: Connect to Mac

   $ sudo dhclient usb0

• WiFi.

Note: Device IP can be found by clicking on Development Mode icon on your Playbook. For USB, this will always be 169.254.0.1.

4. Create and deploy a debug-token (see also this link for more details)

   $ blackberry-debugtokenrequest -register -storepass <password> -csjpin <csj-pin> client-PBDT-<key-number>.csj
   $ blackberry-debugtokenrequest -storepass <password> -devicepin <device ID> debugtoken.bar
   $ blackberry-deploy -installDebugToken debugtoken.bar <device IP> -password <device password>

5. Connect via ssh to the PlayBook

   $ ssh-keygen -b 4096   (need to generate an RSA ssh key with 4096 bits) 
   $ blackberry-connect <device IP> -password <device password> -sshPublicKey id_rsa.pub
   $ ssh -i id_rsa devuser@<device IP> 

If your debug token expires, just request a new one:

   $ blackberry-debugtokenrequest -storepass <password> -devicepin <device ID> debugtoken.bar

Preparing the environment

To set up the environment, we need to source the bbndk-env.sh script. The script is responsible for putting required tools in the path and setting environment variables. This script needs to be sourced every time you open a new terminal. To avoid this, it is suggested you place the line in your ~/.bashrc file pointing to the location where you installed BBNDK.

   $ source $BBDNK/bbndk-env.sh

Getting and building Qt 4.8

$ git clone git://gitorious.org/qt/qt.git

NOTE: we suggest you to start with a clean source tree before building for a different architecture (ARM/x86).

Building Qt 4.8 for ARM (PlayBook)

$ cd qt
$ ./configure -opensource -confirm-license -qpa -iconv -shared -release -xplatform unsupported/blackberry-armv7le-qcc \ 
    -little-endian -arch arm -largefile -nomake examples -xmlpatterns -no-webkit -no-neon -no-rpath -opengl es2
$ make
$ make install

Building Qt 4.8 for x86 (Simulator)

$ cd qt
$ ./configure -opensource -confirm-license -qpa -iconv -shared -release -xplatform unsupported/blackberry-x86-qcc \ 
    -little-endian -arch i386 -largefile -nomake examples -nomake demos -no-neon -xmlpatterns -no-webkit \
    -no-rpath -opengl es2
$ make
$ make install

Qt will be installed at $PWD/stage. Alternatively, you can then use -prefix-install and pass a directory to the -prefix option to change the installation directory.

A Hello World using the NDK CLI tools

Introduction

From now on, the Qt installation directory will be referred to as simply $QTDIR. The BlackBerry NDK 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

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

   $ cp $QT_DIR/lib/*.so.4 deploy/lib
   $ cp $QT_DIR/plugins/platforms/libblackberry.so deploy/plugins/platforms

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 $QT_DIR/bin:

   $ 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 creating 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 xmlns="http://www.qnx.com/schemas/application/1.0">
    <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>blackberry</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>
    <icon><image>icon.png</image></icon>
    <splashscreen>splashscreen.png</splashscreen>
</qnx>

For a full description of the bar file descriptor structure, see the Document Type Definition

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 tokens set up and residing under ~/.rim directory:

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

Deploying and running

All we have to do is sending 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.