View source for Custom Qt on BlackBerry devices

=Using custom Qt builds on BlackBerry 10 devices=

This document describes approaches how to use a custom Qt build to BlackBerry 10 devices and use it for application development in Qt Creator or on the command line. See [[Qt-Creator-with-BlackBerry-10]] for overall description of using Qt Creator with BlackBerry 10 and [[Deployment on BlackBerry]] article for more details about deployment .

==Extending the built-in Qt 4.8==

BlackBerry 10 devices have built-in Qt 4.8 located in the <code>/usr/lib/qt4/<code> folder. There is no need to setup anything in tooling if you use Qt4. Just create a new project and use a kit representing BlackBerry 10 with Qt4. Qt Creator 3.0 and later detects Qt4 in the BlackBerry 10 <span class="caps">NDK</span> and creates appropriate kits automatically. If you use an older version of Qt Creator you might need to create kits manually.</code></code>

In an exceptional case you might decide to use a custom version of Qt4, you can use the remaining part of this page as a guidance. The major point to be aware of is that Qt4 uses the environment variable <span class="caps">QML</span>_IMPORT_PATH to point to the <span class="caps">QML</span> plugins and modules, instead of QML2_IMPORT_PATH in Qt5.

==Adding a custom Qt build to Qt Creator==

The below sections covers Qt5, but it is generally the same for any other Qt build. First, [[Building-Qt5-for-Blackberry|build Qt5 for your BlackBerry 10 device]]. Further, we will assume that your Qt5 build is installed in “$HOME/development/qnx/qt5” folder and and you used the BlackBerry 10 <span class="caps">NDK</span> target 10.2.0.1155 stored in “/opt/bbndk” folder.

Here are the steps how to add this build to Qt Creator:

* Setup the “Qt Version”:
** Go to “Tools -&gt; Options… -&gt; Build &amp; Run -&gt; Qt Versions” tab
** Press “Add” button
** Browse <code>qmake<code> binary in your Qt5 build, e.g. <code>$HOME/development/qnx/qt5/qtbase/bin/qmake<code></code></code></code></code>
** Add a sensible name in the “Version name” field
** In the section “BlackBerry Native <span class="caps">SDK</span>”, choose the directory with contains “host_*” and “target_*” folders which has been used for building Qt5 e.g. the <code>/opt/bbndk<code> folder.</code></code>
** Press “OK” or “Apply” button
* Setup a kit for your Qt5 in Qt Creator:
** Go to “Tools -&gt; Options… -&gt; Build &amp; Run -&gt; Kits” tab
** Press “Add” button to create a new kit, fill its field as:
*** Name – specify a sensible name for your kit. Consider reusing the name you gave to the “Qt Version” as above
*** Select in “ BlackBerry Device” in “Device type”
*** Device – select a BlackBerry 10 device or simulator from the list which you previously connected and configured in Qt Creator
*** In “Sysroot”, se the path to the sysroot folder which starts with the “qnx6” folder within the “target_*” folder that you have used for building Qt5 e.g. “/opt/bbndk/target_10_2_0_1155/qnx6/” folder
*** Select “<span class="caps">GCC</span> BlacckBerry 10” compiler in the “Compiler” section that matches the one for BlackBerry 10 <span class="caps">NDK</span> Target used for building Qt5, e.g. “<span class="caps">GCC</span> BlackBerry 10 (target_10_2_0_1155)”
*** The “Debugger” can keep the default value for for the “System <span class="caps">GDB</span> at /usr/bin/gdb” or also set to the debugger provided in the BlackBerry 10 <span class="caps">NDK</span> Target used for building Qt5
*** Select the Qt5 build you added on the previous previous steps in “Qt-Version”
*** The section “Qt mkspec” can stay empty when developing on a BlackBerry 10 device or should be be set to “blackberry-x86-qcc” when developing for BlackBerry 10 Simulator
** Press “OK” or “Apply” button

Now you can create a new project using “File -&gt; New File or Project… -&gt; Applications -&gt; Qt Quick 2 Application (Built-in Types)” or “BlackBerry Qt 5 <span class="caps">GUI</span> Application” project template. In “Kit Selection” wizard page, select the kit registered above. When asked whether to create a <span class="caps">BAR</span> file descriptor, press “Yes”.

==Embedding a custom Qt build into a BlackBerry 10 application package==

The <code>bar-descriptor.xml<code> file generated in the example at the end of the last section should contain the following or similar lines:</code></code>

The first block sets the environment variables which are set by the navigator before launching the app. This make the application use the Qt run-time bundled into the application package instead of the system one. The deployment of the according artifacts is defined in the second section. See [[Deployment on BlackBerry]] for details about handling assets relevant to Qt application development on BlackBerry 10.

Ideally, the environment variables should have more values to cover all possible use cases so that you do not need to touch them frequently in the future:

This has a few modifications compared to the previous one:

# It uses “app/native/runtime/qt/” instead of “app/native/” for hosting the Qt runtime. This provides more flexibility, since you might want to install your own libs, Qt plugins or <span class="caps">QML</span> modules. You could then use “app/native/” for this and so make sure they do no collide with Qt itself
# It adds “/accounts/devuser/qt/”. This path can contain a Qt runtime which you deploy for development purposes as described later on this page.
# It retains the values which might have been set in the platform in the future

This way of setting Qt runtime variables will be used in all templates provided for BlackBerry 10.

===Handling symbolic links===

When you let Qt Creator run the application on the device, it will first create the application package and upload it to the device. The package will be around 60MB, and now includes the Qt runtime. It may take around a minute to deploy and launch the application on a device. If you look up the actual size of the related binaries in the Qt build you will see that they are actually much smaller, around 15MB. The problem with an over-sized Qt package is that the line <code>&lt;asset path=”\\%QT_INSTALL_LIBS\\%”&gt;lib&lt;/asset&gt;<code> tells the <code>blackberry-nativepackager<code> tool to take the entire <code>libs<code> folder and package it as an asset. This folder usually contains symbolic links to lib names with compatible versions. For security reasons, the <code>blackberry-nativepackager<code> tool adds all symbolic links in a folder as actual files. Due to this, each Qt library is copied multiple times which significantly increases of the package size.</code></code></code></code></code></code></code></code>

Regardless how big Qt5 build is, deploying it each time wastes time in development. There is a method to significantly increase the deployment speed by using an approach when all apps in development mode (the <code>-devMode<code> option in the <code>blackberry-nativepackager<code> tool) can access the home folder of the <code>devuser<code>. See another section about this on this page.</code></code></code></code></code></code>

The only sensible way to reduce the size to a minimum is to manually package only those libraries which are needed. In addition to the explicit listing of the used libraries only, you can also exclude the Qt libraries you don’t use to decrease the package size. For that, you can use the ''&lt;exclude&gt;'' element to specify the libraries to be excluded as shown in the example below:

Similarly, you can explicitly list only those libraries that you are using:<br />

'''''Note:''''' you can use the <code>ntoarm-readelf<code> command line to find out what libraries your application depends i.e. which should be included in the assets. Just make sure that you inspect the dependencies recursively (i.e. even for the dependent libraries) – readelf tool just reports direct dependencies only.</code></code>

When you use a custom Qt build in an application, it is easy to make a mistake which will lead to a missing part of the Qt runtime. In such a case, your application will shortly popup on the screen and then disappear again. Check the [[BlackBerry Hints n Tips|BlackBerry Hints and Tips]] to learn who to check the logs and find out what happened.

==Sharing a Qt5 runtime on a device between apps for development purposes.==

The approach uses the fact the apps in development mode call access the home folder of the “devuser”, see [[Deployment on BlackBerry]] article for more details. This is an attractive possibility saving a lot of time, since you do not add your custom Qt build each time you deploy your app. If you are working on Qt, you can also use this method to deploy a experimental version of Qt for testing. The only thing to keep in mind that this approach does not work with final, signed packages since they cannot access the <code>devuser<code> account anymore. Basically, this approach is a help to reduce app deployment time during the application development. When you are preparing an application to be submitted to BlackBerry World, you need to switch back to “Embedding a custom Qt5 build into a BlackBerry 10 application package” approach otherwise your application will not start.</code></code>

The basic idea is to copy the Qt runtime binary artifacts into a subfolder in <code>/accounts/devuser/<code> on the device, and set relevant environment variables, e.g. <code>LD_LIBRARY_PATH<code>, to point to that Qt installation.</code></code></code></code>

'''Note''': a build of Qt 4.8 is pre-integrated in each BlackBerry 10 firmware and <span class="caps">NDK</span> release. You should not waste your time for adding another Qt 4.8 build unless you have a very good reason for this.

The first step is to copying the Qt runtime onto the device. You start with establishing an <span class="caps">SSH</span> connection to the device. See [[BlackBerry Hints n Tips|BlackBerry Hints and Tips]] to learn how to do this.

Lets assume that <code>$QTDIR<code> points to the root folder of a cross-compiled Qt5 build for BlackBerry 10 and we are going to use the folder <code>/accounts/devuser/qt<code>:</code></code></code></code>

''If you have a '''Qt4''' build you need to copy the <code>imports<code> folder instead of the <code>qml<code> as above.</code></code></code></code>''

Make sure that <code>/path/to/private/key&gt; is the private key part from the public key you used to initiate the <span class="caps">SSH</span> daemon on the device with <code>blackberry-connect<code> as outlined in [[BlackBerry Hints n Tips|BlackBerry Hints and Tips]] .</code></code></code>

Deploying will be even faster if you strip the libraries before copying them. Note that this removes debug symbols from the Qt libraries as well. On a BlackBerry 10 device this can be done with:

Use <code>ntox86-strip<code> for the simulator target. On PlayBook, you can do:</code></code>

The second and the last step is to check the <span class="caps">BAR</span> application descriptor file and to verify that Qt runtime environment variables are set to use it. See the according section on this page about this.

QtCreator 3.1 will integrate all these steps in the <span class="caps">IDE</span> and so support sharing a Qt5 runtime from the active BlackBerry kit on a device between apps for development purposes.

==Using the new make targets and save time on command line:-)==

The recently posted <span class="caps">NDK</span> overlay (see [[Qt5-on-BlackBerry10|Qt5 on BlackBerry10]]) contains an experimental version of an add-on to make specs which significantly improves the work with a custom Qt5 build on the command line. This add-on automatically adds new make targets for packaging, deployment, signing and even deployment of a Qt runtime for development purposes as mentioned in the previous section. Here is a short summary of the provided commands which is also shown if you type “make bbhelp”:

It wraps command line tools included in the <span class="caps">NDK</span> and adds several new make targets. A few environment variables need to be set by the user to pass device and user specific information to the scripts used by the make targets:

* <span class="caps">DEBUG</span>_TOKEN must be set to a full path to a debug token to be used to package the project app in development mode.
* <span class="caps">DEVICE</span>_IP must be set to the &lt;IP address&gt; of the device.
* <span class="caps">DEVICE</span>_PASSWORD must be set to the device password.
* <span class="caps">BAR</span>_DESCRIPTOR may be set to the name of the <span class="caps">BAR</span> (BlackBerry Application Archive) descriptor file to be used.
* <span class="caps">KEYSTORE</span>_PASSWORD must be set to the developer certificate password.
* <span class="caps">CSK</span>_PASSWORD must be set to the bb id token password.

The following additional make targets are provided:

* deploy_qt: deploys Qt runtime into /accounts/devuser/qt/ on the device.
* bar: packages the assets and binary artifacts from the Qt project into a <span class="caps">BAR</span> file ready to be deployed to a device device.
* bar_qt: same as the “bar” target, but adds Qt runtime to the <span class="caps">BAR</span> file.
* bar_signed: same as “bar”, but additionally signs the <span class="caps">BAR</span> file for distribution.
* bar_qt_signed: same as “bar_qt”, but additionally signs the <span class="caps">BAR</span> file for distribution.
* deploy: deploys an existing .bar file to a device.
* bbhelp: displays this message.

Example Usage:

This deploys Qt, creates a <span class="caps">BAR</span> file referring to it and deploys it to the device as specified by the environment variables “<span class="caps">DEVICE</span>_IP” and “<span class="caps">DEVICE</span>_PASSWORD”

This creates a <span class="caps">BAR</span> file with application artifacts and the Qt runtime and deploys it to the device as specified by the environment variables “<span class="caps">DEVICE</span>_IP” and “<span class="caps">DEVICE</span>_PASSWORD”.

The “bar_qt” make target automatically adds the Qt runtime from the Qt5 build in the overlay by adding it to the bottom of the <span class="caps">BAR</span> application descriptor file. This be in conflict with the Qt5 runtime you might had specified using QtCreator or even not be able to parse QtCreator specific variables used in 3.0 and earlier:

The best way to fix this is to use delete related asset lines the <span class="caps">BAR</span> application descriptor file, deploy Qt on the central place with “make deploy_qt” or from QtCreator 3.1 and later and use the values for Qt runtime environment variables as described earlier on this page.

A version of this add-on is currently in the review for a submission as a new feature in Qt 5.4.

===Categories:===

* [[:Category:BlackBerry|BlackBerry]]
* [[:Category:HowTo|HowTo]]