Command Line Rocks! Building BlackBerry 10 Apps Without An IDE

How-to

Don’t get me wrong, I love our Momentics IDE. It provides many features that help to build apps rapidly including the QML previewer and code auto-completion. Sometimes, however, it can be extremely useful to know what’s going on under-the-hood.

This article will aim to explain how to build a native app from the command line, using the tools bundled in the BlackBerry 10 Native SDK and your favourite text editor.

Set up your environment

The Native SDK includes a script called bbndk-env.sh (or .bat on Windows) in the root folder that initialises the environment variables that the other tools depend on. I will refer to the install location of the Native SDK as $NDK_DIR.

Mac: source $NDK_DIR/bbndk-env.sh
Win: $NDK_DIR/bbndk-env.bat

So what does this script set?

The most important environment variables are:

QNX_TARGET: This directory contains all the configuration files and libraries for the BlackBerry 10 device, the target that we want our app to run on.  You can see all the libraries which can be linked against in $QNX_TARGET/armle-v7/lib and $QNX_TARGET/armle-v7/usr/lib.

QNX_HOST: This directory contains the tools and configuration files for our host system, ie Windows, Mac or Linux. It includes a compiler, linker and assembler for cross compiling to various architectures, as well as command line tools for packaging, signing and deploying your application.

Building for the ARM architecture

You may have noticed the use of armle-v7 in the above directory structure. This refers to the processor architecture on BlackBerry 10: ARM Little Endian Version 7. To build binaries that run on BlackBerry 10 you need to compile for this architecture.

Start by creating a folder to hold our app’s files, call it GoodbyeIDE. From now on I will refer to this as $PROJECT_DIR. Inside this folder create a file called main.c with the following content:

#include <stdio.h>
int main()
{
  fprintf(stdout, "Goodbye IDE!\n");
  return 0;
}

Now lets compile it. Change to $PROJECT_DIR and execute:

qcc -Vgcc_ntoarmv7le main.c -o main

Lets explain this command in a bit more detail. qcc stands for QNX C Compiler. BlackBerry 10 is built on top of QNX and uses many of its build tools.

qcc is essentially a wrapper for gcc  (GNU Compiler Collection). The -V switch tells qcc which version of gcc to use, in this case its the ntoarmv7le version which stands for QNX Neutrino ARM Version 7 Little Endian (a bit of a mouthful).

To build for the BlackBerry 10 simulator you need to use the gcc version for the x86 architecture.

qcc -Vgcc_ntox86 main.c -o main

To view a full list of the available gcc versions run:

qcc -V

The main.c -o main part of the command just specifies the input C filename and output binary filename.

OK, so now we should have a binary (called main) that will run on a BlackBerry 10 device. This binary won’t run on your host operating system since it’s not compiled for the same architecture. If you have a working gcc you can compile it by doing:

gcc main.c -o main2
./main2

When you execute main2 you should see “Goodbye IDE”.

TITLE_IMAGE

Create the BAR descriptor XML

BlackBerry 10 apps are packaged as BAR (BlackBerry Application aRchive) files. To create a BAR file we need a descriptor file called bar-descriptor.xml. This file includes information about the app such as name, version, required permissions and a list of assets.

Create the bar-descriptor.xml file with the following content:

<qnx>
  <id>com.example.GoodbyeIDE</id>
  <versionNumber>1</versionNumber>
  <name>Goodbye IDE</name>
  <asset path="main" entry="true">main</asset>
</qnx>

From our point of view the most important line in bar-descriptor.xml is this one:

<asset path="main" entry="true">main</asset>

This specifies that the BAR contains a file called main which is the entry point for the app.

A full list of BAR application descriptor parameters is available here.

Packaging and deploying your app

Now that we have a binary and an application descriptor we are ready to create a BAR file.

A BAR file is essentially a zip file which contains all your app’s assets and the meta information from bar-descriptor.xml. In fact, if you rename a .bar file to .zip you will be able to extract it to see all the files in that app.

To create a BAR file run the following command:

blackberry-nativepackager -package GoodbyeIDE.bar bar-descriptor.xml -devMode -debugToken ~/Library/Research\ In\ Motion/debugtoken1.bar

Note that the -devMode and -debugToken flags are only required if you are deploying to a physical device. This is a handy feature that allows you to deploy your app without signing it, as long as your debug token is installed on the device.

To do this you’ll need to register with RIM to sign applications and create a debug token.

So now you have a BAR file called GoodbyeIDE.bar you can deploy it to the device using the following command:

blackberry-deploy -installApp 169.254.0.1 -password pass GoodbyeIDE.bar

169.254.0.1 is the IP of your target and pass is the device password.

If you take a look at your application icons, you should see a new one called Goodbye IDE (as specified in the <name> tag in bar-descriptor.xml).

cmd2

If you tap on the icon your app should run! But…nothing happened, right?

Viewing log files over SSH

Actually the app did run, it’s just that all it did was print “Goodbye IDE!” to the stdout. The stdout on BlackBerry 10 is directed into a log file. We can view this log file by SSHing onto the device. Here’s how:

First we have to tell the device that we want to create a secure connection to it:

blackberry-connect 169.254.0.1 -password pass

Now open an SSH client (such as putty) and run:

ssh devuser@169.254.0.1

You should now be connected via SSH. Feel free to poke around! Apps are installed in /accounts/1000/appdata. Each app is given its own sandbox folder with a unique name based on its id (which we specified in bar-descriptor.xml).

Example sandbox folder name: com.example.GoodbyeIDE.testDev__GoodbyeIDEcf9b848

The log file can be found in the logs directory under the sandbox folder name. To view the file just run:

cat log

The log file is re-created each time the app is run. To test that the app is working delete the log file, tap on the app icon and run the above command again.

Summary

That’s it for now. The next article will focus on making your life easier by using Makefiles, the Qt build system and creating a more logical project folder structure.

Read the next article in the series, here.

About Don Turner

I work for the BlackBerry Developer Relations team helping developers bring their apps to the awesome BlackBerry 10 platform. I specialise in gaming technologies, native development and Cascades.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus