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 target.

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

You'll also find instructions for how to build and run an app, how to debug an app, and how to profile an app to analyze its performance.

Linking against libraries

Before you can successfully compile and build a Cascades application, 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.

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

Link against a library

To manually link against a library, add a LIBS variable to the .pro file for your app and specify the library name prefixed with -l. For example, if you want to link against the bb/cascades/multimedia library, you must include the following line:

LIBS += -lbbcascadesmultimedia

If you need to link against more than one library, you can list them all on the same line.

LIBS += -lbbcascadesmultimedia -lbbdevice -lbbsystem

You can also use the Add Library wizard to link against a library in your project. In the Momentics IDE for BlackBerry, select your project and click Project > Add Library. Click Standard BlackBerry platform library and follow the instructions in the wizard to select the libraries that you want to add to your project. For more information, see Add libraries.

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

Libraries

Here's a complete list of all of the Cascades and Qt libraries that you must manually link against.

Namespace Linking command

bb/cascades/advertisement

-lbbcascadesadvertisement

bb/cascades/maps

-lbbcascadesmaps

bb/cascades/multimedia

-lbbcascadesmultimedia

bb/cascades/pickers

-lbbcascadespickers

bb/cascades/places

-lbbcascadesplaces

bb/device

-lbbdevice

bb/location

-lbblocation

bb/multimedia

-lbbmultimedia

bb/network

-lbbnetwork

bb/pim

-lbbpim

bb/pim/account

-lbbpim

bb/pim/calendar

-lbbpim

bb/pim/contacts

-lbbpim

bb/pim/message

-lbbpim

bb/pim/notebook

-lbbpim

bb/platform

-lbbplatform

bb/platform/bbm

-lbbplatform

bb/platform/geo

-lbbplatform

bb/system

-lbbsystem

bb/system/phone

-lbbsystem

bb/utility

-lbbutility

bb/utility/i18n

-lbbutilityi18n

QtConnectivity

Linking against the QtConnectivity library is different from linking against other libraries. Instead of specifying the library name in the LIBS variable, you must add connectivity to the CONFIG variable, as follows:

CONFIG += mobility
MOBILITY += connectivity

QtLocationSubset

-lQtLocationSubset

QtNfcSubset

-lQtNfcSubset

QtSensors

Linking against the QtSensors library is different from linking against other libraries. Instead of specifying the library name in the LIBS variable, you must add sensors to the CONFIG variable, as follows:

CONFIG += mobility
MOBILITY += sensors

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_CFLAGS_RELEASE += -fPIC
QMAKE_CXXFLAGS_RELEASE += -fPIC
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
QMAKE_LFLAGS_RELEASE += -Wl,-z,relro

Setting the build configuration

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

In addition, each build configuration can also contain a unique set of assets (as specified on the Assets page in the bar-descriptor.xml file).

When building your application, there are several different build configurations to choose from. To get started, you can use one of the following:

  • Device-Debug (the default build configuration)
  • Device-Profile
  • Device-Release
  • Simulator-Debug

To change the build configuration, right-click the project and select Build Configurations > Set Active and select the new build configuration.

When you build your project, the IDE creates binaries that are configured to run on the target that you specified. To build the binaries, right-click the project and click Build Project or click Build button.

Setting the 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 run configuration, the Momentics IDE creates a default configuration for you when you run your application for the first time. You can select Run, Debug, Profile, or Run Release from the Active Tool 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 consists of various settings and environment variables that affect how the application starts. You enter these settings once, and then you can use this collection of settings again and again.

To create a launch configuration:

  1. Right-click a project in the Project Explorer and select Run As > Run Configurations to create a run configuration (or Debug As > Debug Configurations to create a debug configuration and Profile As > Profile Configurations to create a profile configuration).
  2. Click the New launch configuration icon.

    You can see many configuration possibilities that all deal with starting your executable program. Right now, only the Main tab requires your input. Later, however, you should also look at what the other tabs have to offer.

    Screen showing the Run Configurations wizard in the Momentics IDE.
  3. In the Build configuration drop-down list, choose a build configuration for your application.
  4. Make sure that your target is listed under Target Options, and then click Apply. The launch configuration is now ready.
  5. Click Close.

If a target is not listed under Target Options, you might not have set up a target correctly. To set up a target, run the BlackBerry Deployment Setup Wizard.

Running an application

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

To run your app, make sure your app is showing in the Active Project window or select it from the drop-down list. Right-click the binary file that you want to run and click  Run As > BlackBerry C/C++ Application or click Run button.

Last modified: 2014-01-23

comments powered by Disqus