Qt for the BlackBerry PlayBook

At the keynote to the BlackBerry Developer Conference last week, two very interesting things were announced.  First, the BlackBerry PlayBook Native SDK is finally in public release (it had previously been in a semi-closed beta).  Second, RIM unveiled the Native Open Source Components Initiative on GitHub.  This GitHub site includes ports of many open source libraries to the PlayBook, including the Qt Framework!  The only real downside here is that all they've done so far is to push out the code.  No how-to documentation has been provided.  Therefore, I'm going to attempt to give a walkthrough for setting yourself up to use their Qt port for PlayBook development.



Before we begin, I'm going to make the following assumptions:

• You are using Linux (MacOSX is probably similar, Windows probably has more differences)
• You have a Git client installed
• You have installed the Native SDK in: /opt/RIM/bbndk
• You have already requested and installed code signing keys
• You have generated a debug token, and saved it in your home directory as "debugToken.bar"
• You have an actual PlayBook, on an IP address your computer can connect to, that is in development mode with the above debug token installed.

(I'm sorry if those are a lot of assumptions, but RIM's own documentation covers all of those steps and I'd rather not get sidetracked.)

Downloading and Building Qt

First, put the following line at the bottom of your .bashrc file:

source /opt/RIM/bbndk/bbndk-env.sh

(Seriously, just do it. If you don't, then I don't want to hear all sorts of complaining about how various commands can't be found during the build processes to follow. If you insist on not putting that in your .bashrc, then make sure you run it in every single new shell window you open before doing anything I'm about to discuss.)

Now, time to download and build Qt:

~/pbdev$ git clone https://github.com/blackberry/Qt.git
Cloning into Qt...
remote: Counting objects: 46226, done.
remote: Compressing objects: 100% (29220/29220), done.
remote: Total 46226 (delta 14755), reused 45939 (delta 14468)
Receiving objects: 100% (46226/46226), 158.41 MiB | 832 KiB/s, done.
Resolving deltas: 100% (14755/14755), done.
~/pbdev$ cd Qt
~/pbdev/Qt$ ./configure-qsk arm v7le
 .  .  .
Qt is now configured for building. Just run 'gmake'.
Once everything is built, you must run 'gmake install'.
Qt will be installed into /home/octo/pbdev/Qt/stage/nto/armle-v7/usr/lib/qt4

To reconfigure, run 'gmake confclean' and 'configure'.

~/pbdev/Qt$ make
 .  .  .
~/pbdev/Qt$ make install
 .  .  .

Your first Qt app

Yes, now I'm going to show you how to build/package/install a simple "hello world" application. Once you get past this point, its mostly normal Qt development.

This example application consists of the following files, which I'll describe in detail below:

File	Description
main.cpp	source code for the application
helloworld.pro	qmake project file
blackberry-tablet.xml	bar descriptor file
icon.png	80x80px icon
splashscreen.png	1024x600px splashscreen image

main.cpp

#include <QApplication>
#include <QPushButton>
#include <QWidget>

int main(int argc, char *argv[])
{
    QCoreApplication::addLibraryPath("app/native/lib");
    QApplication app(argc, argv);

    QWidget window;
    window.resize(1024, 600);

    QPushButton quit("Quit", &window);
    quit.setGeometry(422, 100, 180, 40);
    QObject::connect(&quit, SIGNAL(clicked()), &app, SLOT(quit()));

    window.show();
    return app.exec();
}

This is a pretty basic Qt sample application so far. The only unique part is the first line, where we are explicitly telling QCoreApplication to add a library path.  This is necessary to enable the application to find the QPA plugin that RIM provides as part of their Qt port.  What is important to note is that the path is relative to the directory the app will be executed from on the device.

helloworld.pro

QMAKE_LFLAGS += '-Wl,-rpath,\'./app/native/lib\''
LIBS += -lbbsupport

SOURCES += main.cpp

package.target = $${TARGET}.bar
package.depends = $$TARGET
package.commands = blackberry-nativepackager \
    -devMode -debugToken ~/debugToken.bar \
    -package $${TARGET}.bar -arg -platform -arg blackberry \
    blackberry-tablet.xml $$TARGET \
    -e icon.png res/icon.png \
    -e splashscreen.png res/splashscreen.png \
    -e $$[QT_INSTALL_LIBS]/libQtCore.so.4 lib/libQtCore.so.4 \
    -e $$[QT_INSTALL_LIBS]/libQtGui.so.4 lib/libQtGui.so.4 \
    -e $$[QT_INSTALL_LIBS]/libQtOpenGL.so.4 lib/libQtOpenGL.so.4 \
    -e $$[QT_INSTALL_LIBS]/libQtNetwork.so.4 lib/libQtNetwork.so.4 \
    -e $$[QT_INSTALL_LIBS]/libbbsupport.so.4 lib/libbbsupport.so.4 \
    -e $$[QT_INSTALL_PLUGINS]/platforms/libblackberry.so lib/platforms/libblackberry.so

QMAKE_EXTRA_TARGETS += package

This file does a lot of important things:

• Configures the linker to hard-code the path, relative to the directory the app will be executed from, where the Qt libraries will be installed
• Includes the "bbsupport" library, which allows the app to interface with the device in a Qt-friendly way
• Adds a special make target ("make helloworld.bar") that builds a BAR file with the following characteristics:
• Development-mode build, using a debug token
• Passes command-line arguments to use the "blackberry" QPA plugin
• Bundles all the resources and libraries our app may need

blackberry-tablet.xml

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<qnx xmlns="http://www.qnx.com/schemas/application/1.0">
    <id>org.demo.helloworld</id>
    <filename>helloworld</filename>
    <name>Hello PlayBook</name>
    <versionNumber>1.0.0</versionNumber>
    <description>Hello World Example Application</description>
    <copyright>2011</copyright>

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

    <publisher>Logicprobe.org</publisher>
    <permission system="true">run_native</permission>
    <category>core.games</category>
    <icon><image>res/icon.png</image></icon>
    <splashscreen>res/splashscreen.png</splashscreen>
</qnx>

The descriptor file is pretty standard for the PlayBook, and described in far greater detail within RIM's own documentation. The graphics are not provided here, but you can use any appropriately sized PNGs of your choosing. If you omit the splash screen, remember to remove it from the descriptor file as well.

Building and installing

~/pbdev/helloworld$ ../Qt/stage/nto/armle-v7/usr/lib/qt4/bin/qmake
~/pbdev/helloworld$ make
qcc  .  .  .
qcc  .  .  .
~/pbdev/helloworld$ make helloworld.bar
blackberry-nativepackager  .  .  .
Info: Package created: helloworld.bar
~/pbdev/helloworld$ blackberry-deploy -installApp -device 192.168.1.42 -password foobar helloworld.bar
Info: Sending request: Install
Info: Action: Install
Info: File size: 6646238
Info: Installing ...
Info: Processing 6646238 bytes
Info: Progress 0%...
Info: Progress 21%...
Info: Progress 97%...
actual_dname::org.demo.helloworld.testDev__helloworld32c52fe1
actual_id::testDev__helloworld32c52fe1
actual_version::1.0.0.0
result::success

And that's all there is to it! If the size of the BAR file bothers you, try experimenting around to see if you can get away with including a smaller subset of the Qt libraries or building Qt with fewer features. However, the bulk of that size is from QtCore and QtGui.