View source for Deployment on BlackBerry

{{Cleanup | reason=Auto-imported from ExpressionEngine.}}

[[Category:BlackBerry]]



This article explains various details about deployment on BlackBerry 10 for Qt developers. Generally, this topic is well explained in the BlackBerry 10 documentation for native application development. In this article, you will find some additional details and tips specific for Qt development.

== Start with BlackBerry 10 docs ==

It is good to get an overview first if you are new to a platform. Please read the following overview articles in the BlackBerry 10 documentation:
* [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_stub_app_creation_process.html Developing apps] and all articles in that section.
* [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_about_bar_app_descriptor_file.html The BAR application descriptor file ] and [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_appfund_accessing_restricted_functionality.html App permissions]
* [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_appfund_applifecycle.html App Life Cycle]
* [https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html Working with the file system]. This article also explains how standard Qt paths, e.g. <code>QDir::homePath()</code> are mapped to the file system.
* [https://developer.blackberry.com/native/documentation/core/rtos.html Using low-level functionality]

== Application packaging ==

The page [https://developer.blackberry.com/native/documentation/core/qt_package_deploy.html Packaging, deployment and distribution] is a good introduction to the tools and how to use them.
In short, applications are packaged in so called '''BAR files''' which are zip archives with additional meta information.

=== Blackberry Application aRchive (BAR) descriptor file ===

A part of this meta information is the content of the [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_about_bar_app_descriptor_file.html BAR application descriptor file] which is an '''XML''' file. This file describes the content of the package and where this content can be found. This file defines other important meta information as well, but this is less relevant to this article.

Qt Creator has an editor for the BAR application descriptor files which simplifies quite some manual editing.

The content of the package may also include images, sounds and any other data files used by the application in addition the the binary.

See [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/r_blackberry_tablet_dtd_intro.html full list of all elements in a BAR application descriptor file]

=== blackberry-nativepackager ===

Application packages are created by the command line tool '''blackberry-nativepackager''' provided in the BlackBerry 10 NDK. This tool reads a BAR application descriptor file passed as an argument and builds the application package accordingly.

Application packages can be built in a development mode or can be built as signed packaged. Development mode applications require a '''debug token''' and can be installed and run on any device with the same debug token as they were build with.

Signed packaged are usually used for publishing in BlackBerry World. They can also be installed from the command line on any device in development mode and do no need a debug token.

See the full article about [http://developer.blackberry.com/native/documentation/core/qt_package_deploy.html Packaging, deployment and distribution]

== Where do the app resources land on the device ==

=== Handling the sand box ===

Each application is installed in its own home folder on a dedicated partition. Shared folders (those which contain data to be shared between apps) are mapped according to permissions requested so that the app can access them under the standard paths. An important thing to keep in mind is that all applications can access files only within the boundaries of their "sandboxes". When the app asks to access shared data, according folders become available in app's sandbox as well. See [https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html Working with the file system] for an overview of all sub-folders for different purposes in app's home folder.

Applications cannot directly access any files outside their sandboxes. Even though it is possible to package and deploy libraries with the application, it is not possible to deploy any libraries into the system folders. Applications cannot share their libraries with other applications either.

=== Packaging and accessing the files ===

Even though the article [https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html Working with the file system] explains how the sandbox model influences file access, it might be clear from the beginning how paths can actually be referred in the application code.

Lets assume you have an app which loads an image with Qt Quick . The application code is located in the subfolder "test_assets" in your "projects" folder. The first thing you have to take care of is to add this image to the BAR application descriptor file:

<code>
 <asset path="/Users/johndoe/projects/test_assets/qt-logo.png">qt-logo.png</asset>
</code>

This line is the universal way to add any other "stuff" to the app package, see "this":The application descriptor file DTD article for more details. It is basically:

<code>
 <asset path="<local_path_to_files>/<local_file_name>"><on_device_path_to_files>/<on_device_file_name></asset>
</code>

or even shorter:

<code>
 <asset path="<SOURCE>"><TARGET></asset>
</code>

Note: we use an absolute path in the above example to handle shadow builds. A relative path works too, but will make shadow builds less portable than absolute paths :-)

You also have to add QML files:

<code>
<asset path="/Users/johndoe/projects/test_assets/qml">qml</asset>
</code>

The key thing to know here is that the app installation folder is mapped to the folder "app/native" in the application working directory (referred by QDir::currentPath(), i.e. a "." folder in the BAR application descriptor file maps to the "app/native/." folder. Our app, the app would be installed for example in:

<code>
/accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f
</code>

The "qt-logo.png" lands here:

<code>
/accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qt-logo.png
</code>

The "qml" folder will be recursively copied to
<code>
/accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qml/
</code>

Our app has only one QML file which lands here:

<code>
/accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qml/main.qml
</code>

This QML code loads the image in "main.qml" as:

<code>
 Image {
 source: "../qt-logo.png"
 anchors.centerIn: parent
 }
</code>

Notice the "../" in the front of the file name! This is because the current folder of an Qt Quick element is where its file was loaded from. We load "main.qml" this way:

<code>
int main(int argc, char *argv[])
{
 QGuiApplication app(argc, argv);
 QQmlApplicationEngine engine;
 engine.load(QUrl(QStringLiteral("app/native/qml/main.qml")));
 return app.exec();
}
</code>

"Image" assumes it is located in "app/native/qml/" and so needs to get one level up to get to ""app/native/qt-logo.png".

One more thing to notice. The article [https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html Working with the file system] also talks about a dedicated "assets directory". This is a bit confusing, since the "asset" XML element in the BAR application descriptor file can refer to any file, but the "assets directory" refers to the "asset" URI scheme in the Cascades framework. Using Cascades UI components you can load image as"

<code>
ImageView {
 imageSource: "asset:///image.png"
}
</code>

Doing the same in Qt Quick with Qt 4.8:

<code>
 Image {
 source: "asset:///qt-logo.png"
 anchors.centerIn: parent
 }
</code>

does not work, since the "asset" scheme is not available in Qt Quick. There is another approach for this in Qt 5.2 and later.

=== Prefer using the Qt resources ===

Using Qt resources (via the "qrc://" scheme) for all small read-only files and especially for QML code files is a '''more preferred and convenient way*! Accessing assets as files makes only sense for large read-only files or files which will be changed/created by the app.

=== Viewing the folders on the device ===

In some cases, it might be needed to inspect the actual content of the folders directly on the device. You can do this in an SSH shell in the File Inspector in the Momentics IDE. The article [[BlackBerry_Hints_n_Tips | BlackBerry Hints and Tips]] shows how to use SSH with BlackBerry 10 along with a few other hints and tips.

== Packaging and Deploying Qt5 applications using the binary Qt5 overlay ==

The easiest way to deploy Qt5 applications for testing and distribution in Blackberry World is to use the binary overlay explained in [[ Qt5-on-BlackBerry10 ]]. It contains an experimental make specs add-on which provides special make targets for deployment and packaging. See the article [[Custom_Qt_on_BlackBerry_devices|Using custom Qt builds on BlackBerry 10 devices]] for details. This add-on also automates the deployment of a Qt runtime for a shared use which is explained below.

== Shared use of data by multiple apps in development ==

If your application has been packaged in the development mode (the '''-devMode''' option in '''blackberry-nativepackager'''), it gets slightly more permissions than if it was in the release mode (see [https://developer.blackberry.com/native/documentation/core/com.qnx.doc.ide.userguide/topic/package_deploy_about.html this article] in the BlackBerry 10 documentation for mode details). One of those permissions is a read/write permission for the '''devuser''' home folder. '''devuser''' is a user account on the device linked to your debug token. You can use this folder if the apps use the same set of data for development purposes.