Clone wiki

blackberry-py / Building Tart

Building Tart

This page describes the steps needed to build an entire Tart binary distribution, which includes the TartStart launcher, libraries, JavaScript shim, and Python packages.

The following sections describe each major activity you'll need to complete to prepare your development machine for creating a Tart distribution.

You can successfully use Tart and build Python apps for BlackBerry 10 without doing this, however, as we provide a binary distribution (e.g. on our downloads page. You will still require an installation of the NDK, however, in order to package, sign, and deploy your own apps.

Note: these instructions are written for Windows, but if you're installing on OSX or Linux it should be easy to adapt them as you go.

Clone Repository

We're using Mercurial to manage the repository. Although the BlackBerry community has a preference for Git, the Python community has a preference for Mercurial. The project is hosted at Bitbucket (the Mercurial-based cousin to Github).

Install Mercurial if you don't have it already. You have a choice of command-line only (regular Mercurial) or the TortoiseHg package which gives a GUI and also Explorer integration. Make sure that your PATH is updated to include the location of the "hg" executable, then run:

hg clone
cd blackberry-py

You may want to add the blackberry-py/bin folder to your PATH as well, though you can use its contents without doing so.

Download Python sources

Although we're not compiling Python itself, we need the Python header files as TartStart is responsible for embedding Python in the app. The headers are available in the Python source distribution so the simplest approach is just to install that.

Download and extract the Python 3.2.2 source tarball. A shortcut to doing this is provided in the bin/ utility. The makefile assumes the sources are in ../Python-3.2.2, relative to the TartStart folder.

Install the BlackBerry Native SDK

BlackBerry 10 has several SDKs, each of which includes a set of command-line utilities for signing, packaging, deploying, and connecting to a device or simulator for development purposes. To build TartStart, which has C++ source, you'll need the Native SDK (also known as the NDK). Although there's a beta 10.2 package available, it has rough edges. For now, stick with what we used for the official Tart distribution: NDK 10.1.

This isn't a tutorial on how to install and use the NDK, so if you've never done it before you should follow the instructions on that page, perhaps starting here:

The pre-10.2 installer may be available at bb10_1_x-win32-1020-201303191709-201303191501.exe and the rest of this document assumes you've installed it.

After installation, you need to ensure that some environment variables are set and that your PATH is updated. The simplest way to do this is to run c:\bbndk \bbndk-env.bat (or on other platforms).

Retrieve Files from Device/Simulator

The NDK includes the header files (for compilation) and images (for linking) of all the standard libraries, but not for Python. In order to compile TartStart and link it you'll need to retrieve a couple of files from the device (or the simulator, if you're not using a device).

  1. Get a copy of the /usr/include/python3.2m/pyconfig.h file from the target. Place this file in the include/ directory of the Python-3.2.2 folder.

  2. Get a copy of the /usr/lib/ file from the target (device or simulator) against which you plan to build. The one from the device should go into libs/arm and the simulator's version should go in libs/x86.

If you have PuTTY installed, you could retrieve these files as follows:

  1. Launch the SSH server on the device or simulator using Momentics, or with the blackberry-connect utility:

    blackberry-connect DEVICEIP -password PASS
  2. Without terminating the above connection, use another console window to retrieve the required files. The following assumes you have installed PuTTY and have the pscp command in your PATH. Make the substitutions for DEVICEIP and SIMIP appropriate for your own network. If connected via USB, the address is likely

    pscp devuser@DEVICEIP:/usr/include/python3.2m/pyconfig.h Python-3.2.2\include
    md libs\arm
    pscp devuser@DEVICEIP:/usr/lib/ libs\arm
    md libs\x86
    pscp devuser@SIMIP:/usr/lib/ libs\x86

Compile Sources

Change to the TartStart directory and run "make". The included Makefile is configured to expect the various dependencies to be in the locations described above.

The Makefile provides the following build targets:

Optimized executable with reduced logging and faster startup (this is the default if you specify no build target)
Full logging, suitable for use during development
Same as Device-Debug but built for the simulator (x86)
Builds all of the above.
Copies the executables to ../tart/entry.
Removes build artifacts from TartStart folders.

If you're trying to build the Tart distribution package, run the following and you should get the three executables in the right location (blackberry-py/tart/entry).

cd TartStart
make all
make install
make clean
cd ..

Packaging for Distribution

There's now a convenience script for building the complete Tart binary distribution, which includes all three variants of TartStart, the lib-downloads libraries, the JavaScript code, and all the Python code in the framework.

If you've been able to get all the above installed and working, running bin/ with a revision or tag name (which can be just "tip" for the latest, not including your local changes) will build a binary distribution file.