Building and running

When you develop a Cascades application in the Momentics IDE for BlackBerry, you can build your app directly in the IDE and deploy it to a device or simulator that's configured as a launch target.

The following sections contain information about important build and project settings.

Link against libraries

Before you can successfully compile and build a Cascades app, you must link against all the libraries that you use in your app.

For your convenience, a Cascades project automatically links against bb/data, most of bb/cascades, and most of the Qt modules, since these libraries contain some of the most commonly used APIs. In this model, shared libraries are pre-linked into one library. Since linking to the libraries is done before the app is started, this helps decrease start-up time

If you're creating a new app, 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 app, such as the ones in the bb and qt4 folders.

You can specify additional libraries that you want to link against in the .pro file for your app.

Screen showing the Project Explorer view in Momentics IDE.

For a complete list of libraries available in the BlackBerry 10 Native SDK, see Library support.

Compile resources

Compiling application resources is a way to 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:

<RCC version="1.0">
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"/>

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

Set makefile security settings

The makefile in a Cascades project contains a set of instructions that specify how to build an application. When you use the Momentics IDE to build and package your application, you don't typically need to modify any of these instructions. However, depending on the version of the BlackBerry 10 Native SDK that you're running, you might need to update some security settings.

These compiler and linker options help increase the difficulty of exploiting vulnerabilities in the application. With the correct configuration, many vulnerabilities that might allow attackers to take control of an application become more difficult to exploit. The recommended security settings for a Cascades app are as follows:

QMAKE_LFLAGS_RELEASE += -Wl,-z,relro -pie
QMAKE_POST_LINK = ntoarm-objcopy --only-keep-debug ${DESTDIR}/${QMAKE_TARGET} ${DESTDIR}/${QMAKE_TARGET}.sym && ntoarm-objcopy --strip-all -R.ident --add-gnu-debuglink "${DESTDIR}/${QMAKE_TARGET}.sym" "$@" "${DESTDIR}/${QMAKE_TARGET}" 

In future releases, some of these values might be enabled by default.

If your project has been updated to a recent version of Cascades, adding these settings might not work on their own. To determine if additional settings are required, look for the line containing the CONFIG variable in your .pro file. If that line contains cascades10, then the following settings are also required:

QMAKE_CFLAGS_RELEASE += -fstack-protector-strong
QMAKE_CXXFLAGS_RELEASE += -fstack-protector-strong

Create a launch configuration

To run, debug, or profile an application on your target device or simulator, you need a launch configuration. If you don't create a launch configuration, the Momentics IDE creates a default configuration for you when you run your application for the first time. You can select a launch mode, such as Run, Debug, QML Profile, or Run Release, from the Launch mode drop-down list and use the default launch configuration for each of these tools.

If you want more control, you can create a launch configuration. A launch configuration defines which app to launch, the command-line options to use, and what values to use for environment variables. The configuration also defines which tools to run with your app, such as the Code Coverage tool, the Application Profiler, and the Memory Analysis tool. You enter these settings once, and then you can use this collection of settings again and again. You can also create multiple launch configurations for your app.

To create a launch configuration:

  1. On the toolbar, in the Launch Target drop-down list, select a device or simulator.
  2. In the Launch configuration drop-down list, select Create New Configuration.
  3. Select the initial launch mode, and click Next.

    To profile your app, select either C/C++ Profile or QML Profile instead of Profile.

  4. In the Launch Configuration Type options, select either BlackBerry C/C++ Application or BlackBerry Postmortem Debugging. You can use the default launch configuration settings or customize the settings:
    • To use the default settings, on the Launch Configuration Type screen, click Finish.
    • To customize the settings, on the Launch Configuration Type screen, click Next. Select the settings that you want, and then click Finish.

Build your app

After you create a project, you need to build it before you can run it on a device or simulator. The launch mode determines how the binary file is packaged (with or without debugging capability), and what type of launch target it runs on (device or simulator). For example, executables built using a debug launch configuration contain additional debug information that lets the debugger make direct associations between the source code and the binaries generated from that original source.

When you build a launch configuration, the Momentics IDE compiles and links your project.

  1. On the toolbar, select the Launch mode that you want to build, for example, Run or Debug.
  2. In the Launch configuration drop-down list, select the launch configuration for the project.
  3. In the Launch Target drop-down list, select the device or simulator that you want to build on.
  4. To build the binaries, click Build button.

When you build your project, the IDE creates binaries that are configured to run on the launch target that you specified. Each build configuration can also contain a unique set of assets (as specified on the Assets tab in the bar-descriptor.xml file).

You can watch a build's progress and see the output in the Console view. If a build generates any errors or warnings, you can see them in the Problems view.

You can also build a project manually. For more information, see Build an application manually.

Run your app

When you've built the application binaries and created the launch configuration, your app is ready to run on the specified launch target.

To run your app:

  1. From the Launch mode drop-down list, select Run.
  2. Make sure that the launch configuration for your project is showing in the Launch configuration window or select it from the drop-down list.
  3. Make sure that your target is showing in the Launch target drop-down list.
  4. Click Momentics launch button or right-click your app and click  Run As > BlackBerry C/C++ Application.

Last modified: 2014-09-30

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus