The news that Canonical is working on a version of Ubuntu for the smartphone drew excitement from industry-watchers around the world. However, if you've actually downloaded the trial version onto your own smartphone, you might have hit a wall: all is not tried and tested.

The good news is that, although the actual Ubuntu phone OS is still in incubation, the QML Toolkit, which is used to build apps for the new system, is available for users who want to experiment with developing for the Ubuntu Phone. This article shows how to get started with the QML Toolkit development environment. The instructions are largely based on the work of Canonical developer David Planella, who is responsible for efforts around the new Ubuntu phone apps and has a website [1] dedicated to encouraging QML development (see the box titled "What is QML").

This article describes how you can use Qt Creator to set up a development environment for QML. I won't delve into the code itself. (You'll find several good online tutorials on QML coding.) The prerequisite is that you use at least Ubuntu 12.10, because the components for "Quantal Quetzal" are required. (Some developers have reported success with installing the Quantal packages on Ubuntu 12.04 [2], but I have not tested this alternative.

Ubuntu 12.10 is the first version to include QML support, and the steps for setting up QML have gotten easier with Ubuntu 13.04. As with many new technologies, the configuration steps are a "moving target" as tools and procedures evolve.

Hands on: Qt 5 (12.10)

If you are running Ubuntu 13.04, all you have to do to get started is install the ubuntu-sdk package.

If you are running Ubuntu 12.10, the first thing you need is a very recent version of Qt5 that you can get from a PPA. Use the following commands:

$ sudo add-apt-repository ppa:canonical-qt5-edgers/qt5-beta1
$ sudo apt-get update
$ sudo apt-get install qt5-meta-full

You get the essential Qt packages onto your machine by installing the qt5-meta-full package. Look for the executable Qt applications in the /opt/qt5/bin directory. To run the executables system-wide on Ubuntu, you'll need to use Bash. To do this, open a terminal using Ctrl+Alt+T and enter the following command:

$ echo 'export PATH=/opt/qt5/bin:$PATH' >> ~/.bashrc

The path now ends in the hidden configuration file ~/.bashrc .

The qt-components are reusable QML files or components for Qt Quick – certain buttons and other graphical elements. These components are especially for Ubuntu, and you'll install them with the following steps (from the PPA):

$ sudo add-apt-repository ppa:ui-toolkit/ppa
$ sudo apt-get update
$ sudo apt-get install qt-components-ubuntu*notepad-qml qtcreator

As you might have noticed, Qt Creator is immediately installed at this point. The graphical application helps in developing GUIs with Qt and is also ideal for building the desired QML interfaces. But, you first need to link the Integrated Development Environment (IDE) with qmlscene to invoke the code directly from Qt Creator. qmlscene is a viewer for QML documents.

Preparing Qt Creator

You don't need to install qmlscene separately, because it's already in the /opt/qt5/bin directory with the Qt5 version. Start Qt Creator with Bash or from the HUD and, if you are running Qt Creator on Ubuntu 12.10, choose Tools | Options . On the External Tools tab, select Preview (qmlviewer) . Double-clicking changes the option to Preview (qmlscene) and shows up later as a menu item in Qt Creator. Next to Executable Files , click the Select button and navigate to the /opt/qt5/bin directory, in which you choose qmlscene . Clicking Open and OK completes the task. (Again these configuration steps are not necessary if you have installed the ubuntu-sdk package on 13.04.)

You can now create your first project, which you open using Files | New File or Project . Under Projects , select Applications and, right next to it, choose Qt Quick UI (Qt Quick 2 UI on 13.04).

Next, give the project a suitable name. In his tutorial, David Planella describes how you can develop a currency conversion app with the name CurrencyConverter.

You will need to have write permission for the application folder. You can place the folder in your home directory, for example, in /home/{USERNAME}/qml . Optionally, you could use a version control program such as Bazaar to protect the code [3].

Hello, World!

After completing the steps successfully, you will end up in a document that already contains code. On 12.10, using Tools | External | Qt Quick | Preview (qmlscene) doesn't let you run the code, because it is a bit outdated. An online working code example from David Planella [4] appears in Listing 1. A simple copy-and-paste is enough to add the code and, using the aforementioned steps, you'll be able to see your application.

01 import QtQuick 2.0
02 import Ubuntu.Components 0.1
03
04 Rectangle {
05     id: root
06     width: units.gu(60)
07     height: units.gu(80)
08     color: "lightgray"
09
10     property real margins: units.gu(2)
11     property real buttonWidth: units.gu(9)
12
13     Label {
14        id: title
15        ItemStyle.class: "title"
16        text: i18n.tr("Currency Converter")
17        height: contentHeight + root.margins
18        anchors {
19            left: parent.left
20            right: parent.right
21            top: parent.top
22        }
23     }
24 }

On 13.04, however, if you visit Tools  | External | Qt Quick | Qt quick 2 Preview (qmlscene) , you will immediately be able to run the placeholder program, and you will see a window like the one in Figure 1. Running the program shown in Listing 1 results in a window like the one in Figure 2.

Figure 1: Use the QML Toolkit to create your first app for "Ubuntu for Phones."

Figure 2: CurrencyConverter gives you a taste of what you can do with QML.

Starting package

Now you can begin to work through some of the tutorials to understand QML better – practiced JavaScript users have a definite advantage. Planella's tutorial is a good start [4]; with a dearth of other tutorials, Planella points to the API for the currently available elements [5].

Qt5 developers also have other tutorials online that explain how to develop the QML graphical interface [6]. Because the SDK for 12.10 is a bit spotty, I recommend upgrading to the SDK offered in 13.04, which is much better and easier to set up. Interested developers can also register with the "Ubuntu for Phones" project [7].