Clone wiki

blackberry-py / Installing Tart

Installing Tart

Tart is distributed as a zip file containing everything (other than the NDK) that you need to build Python apps. Actually you'll need to provide your own code. Fingers probably help too. Maybe also a computer.

This page assumes you've already figured out how to install the NDK, which you likely did without reading our yet-to-be-written NDK Tutorial.

Downloading Tart

Grab the latest binary release of Tart from the downloads page. The file is called tart-m.n.zip where m.n is the version number.

Create a folder in which to do your development. If you're not using a revision control system such as Mercurial or Git, you really should learn about them and pick one, to save your sanity. If you've already got Mercurial installed, you could start a new project easily with hg init myproject and then unzip the tart zip in that new folder.

Configuring Tart

Our goal is for very little configuration to be required, but enough that we can automate or simplify certain things that would otherwise be tedious or difficult.

Our "model" for a proper development environment is based on using a modern revision control system. Popular choices include Mercurial, Git, and Subversion and no modern developer should work without one. Tart expects to find a tart.ini file in the top of your working folder.

For now, the only thing required is a pointer to your debug token file, but in future other global settings will be stored there too. If you specify an idbase value, it will be used to automatically form app ids for each app by appending the app's "name" field.

# tart.ini file
[environment]

# Path to debug token file (should be treated as relative to this file)
debugtoken: debugtoken.bar

# The base of any app id which doesn't explicitly specify an id.
# If no "id" field is provided in tart-project.ini, the app id
# will be formed from this string, a dot, and the app name.
idbase: ca.microcode

The file syntax is that of a typical "ini" file, with a mandatory section named [environment] and by convention the key/value separator is a colon followed by space, instead of an equal sign (though either works).

Configuring an App

Individual apps should have their own configuration file as well, to leverage the tart package utility which greatly simplifies the process of building a .bar file to deploy your app.

The app or project file is named tart-project.ini and should reside in the main folder for an app, which is usually a subdirectory of the repository's top folder where tart.ini resides.

The following is a minimal project file, and contains enough for tart package to build the app.

[project]
# that's right... no real content is required if idbase is in tart.ini

All fields will be created from default values, the name of the containing folder, or information supplied by the tart.ini file.

A real project file looks more like this:

[project]
name: CoolApp
title: Super Cool App
id: com.example.SuperCool
version: 1.0.2
description: The supercoolest app in the world.

theme: dark
icon: coolicon.png

permissions:
    bbm_connect
    access_internet

assets:
    schema.xml
    extradata/

The app should also have an app.py file, or a Python package named app and this will be discovered automatically. All Python files imported by it or by others will be compiled to .pyc files and those files included in the app.

If you need to include files that aren't .py files, include them or their parent folder name in the assets field above.

The default theme is dark. (It's a known issue that you can't currently leave the theme unspecified and use the device default.)

The default icon is named icon.png but if you don't provide a file named that, the NDK supplies a default image.

A minimal app needs an app.py with some code to create the tart.Application instance, and an assets/main.qml file to define the main page of your UI.

Packaging an App

Once you have your tart-project.ini file defined, and your app source created (and cloning one of the samples is the best way to get started, possibly the StarterApp), you can easily package your app into a .bar file.

Execute the following command from within the tree under your tart.ini:

tart.cmd package -mdebug path/to/MyApp

This will build a "debug mode" Bar file containing all the files required to install on your device. The default is to build for the ARM architecture which the devices use, but you can specify "--arch x86" if you're building for the simulator.

Learn about other options using "tart.cmd help package" or the "-h" option.

To package a final release for signing and deployment through BlackBerry World, use "-mrelease" (which is also the default, so you can just leave it out).

tart.cmd package -mrelease path/to/MyApp

Each of these commands will output some progress info and then place the final Bar file in the current directory. In the above example, the output file would be named MyApp.bar or possibly something else, based on the value of the "name" field in the tart-project.ini file.

Updated