Building and launching

In the Momentics IDE for BlackBerry, all of your development tasks start with the toolbar. You can use the toolbar to build, launch, debug, profile, and analyze your app.

Screen showing the buttons and drop-down lists on the toolbar.

When you create a project, the Momentics IDE creates a launch configuration for your app. You can create a launch configuration for different modes, such as run, debug, profile, or memory analysis. When you select a launch mode on the toolbar, it changes how the Momentics IDE starts the app. You can build your app directly in the Momentics IDE and deploy it to a device or simulator that's configured as a launch target.

Link against libraries

Before you can build an app successfully, you must link against all of 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, because these libraries contain some of the most commonly used APIs. In this model, shared libraries are pre-linked into one library. Linking to the libraries before the app starts helps to decrease start-up time.

If you're creating a Cascades 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 of 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 that are available in the BlackBerry 10 Native SDK, see Library support.

Compile resources for Cascades apps

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

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

To compile the QML files in your own app, you need to complete the following tasks:

Create the .qrc file

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

In the .qrc file, you specify the location and names of the QML files that you want to compile.

Screen showing the qrc-assets file in the Momentics IDE for BlackBerry.

For example:

<RCC version="1.0">

Change the .pro file

Next, you must change your app's .pro file to reference the .qrc file that you created:

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

Reference QML files

In your C++ app code, you must change how you load a QML file into the app. Here's how you typically load a QML file:

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

You must change this code 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 app from mistakenly scanning and loading QML files other than the files 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 security options

The Makefile in a Cascades project contains a set of instructions that specify how to build an app. When you use the Momentics IDE to build and package your app, 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. For more information, see Makefile security settings for Cascades apps.

You can select compiler and linker options that activate security features when you compile your C project and link object files into shared objects and executables. By default, the Momentics IDE applies the compiler and linker options to new C projects for all managed builds and Makefile projects. For more information, see Security options for C apps.

Makefile security settings for Cascades apps

These compiler and linker options make it harder to exploit vulnerabilities in an app. With the correct configuration, many vulnerabilities that might allow attackers to take control of an app 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

Security options for C apps

You can set compiler and linker pass-through options for C apps.

Compiler options

This option causes the compiler to inject a cookie. If a buffer overflow occurs at runtime, the cookie is overwritten and the app quits with an error message on the console. Users don't see the console error when the app exits.
-D defines a macro and _FORTIFY_SOURCE provides lightweight buffer overflow protection to some memory and string functions. For example, with -D_FORTIFY_SOURCE=2, the line strcpy (&var.t.buf[1], "abcdxyz"); is considered a buffer overflow. If the compiler determines at compile time that an overflow occurs, it issues a warning. If the compiler cannot detect an overflow at compile time, it performs a check at runtime. If the check fails, the compiler prints a message on the console and ends the process.

You must use the -fPIE option when you compile your app as a position-independent executable (PIE). PIE refers to code that runs correctly regardless of its location in memory. To take full advantage of the Address Space Layout Randomization (ALSR) security features in the BlackBerry 10 OS, compile your executable as a PIE. The Momentics IDE applies this option only to release builds.

Be careful not to compile shared objects with the -fPIE option. Use the -shared option instead. The -shared option implies -fPIC.

The default option in the toolchain is PIE. If you have non-PIC libraries, you must rebuild them to link them correctly into a PIE binary, or use -nopie when linking the executable to generate an absolute executable.

Since gprof doesn't work on shared objects, when you compile and link with -p, you need to specify -nopie to generate an executable and linkable format (ELF) executable with output that gprof can use.

Linker pass-through options

This option causes the dynamic linker to mark dynamic relocations in ELF files as read-only when the relocation tables have been processed.
This option forces all relocations to be applied, and all symbols to be resolved immediately at runtime. Without this option, the dynamic linker resolves the app lazily. If you use this option together with -Wl,-z,relro, they provide a high level of protection for the relocation table.
This option produces a position-independent executable (PIE). The Momentics IDE applies this option only to release builds.

Create a launch configuration

To run, debug, or profile an app 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 app 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 options.

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, Application Profiler, and Memory Analysis tool. You specify these settings once, and then you can use them when you need to. 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, click Create New Configuration.
  3. Select the initial launch mode and click Next.

    To profile your app, select either C/C++ Profile or QML 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.

Last modified: 2015-07-24

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

comments powered by Disqus