The porting process

Porting involves the following steps:

  1. Determine app dependencies.
  2. Set up your build environment.
  3. Build your project and resolve compiler issues.
  4. Write platform-specific features.
  5. Deploy your app.

The following sections describe each step in the process. For some general tips to make your porting efforts easier, see Tips and tricks.

Determine app dependencies

Before you port your app or library to BlackBerry 10, it's important to understand the dependencies, or required libraries, of the project. You can do that either by reading the documentation associated with the project or by looking at the makefiles and other build configuration files that come with it. Some libraries are guaranteed to be available, such as the POSIX standard C library. Other libraries may be specific to your app and you’ll have to either port that library yourself or find a version that has been ported already.

When you know which libraries you need, you can compare that list with the libraries that are included with the BlackBerry 10 Native SDK. You can import these libraries for use in your project. The libraries that are available to you are located in the \lib and \usr\lib directories, in the \target_<version>\qnx6\armle-v7 directory, which is located in the Native SDK installation folder. The libraries for the BlackBerry 10 Device Simulator are located in the \target_<version>\qnx6\x86 folder.

Set up your build environment

After you study the dependencies that your app requires and decide to go ahead and port it, the next step is to set up a build environment. You have three choices:

  • Use the Momentics IDE for BlackBerry: Allows you to take advantage of the compilation, deployment, debugging, and profiling features of the IDE
  • Use makefiles: Gives you direct, command-line control over the compiler and linker (and you might be more familiar with this type of build)
  • Use the GNU Autotools: Makes compilation on different platforms easier

Use the Momentics IDE

You can use two types of builds in the Momentics IDE: makefiles or managed builds. A makefile describes how to compile and link projects using instructions contained in files, whereas a managed build moves compiling and linking options into properties and views in the Momentics IDE. Experienced porters tend to favor the makefile approach, which makes sense because many projects are based on makefiles. But if you're not familiar with them, you can use managed builds instead.

The makefile system in the Momentics IDE is a bit different from what you might be used to. It is recursive in nature and searches for directories that correspond to the target systems that you want to build for, such as ARM for BlackBerry 10 devices and x86 for the simulator. It traverses each directory and builds each variant that you specify. For example, the build outputs a.le.v7 (static library), so.le.v7 (shared library release), so.le.v7.g (shared library debug) are all for a single target system (the one that corresponds to the current project folder).

To set up the Momentics IDE for porting:

Before you build your project, make sure that all references to include paths, libraries, and files are applied to the correct launch configuration. The Momentics IDE treats each launch configuration separately, so references specified in the Device-Debug configuration may not appear in the Device-Release configuration. If you have references that apply to all configurations, you should specify them using All configurations. This setting applies to assets that are specified in the bar-descriptor.xml file as well. For more information about building projects, see Building your app.

Use makefiles

You can build your project outside of the Momentics IDE by using the qcc compiler that comes with the Native SDK (located in <install directory>\host_<version>\win32\x86\usr\bin). If you use this approach, the bbndk-env_<version>.sh file located in the installation directory sets the required environment variables that are necessary to compile.

If you started with a build for a different platform (for example, Linux), you can often use the same defines in that project’s makefile for your new build.

If you add code that is specific to BlackBerry 10, you can use the #ifdef __QNX__ predefined macro to conditionally include or remove code based on the platform type.

Use the GNU Autotools

It's common for apps and libraries to use the GNU Autotools to support compiling for different platforms. The Autoconf tool creates a configure script that you can use to ease the burden of creating a different makefile for every platform. A configure script processes a makefile.in file and some configuration files to create a platform-specific makefile as output. For more details, take a look at the Autoconf manual. An example of an open source library that uses the GNU Autotools is the Simple DirectMedia Layer (SDL) library, which is located on GitHub.

If you use a configure script to create a makefile that builds your app for BlackBerry 10, make sure that the following environment variables are set:

RANLIB="${QNX_HOST}/usr/bin/ntoarmv7-ranlib "
CPP="${QNX_HOST}/usr/bin/qcc -V4.6.3,gcc_ntoarmv7le -E "
CC="${QNX_HOST}/usr/bin/qcc -V4.6.3,gcc_ntoarmv7le "
LD="${QNX_HOST}/usr/bin/ntoarmv7-ld "
CPPFLAGS="-D__PLAYBOOK__ -D__QNXNTO__ "
CFLAGS=" -g -fPIC -fstack-protector-strong"
LDFLAGS="-L${QNX_TARGET}/armle-v7/lib -L${PREFIX}/lib -lscreen -lasound -lpps -lm -lpng14 -lbps -lEGL -lGLESv2 -Wl,-z,relro -Wl,-z,now -pie"

In this example, the LDFLAGS variable includes the libraries that the app needs, such as Screen and EGL. To run the configure script on Linux, you must pass in the following cross-compile flags:

./configure --build=i686-pc-linux --host=arm-unknown-nto-qnx6.5.0eabi

You may also need to pass in additional parameters depending on the capabilities required by your app and the configure script.

POSIX-compliant apps expect a file system layout that conforms to the Filesystem Hierarchy Standard. Using this format means that, by default, the software you build is installed in /usr/local. However, on a BlackBerry 10 device, you don't have write access to anything outside the app or shared directories. To deal with this situation, you may need to edit the bar-descriptor.xml and config.xml files in the project to correct any paths to files that the app needs.

If you edit any files that the Autoconf tool uses, such as .m4 files, you must run the following command to generate new build files:

NOCONFIGURE=1 ./autogen.sh

You must also set the NOCONFIGURE environment variable so that the script doesn't run the configure script, because you run it manually later with the cross-compile flags, as shown above.

Build your project and resolve compiler issues

After you set up the build environment in a way that lets you cross compile for BlackBerry 10, the real work begins. You might compile your project and end up with a .bar file that you can install and test on a device, but it's likely that you'll have to address some platform-specific issues. If you can get your project to compile, though, you're in a good position to continue with those tweaks.

Write platform-specific features

When you port your app to BlackBerry 10, you may find that some of your app's features don't work correctly or in the same way as they used to. For example, the way that information or UI elements are displayed on the screen may be different, or the input methods that your app uses are handled differently in BlackBerry 10.

You should look at the libraries that are included in the BlackBerry 10 Native SDK, as well as open source libraries that are supported, to find the features that your app uses and write code that uses these BlackBerry 10 libraries. To learn more about the features that you may need to convert, see Writing platform-specific features.

Deploy your app

Depending on the environment you choose, you should consider certain factors when you deploy to a BlackBerry 10 device or the simulator. At a minimum, you need to sign your app so that it can be distributed on the BlackBerry World storefront. For more information on signing, see Signing and publishing.

If you're using the Momentics IDE for BlackBerry, you can package and deploy your app from within the IDE. You also have access to the powerful code coverage, profiling, and memory analysis features of the IDE. To learn more, see Packaging and deploying apps.

If you're building your app using makefiles outside of the Momentics IDE or using the GNU Autotools, you can run the blackberry-deploy tool from the command line to start your app on the BlackBerry 10 device or the simulator. An example of an automated script that uses the blackberry-deploy tool is included with the SDL library, which is located on GitHub.

Last modified: 2014-09-30



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

comments powered by Disqus