Start porting

Porting involves the following steps:
  1. Determine application dependencies on external libraries.
  2. Set up your build environment.
  3. Build and resolve any compiler issues.
  4. Write platform-specific features.
  5. Deploy your application!

Determine application dependencies

Before you port your application 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 are very specific to your application 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 Native SDK. The libraries that are available to you are located in the \lib and \usr\lib directories, in the \target\qnx6\armle-v7 directory, which is located in the Native SDK installation folder. The BlackBerry 10 Dev Alpha Simulator files are located in the \target\qnx6\x86 folder.

If you don’t see a library that you need to compile the application you're porting, check the Library support page for a list of existing libraries that were already ported to the Native SDK. You can import these into your Native SDK project.

Set up your build environment

After you study the dependencies that the application requires and decide to go ahead with the port, the next step is to set up a build environment. You have three choices:
  1. Use the Momentics IDE for BlackBerry: Allows you to take advantage of the compilation, deployment, debugging, and profiling features of the IDE
  2. Use makefiles: Gives you direct, command-line control over the compiler and linker (and you might be more familiar with this type of build)
  3. Use the GNU Autotools: Leverage the GNU Autotools approach for making compilation on different platforms easier

Use the Momentics IDE

You can use two types of builds within 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 given that most projects are based on makefiles – but if you are not familiar with them, you can use managed builds to make your life easier.

The makefile system in the Momentics IDE is a bit different than 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:
  1. If you do not have a project already, you can create a project as described here, choosing between a makefile or managed build type.
  2. If you have a makefile-based project already, you can import the existing source code as described here.
  3. If you have a dependency on an existing library, that is already built for the BlackBerry 10 OS, you can add it to the project by using the Add Library Wizard, as described here.
  4. To configure the build, you can edit the project's makefiles for a makefile build, as described here, or edit the project's build properties for a managed build, as described here.

Before you perform the build, make sure all references to include paths, libraries, and files are applied to the correct Build Configuration. The Momentics IDE treats each Build Configuration separately, so references specified in Device-Debug may not appear in Device-Release. If you have references that apply to all configurations, you should specify them using All configurations. This applies to assets specified in the bar-descriptor.xml file as well.

Use makefiles

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

Note that 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 is common for applications and libraries to use the GNU Autotools to support compiling for different platforms. The Autoconf tool creates a script called configure 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, have a look at the Autoconf manual here. An example of an open-source library that makes use of the GNU Autotools is the Simple DirectMedia Layer library, located here.

If you use a configure script to create a makefile that builds your application for BlackBerry 10, you must ensure 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 the application needs, such as Screen and EGL. To run the configure script on a Linux platform, 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 application and the configure script.

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

If you edit any files that the Autoconf tool uses, such as .m4 files, you must run NOCONFIGURE=1 ./autogen.sh to generate new build files. You must also set the NOCONFIGURE environment variable so that the script doesn't run configure, because you'll run it manually later with the cross compile flags, as above.

Build and resolve any compiler issues

After you set up the build environment in a way that lets you cross compile for BlackBerry 10, the real work begins. Unless you get lucky — it's not unheard of to just compile and end up with a .bar file that you can install and test — you will have to address some platform-specific issues, but once you get your application compiling, you're in a good position to continue with those tweaks.

Last modified: 2014-06-24



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

comments powered by Disqus