Qt Creator with BlackBerry 10

[toc align_right="yes" depth="2"]

Using Qt Creator for BlackBerry 10 Development

Overview

Qt is one of the application development frameworks available on the BlackBerry 10 platform. Using Qt, you can deploy your Qt C++ or Qt Quick application to BlackBerry 10 devices. The current release of the BlackBerry 10 Gold NDK includes Qt 4.8 for both the simulator target (x86) and device targets (arm) available for development. Compared to the development for the PlayBook, Qt is integrated in the BlackBerry 10 device firmware and so can be used by Qt applications as shared libraries.

This page explains how to use QtCreator 3.0 with the BlackBerry 10 NDK

Note: The NDK is in continuous development. We will update this page from time to time to cover new releases of the NDK and QtCreator. The following steps were tested using Ubuntu 12.04 LTS 32-bit but should work in a similar way on Windows and Mac OS X.

Note: If you are using Qt Creator 3.2, you won't be able to run and debug your application on the device. This is an known issue that will be fixed in the next releases.

Getting Started

The following tools are required for development for the BlackBerry 10 platform using QtCreator:

• Momentics IDE
• BlackBerry 10 API Level
• QtCreator 3.0
• BlackBerry 10 device or simulator

See complete article Setup for BlackBerry10 development

QtCreator 3.0

QtCreator 3.0 can be downloaded:

• from Official Downloads
• from Official Development Releases Downloads
• from Daily Snapshot Builds of QtCreator
• cloned and built from QtCreator Source Code

Note: QtCreator 3.0 Beta identifies itself as QtCreator 2.8.82 (pre-3.0.0).

Note: BlackBerry 10 support in QtCreator 3.0 is provided by "Qnx" plugin. This plugin should be enabled by default.

Configuring QtCreator

QtCreator 3.0 brings new features for BlackBerry 10 support that enables you to easily create, build, deploy, run and debug your application directly from the IDE.

Here are new features that BlackBerry 10 plugin provides in QtCreator 3.0:

• Support for using multiple BB NDK API Levels
• Automatic detection of installed BB NDK API Levels
• Improved Device wizard
• Updated BlackBerry Signing Keys options page, creation of Developer Certificate and Debug Token
• Easy setup of your BlackBerry 10 development environment (Kits, Qt Version, Compiler, …)
• UI editor for bar-descriptor.xml files

Configuring API Level

QtCreator 3.0 has built-in automatic detection of installed BlackBerry 10 API Levels. You can look open "Tools -> Options…-> BlackBerry -> NDK" page (on MacOSX: "Preferences-> BlackBerry -> NDK") to see the listing.

If your API Level is not listed under 'Auto-Detected' category, you can add it by clicking on "Add" button and browsing for the "bbndk-env.sh/bat" that represent your API Level.

For each API Level listed in the "BlackBerry-> NDK" options page, there are the following settings pre-configured:

• one QtVersion for HOST/OS/ARCH/usr/bin/qmake - represents Qt4 qmake
• one Kit for Qt4 on Device
• one Kit for Qt4 on Simulator

Qt5 is not available built-in on 10.2 device firmware. When available, additional QtVersion and two Kits are going to be created for that Qt5 too.

Note: If you are having many API Levels installed but not using them you can selected appropriate API Level in the listing and press "Deactivate" button. Then related QtVersions and Kits are removed. All Active API Levels are display with bold font in the listing.

Configuring Signing Keys

Note: Make sure that you have BlackBerry 10 API Level version 10.2 or newer installed on your host machine. This is a prerequisite for proper work of Signing Keys configuration. See "BlackBerry 10 API Level" section for information how to install it.

Open "Tools -> Options…-> BlackBerry -> Keys" page (on MacOSX: "Preferences-> BlackBerry -> Keys") to configure keys. It should state, that you have have your keys ready to be used.

Note: if it prints "No keys found." message when you need to obtain BlackBerry Signing Keys as described above.

Click on "Create certificate" button to create one. Fill your Author (any name) and password and press OK button. Now your "Keys" page should display details about your "Developer Certificate".

Configuring Qt Creator for the Qt5 Overlay

When installing the Qt5 Overlay, Qt Creator might not be aware of any changes and won't immediately generate kits for the Overlay Qt5 version. That's because Qt Creator (version 3.0 and higher) should have detected the installed API Levels, and generated kits for the active API level. In order to force Qt Creator to generate the new kits for Qt5 Overlay version, you need to deactivate and activate the "BlackBerry Native SDK 10.2" API level again after you have installed the Overlay.

If you only have one unique "BlackBerry Native SDK 10.2" API Level, you won't be able to deactivate it with Qt Creator 3.0, since it needs to keep at least one API level activated for other features that depend on it. To work around this, you need to install a new API Level (i.e target) and activate it, before you are able to deactivate/activate the "BlackBerry Native SDK 10.2" API Level.

Due to a known Qt mkspec issue in QtCreator 3.0 , please make to use a correct Qt mkspec when building your project, as described in the next section.

Note:: The upcoming Qt Creator 3.1 doesn't require any API level to be active, and should provide new button to refresh your existing API levels to detect any new changes.

Mkspec known issue:

Due to some changes in the Qt mkspec targeting armlev7 architrecture, QtCreator 3.0 will use a wrong mkspec when building your project. In order to workaround this, you need to explicitly set the mkspec in your BlackBerry Kits targeting the device as follow:

• For BlackBerry kits using Qt5 version: blackberry-armle-v7-qcc
• For BlackBerry kits using Qt4 version: blackberry-armv7le-qcc

The Qt mkspec entry for the generated kits that are targeting the simulator should be always set to "blackberry-x86-qcc" regardless which Qt version is used.

Note:: This issue should be fixed in the upcomming QtCreator 3.1 release.

h3. Adding Device or Simulator

Go to "Tools-> Options -> Devices-> Add -> Blackberry Device" (on Mac: "Preferences-> Devices -> Add-> Blackberry Device") to add a BlackBerry Device. It opens a BlackBerry Device wizard that allows to add either a physical device or a simulator.

• On the first page, select an auto-detected device and enter device password. If device is not auto-detected, choose "Specify Manually" item and enter IP address too. Device password is required for connecting to physical devices only
• On the second page, the device is query and SSH connection keys are generated (stored at "~/.config/QtProject/qtcreator/qnx/id_rsa" file)
• On the third page, you can specify the configuration name and debug-token (locate an existing one or click on "Generate" button to generate new one) - see the next section for more information.

Note: Press "Apply" in the "Options" dialog to store the changes otherwise the other Options pages will not notice your new device.

Connecting to Device

QtCreator automatically tries to connect to a device when:

• Run an application with BlackBerry kit
• Press "Apply" button in the "Options" dialog to store newly added device

When a device is connected, QtCreator starts working with the device e.g. running a project.

Troubleshooting

If you see the following line in the connection log:

Info: Connecting to target 169.254.0.1:4455
Error: Connection failed: connect timed out

then it means that QtCreator cannot connect to a device.

Check if the device:

• is switched to Development Mode
• has correct platform set for "Settings -> Storage-> Usb connection". Use "Connect to Windows" for Linux.
• is NOT connected by any "blackberry-connect" command-line tool already.
• is NOT connected already in Momentics IDE.

If the device was connected by "blackberry-connect" or Momentics IDE then:

• stop the tool
• unplug the device from USB
• wait for 15 seconds
• plugin the device to USB
• Connect to the device from QtCreator

For details, see issue QTCREATOR-10910.

Generate and Upload Debug Token

To be able to deploy an application to your physical device, you need to have a valid Debug Token on your physical device and use the same Debug Token for creating your BlackBerry aplication.

When you are adding a new BlackBerry 10 device to QtCreator you need to:

• specify an existing file with a debug token generated for your device
• generate a new debug token for your device

Similarly when you have your BlackBerry 10 device already added in QtCreator, you can go to "Tools -> Options-> Devices -> Select your device" (on Mac: "Preferences-> Devices -> Select your device") to see details about your device. The "Type Specific" section offers you to:

• specify an existing file with a debug token generated for your device
• request a new debug token for your device
• upload the debug token to your device

To create a new debug token click on "Generate" or "Request" button to open a "Request Debug Token" dialog.

There specify:

• a path for file that will hold the debug token for your device
• device PIN- this should be automatically retrieved if your device is attached to your host machine

When you press OK, the new debug token file is created and assigned to your device configuration.

Note: that you need to press Apply to make those changes been applied to QtCreator settings.

In case you have created a new debug token, you need to upload it to your device too so QtCreator and BlackBerry 10 device are using the same debug token. Press "Upload" button in "Type Specific" section of the device configuration. You should see configuration dialog, when the debug token is successfully uploaded.

Assigning Device to Kit

• Go to "Tools -> Options-> Build & Run -> Kits" (on Mac: "Preferences-> Build & Run -> Kits") to list available kits
• Select a kit that you would like to work with
• Make sure that your kit is having Device Type field set to "Blackberry Device"
• Select your device in the "Device" field
• Make sure that your "Qt mkspec" field is set correctly (for physical devices, use "" or "blackberry-armv7le-qcc"; for simulator, use "blackberry-x86-qcc")

Note: similarly to "Devices" page, if you make any change in "QtVersion" tab press Apply button to store the changes otherwise other pages will not notice your changes.

Creating BlackBerry 10 Application

There are several project templates that can be used for creating BlackBerry 10 project. You can access it via access the wizard via "File-> New File or Project…" main menu.

In the "New" wizard, the "Applications" category contains the following project templates that allows creating applications for BlackBerry 10 device:

• Qt Quick Application
• Qt Widgets Application
• Qt Console Application
• BlackBerry Cascades Application

Note: if you are unable to see "BlackBerry" project template, select "All Templates" in the top-right corner of the dialog.

Qt Quick Application

This template is generic for Qt Quick applications for any platform. They can be used even for BlackBerry devices.

You need to select to use a BlackBerry kit - either in the project wizard itself or add BlackBerry kit to the project any time later. When you do so, IDE asks you whether you want to generate BAR Descriptor.

Answer "Yes" to bar-descriptor.xml is created in your project and added into "OTHER_FILES".

Note: The bar-descriptor.xml file is created just once only and when you are assigning a BlackBerry kit to a Qt4/5 project. This way use can take any existing QtQuick 1/2 project and all deployment to BlackBerry 10 devices just by assigning a BlackBerry kit to your project.

Note: The template allows you to choose Qt Quick Component Set as "Qt Quick 1.0", "Qt Quick 2" or "Qt Quick Controls 1.0". "Qt Quick 2" and "Qt Quick Controls 1.0" requires Qt5 runtime which is not available on BlackBerry 10 devices including 10.2 version.

Qt Widgets Application

The "Qt Widgets Application" project template provides an application that is using QtGui and QtWidgets library. if you choose to use any BlackBerry kit, you will be asked whether bar descriptor file should generated. Then the application can be deployed and launched on BlackBerry device the same as for QtQuick applications.

Qt Console Application

Using this project template is similar to "Qt Widgets Application" project template.

BlackBerry Cascades Application

This project template create a project with a preset main.qml to use Cascades UI.

Note: Cascades UI FW is available in Qt4 runtime on BlackBerry devices and simulators only.

Deploying Qt Applications

BlackBerry 10 devices are having Qt4 runtime automatically available for you in "/usr/lib/qt4" folder. The project-templates and bar-descriptor.xml generated by QtCreator are using this Qt4 runtime.

BlackBerry 10 devices are NOT shipped with built-in Qt5 libraries and therefore you need to supply them manually.

See Qt on BlackBerry devices page for more details.

bar-descriptor.xml File

The "bar-descriptor.xml" file specifies the parameters for identifying, installing, and launching native applications on BlackBerry 10. It contains mainly information about the application author, id, icons and other properties and is used to create the BAR file or BAR package. A BAR package is a installation package of an application for the BlackBerry 10 platform. "BAR" stands for " B lackberry A pplication a R chive". For more details please refer to bar descriptor file documentation

QtCreator provides a UI editor for editing your bar-descriptor.xml and manage your application's behavior and appearance.

The Bar Descriptor editor has 4 tabs:

• General - edits name, descriptor, icon, splash screens, package information, author information
• Application - edits orientation, chome, application arguments, permissions, environment
• Assets - edits a list of assets that are packaged into your application
• XML Source - edits the bar-descriptor.xml using text editor

Note: a newly created project has the bar descriptor file listed as a bar-descriptor.xml file under "Other files". This file will be used by QtCreator to generate a final bar-descriptor.xml in the build directory to package your application. For example "SRC_DIR" is replaced with your project directory path.

If you run the application now, QtCreator will create the bar package, connect to the device or simulator and launch your application. You can also do these steps using commands in a shell, see the next section for more details.

For performance reasons, the log output from qWarning, qDebug, etc is captured by the "slog2" logging system on BlackBerry 10 instead of plain text files in the file system. All these messages will appear unfiltered in the "Application Output" view.

If you want to use command-line to package and deploy your application, see the following page:

• Command-line Tools
• Packaging and Deploying

Import Momentics Cascades Project

If you are having an existing Cascades project that has been created using QNX Momentics IDE, then such a project cannot be directly used in QtCreator. Instead you need to import such a project into QtCreator:

• Go to "File -> New File or Project…"
• Select "All Templates" in the "Choose Template:" combobox in the top-right conner of the wizard
• Select "Import Project" in category listing
• Select "Momentics Cascades Project" in the project listing

• In the next page of the wizard, specify a folder that contains .pro file of your Momentics Cascades project
• In the next page, specify the new name and location of your new project
• Press Finish

Your Momentics Cascades project is going to be read and a new QMake-based project is going to be created at a specified location. Note that the new project is a converted copy of your original project. The original project is not modified by the Import wizard.

When the project import finishes, "import.log" is created next to your .pro file of your application. The log file contain information about the importing process.

UI Adaptability

Note that QtCreator does not understand "UI Adaptability" concept used in BlackBerry applications. Still your imported project will contains all (QML, images, resources) files- even those that are stored in the non-default selector folders.

QtCreator will be unable to correctly resolve references to other QML files that are relative due to UI Adaptability.

Still when you run such an project in a BlackBerry 10 device or simulator, UI Adaptability will work in your application.

Zygote Applications

The import process convert the bar-descriptor.xml and .pro files of your application. It strips the code that is related to "Zygote" your application. This will reduce the start up of your application but should not affect its functionality.

Localization

The import process convert the bar-descriptor.xml and .pro files of your application. It strips the localization support aka the "translations" folder and its inclusion into BAR package.

Known Bugs

Qml Profiler Tool is not supported by QtQuick1 applications for Qt ver. <= 4.8.6

For more information see QTBUG-36144. This bug affects QtQuick1 applications only. The Cascades applications can be still profiled as expected.