Compiling libraries and resources

By pre-linking your libraries and compiling resources, you can decrease app start-up times and page load times while making minimal changes to your application code.

Pre-linking libraries

Cascades uses a number of different Qt and platform-specific libraries. In previous releases, the majority of an app's start-up time was spent loading and linking these shared libraries. In the current model, shared libraries are pre-linked into one library. Since linking to the libraries is done before the application is started, this helps decrease start-up time.

The changes to the project templates only affect applications that you build using the Device-Release configuration. If you build apps using the Device-Debug and Simulator-Debug configurations, you shouldn't pre-link libraries because this can cause issues for debugging.

Creating a new project

If you're creating a new application, you don't have to do anything to pre-link shared libraries. Just create a new project using any of the Cascades project templates and your app pre-links its shared libraries automatically.

In the Project Explorer view, you can expand the Includes folder to see all the libraries that are available. The libraries that are pre-linked by default are the ones that you typically use to create a Cascades application, such as the ones in the bb and qt4 folders.

Screen showing the Project Explorer view in Momentics IDE.

Migrating an existing project

If you have a project that was created using an older version of Cascades, you can migrate to the new template without creating a new project.

To start, open the .pro file in your project. As an example, here's the project file for the Cascades Cookbook application:

TEMPLATE = app
TARGET = cascadescookbookqml

CONFIG += qt warn_on debug_and_release cascades
INCLUDEPATH += ../src   SOURCES += ../src/*.cpp
HEADERS += ../src/*.h

device {
    CONFIG(release, debug|release) {
        DESTDIR = o.le-v7
    }
    CONFIG(debug, debug|release) {
        DESTDIR = o.le-v7-g
    }
}

simulator {
    CONFIG(release, debug|release) {
        DESTDIR = o
    }
    CONFIG(debug, debug|release) { 
        DESTDIR = o-g
    } 
}

OBJECTS_DIR = $${DESTDIR}/.obj
MOC_DIR = $${DESTDIR}/.moc
RCC_DIR = $${DESTDIR}/.rcc
UI_DIR = $${DESTDIR}/.ui

As mentioned above, pre-linked libraries are applicable only to release binaries, so you need to make changes to that configuration only. The first step is to add a template override from app to lib in the Device-Release configuration section of the project file. You can also change the visibility of default symbols to -fvisiblility=hidden to prevent internal symbols from being available, which makes the library smaller and faster to link against.

...

device { 
    CONFIG(release, debug|release) {
        DESTDIR = o.le-v7
        TEMPLATE=lib
        QMAKE_CXXFLAGS += -fvisibility=hidden
    }

...

Next, you must update the main() declaration in the main.cpp file:

int main(int argc, char **argv)

Add the Q_DECL_EXPORT symbol before the declaration:

Q_DECL_EXPORT int main(int argc, char **argv)

The final change is in the bar-descriptor.xml file. Here's the bar-descriptor.xml file for the Cascades Cookbook application:

<configuration id="com.qnx.qcc.toolChain.1485069140" name="Device-Debug">
  <platformArchitecture>armle-v7</platformArchitecture>
  <asset path="arm/o.le-v7-g/cascadescookbookqml" entry="true"
         type="Qnx/Elf">cascadescookbookqml</asset>
</configuration>

<configuration id="com.qnx.qcc.toolChain.1120265426" name="Device-Release">
  <platformArchitecture>armle-v7</platformArchitecture>   
  <asset path="arm/o.le-v7/lib/cascadescookbookqml.so.1.0.0" entry="true"
          type="Qnx/Elf">cascadescookbookqml.so</asset>
</configuration> 

Add an app entryPointType to the Device-Release configuration called Qnx/Cascades:

...

<configuration id="com.qnx.qcc.toolChain.1120265426" name="Device-Release"> 
    <entryPointType>Qnx/Cascades</entryPointType>

...

After you update the bar-descriptor.xml file, you must export the project to a .zip file. To export the project:

  1. Right-click the project and click Export.
  2. Expand General, select Archive File, and click Next.
  3. Click Browse, find a location to save the file, provide a file name, and click Save.

Next, you must create a new workspace. If you created a new workspace when you installed the latest version of the BlackBerry 10 Native SDK, that's fine. The workspace just can't be the one that you initially created the project with. To create a new workspace, click File > Switch Workspace > Other and specify a location for the new workspace.

Now you must import the project into your new workspace. To import the project:

  1. Click File > Import.
  2. Expand General, select Existing Projects into Workspace, and click Next.
  3. Click Browse, locate the project, and click Finish.

Lastly, it's time to test your new application. To test out your app:

  1. Right-click your project, click Build Configurations > Set Active > Device-Release.
  2. Right-click your project and click Clean Project.
  3. Build and deploy your app.
 

Compiling resources

Compiling application resources is another way that you can decrease your app's loading times. In an application that doesn't compile resources, QML files are stored within the app's assets folder in the file system. Accessing these QML files can be very inefficient for applications that contain a lot of QML. To help speed up load times for QML, you can compile your QML files as a resource.

When you compile your QML as a resource, the QML isn’t technically compiled since it still needs to be parsed and read. The content from the QML is bundled in your binary file, which decreases the time that your application needs to access the content.

To compile the QML in your own application, there are several tasks described below that you need to complete:

Create the .qrc file

The first step to compiling resources is to create a .qrc file in the same location as your project file. In this example, a file called qrc-assets.qrc is created.

Within the .qrc file, you specify the location and names of the .qml files that you want to compile. For example:

<!DOCTYPE RCC>
<RCC version="1.0">
<qresource>
<file>assets/main.qml</file>
<file>assets/common/mycomponent.qml</file>
</qresource>
</RCC>
Screen showing the qrc-assets file in the Momentics IDE for BlackBerry.

Modify the .pro file

Next, you must modify your application's project file to reference the .qrc file you created:

RESOURCES += qrc-assets.qrc
DEPENDPATH += assets

Reference .qml files

Within your C++ application code, you need to make changes to how you load a .qml file into the application. Here's how you typically load a .qml file:

QmlDocument *qml = QmlDocument::create("asset:///main.qml");

You must change this to:

QmlDocument *qml = QmlDocument::create("qrc:/assets/main.qml");

Asset selection is not supported with compiled resources. For example, if your app stores QML assets in a 720x720 folder, you can't compile your QML resources.

Filter out other .qml files

To prevent the application from mistakenly scanning and loading .qml files other than those bundled in the binary, you should ensure that the .qml files are removed from the assets directory on the device. You can filter out the .qml files by adding the following lines to your bar-descriptor.xml file:

<asset path="assets" dest="assets">
    <exclude name="**/*.qml"/>
</asset>

For more information about compiling resources, see The Qt Resource System on the Qt website.

Last modified: 2013-12-21

comments powered by Disqus