Generally, this topic is well explained in the BlackBerry 10 documentation for native application development.

Application Packaging

The page 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 that contain additional meta-information.

Blackberry Application aRchive (BAR) Descriptor File

A part of this meta information is the content of the BAR application descriptor file which is an XML file. This file describes the content of the package and where this content can be found. Other important meta-information is defined in this file, as well.

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 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 development mode or can be built as signed packages. 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 not need a debug token.

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 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 Working with the file system explains how the sandbox model influences file access, it might not be clear from the beginning how paths can actually be referred in the application code.

This line is the universal way to add any other content to the app package:

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

or even shorter:

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

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 following line adds this image to the BAR application descriptor file:

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

You also have to add QML files:

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

Note that we used absolute paths in the above examples, though relative paths work, as well.

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(), for example a . folder in the BAR application descriptor file maps to the app/native/. folder. Our app would be installed for example in:

/accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f

The qt-logo.png lands here:

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

The qml folder will be recursively copied to

/accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qml/

Our app has only one QML file which lands here:

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

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

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

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

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

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 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:

ImageView {
    imageSource: "asset:///image.png"
}

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 and Tips shows how to use SSH with BlackBerry 10 along with a few other hints and tips.