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. tart-1.0.zip) 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 https://microcode@bitbucket.org/microcode/blackberry-py
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/getpythondev.py 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:
https://developer.blackberry.com/native/documentation/bb10/getting_started.html

The pre-10.2 installer may be available at
https://developer.blackberry.com/native/downloads/fetch/installer-bbndk-
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 bbndk-env.sh 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/libpython3.2m.so 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 169.254.0.2

    pscp devuser@DEVICEIP:/usr/include/python3.2m/pyconfig.h Python-3.2.2\include
    
    md libs\arm
    pscp devuser@DEVICEIP:/usr/lib/libpython3.2m.so libs\arm
    
    md libs\x86
    pscp devuser@SIMIP:/usr/lib/libpython3.2m.so 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:

Device-Release
Optimized executable with reduced logging and faster startup
(this is the default if you specify no build target)
Device-Debug
Full logging, suitable for use during development
Simulator-Debug
Same as Device-Debug but built for the simulator (x86)
all
Builds all of the above.
install
Copies the executables to ../tart/entry.
clean
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/make-tart-distro.py 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.

Updated