Revision as of 19:28, 25 May 2010

This is work in progress. It references various components which are not available publicly, but will be made available around the time of the MeeGo 1.0 release (some time in May 2010).

Introduction

This tutorial introduces developing for MeeGo x86 devices on Linux.

How to do it (the short version)

• Get and install the MeeGo SDK
• Enter the MeeGo SDK environment
• Start the Simulator
• Start Qt Creator
• Use Qt Creator to build a project, configuring it to use the correct DISPLAY environment variable for the Simulator
• Build the project using the SDK's Qt libraries
• Run the application inside the Simulator
• Debug the application inside the Simulator

If you've got a MeeGo device:

• Prepare the device
• Run the application on the device
• Debug the application on the device

How to do it (the longer version)

Install the MeeGo SDK on your Linux machine

See Getting started with the MeeGo SDK for Linux for instructions. You should also install Qt Creator, as explained in the same instructions.

Enter the MeeGo SDK environment

See these instructions on how to enter the MeeGo SDK environment.

Run the Simulator

With everything installed, you should now be able to run the Simulator.

Build the project with Qt Creator

Start Qt Creator from the MeeGo environment command line with:

qtcreator &

This runs Qt Creator on the host (not inside Xephyr):

To setup the project:

• Create a new project (File > New File or Project). Under Projects, select Qt Gui Application and click OK.
• Enter helloworld for the name; choose a directory to save it to. Click on Next.
• Accept the defaults in the Class Information dialog box and click Next.
• In the Project Management dialog box, click Finish.

Next write some code:

• Open the Forms folder and double-click mainwindow.ui to open it in the graphical forms editor.
• Drag a label from the list of widgets on the left-hand side of the forms editor and drop it into the editable area.
• Change the text to something else ("Hello world" works well).
• Put any other junk you like the look of in there.

Then configure the project:

• Click on the Projects icon on the left of the Qt Creator window.
• Configure the Qt version:
  • Under Build Settings > General, click on the More button. This displays the Qt version which will be used when building and running the project.
  • Click on the Manage button next to Qt Version. This displays the Qt Versions panel:
    
  • Select the Qt in PATH entry.
  • Click on Rebuild to set up the Debugging Helper for this version of Qt.
  • Click OK to save your changes.
• Make sure that the Qt Version is now set to Default Qt Version (Qt in PATH).
• Next, configure the run environment to use the Simulator to display the application when it's running:
  • Scroll down to the Run Settings and click on the More button under Run Environment.
  • Double-click in the text entry next to the Display variable; change :0.0 to :2. This tells Qt Creator to run the application on display number :2, the one which Xephyr is in control of.

Run the application inside the Simulator

Now you're all set to run the application.

From inside Qt Creator, click on the big green arrow (bottom-left corner) to run the application. This will build it first (using the Qt Version you set up) then run it on display :2 (inside the Xephyr simulated MeeGo desktop).

In the Simulator, you might need to click on the MyZone icon (the house icon) to reveal the application running behind it:

Debug the application inside the Simulator

This means running the application from Qt Creator, but with debugging turned on, so you can watch the state of the application while it's running under Xephyr.

In the previous sections, we built the debugging helper for the version of Qt we're using. This needs to be done first, otherwise you can't debug the application.

To put Qt Creator into debug mode, click on the bug icon in the left-hand toolbar. This adds some extra panels to the window which are used to show the stack, watch expressions etc..

Next, you need something to debug. I added a Push Button to the form:

Then added a click handler for it, so that when the button is clicked, a message string is assigned into a variable then output to the console. The code looks like this:

/* file: Headers/mainwindow.h */
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>

namespace Ui {
    class MainWindow;
}

class MainWindow : public QMainWindow {
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = 0);
    ~MainWindow();

protected:
    void changeEvent(QEvent *e);

private:
    Ui::MainWindow *ui;

private slots:
    void on_pushButton_clicked();
};

#endif // MAINWINDOW_H

/* file: Sources/mainwindow.cpp */
#include "mainwindow.h"
#include "ui_mainwindow.h"
#include <QDebug>
#include <QString>

MainWindow::MainWindow(QWidget *parent) :
    QMainWindow(parent),
    ui(new Ui::MainWindow)
{
    ui->setupUi(this);
}

MainWindow::~MainWindow()
{
    delete ui;
}

void MainWindow::changeEvent(QEvent *e)
{
    QMainWindow::changeEvent(e);
    switch (e->type()) {
    case QEvent::LanguageChange:
        ui->retranslateUi(this);
        break;
    default:
        break;
    }
}

void MainWindow::on_pushButton_clicked()
{
    QString message;
    message = "I have been well and truly clicked";
    qDebug() << message;
}

Most of this is boilerplate generated when I started the project, but the MainWindow::on_pushButton_clicked method is mine. Notice how it also needs to be defined as a private slot in the header file.

Add a breakpoint next to the line where you want the debugger to break by clicking in the editor margin. It looks like this:

(See the red circle on line 34 after message is initialized.)

To run the application in debug mode, click on the green arrow with a bug overlaid on it (bottom left). This starts the application inside Xephyr:

Now, click on the button. The program should pause at the breakpoint. Switch back to Qt Creator and look at the debug panels:

Notice how the Locals and Watchers tab reports the message variable set to "I have been well and truly clicked".

For more information about using Qt Creator in debug mode, see [1].

Optional instructions for using a real MeeGo device

If you have a real MeeGo device available, it's also possible to run and debug your application on it using Qt Creator.

Prepare the device

The device requires some configuration and extra packages before you can deploy from Qt Creator to it. Install them from the command line as follows:

1. Deployment from Qt Creator to a real device uses SSH for file copying, so you need to install OpenSSH server on the netbook with:

   sudo yum install openssh-server

   To start it manually (you'll need to do this just after you've installed it, otherwise it won't be available until you reboot):

   sudo /etc/init.d/sshd start

   To add it to the init sequence so it starts at boot time:

   sudo chkconfig --add sshd

2. If you want to debug applications remotely, you need to install gdbserver on the netbook:

   sudo yum install gdb-gdbserver

Run the application on the device

In Qt Creator (still running from the chroot):

1. With a project selected, click on the Projects icon to show the project configuration tabs.
2. Select the Run Settings tab.
3. Click on the Add drop-down and select testapp on MeeGo device (testapp will be set to the name you gave your project).
4. Click on the Manage device configurations link to display the MeeGo Device Configurations dialog.
5. Click on the Add button (top-right) and complete the fields so they resemble the screenshot below:
   File:QtCreator configure meego device.png
   You'll need to set Host Name to the IP address or domain name of the netbook, and enter the User Name and Password you used when you set up the netbook. The other options can be left at their defaults.
6. Click on the Test button to check the connection. If it's configured correctly, you should see a message like the one in the screenshot above ("Device configuration successful").
7. Click on OK to save your changes. This returns you to the Run Settings tab.
8. Select the new MeeGo netbook option from the Device Configuration drop-down.

Once you've completed this, you should be able to deploy and run the application on the netbook:

1. At the bottom-left of the Qt Creator window is a panel for selecting the build and run environments:
   
   Click on the computer monitor icon, then use the arrows to select testapp on MeeGo device from the Run drop-down. The Build drop-down can be left at Debug.
2. Click on the green arrow (the normal run arrow) to deploy the application and run it. This copies the application binary to the home folder of the user you specified in the SSH settings and runs it.
   If you can't see the application, it may be because it hasn't been given focus. You can use the zones icon in the toolbar to show the running application and select it.

Here's an example of what the application looks like running on a netbook:

Debug the application on the device

This works almost the same on a remote device as it does inside the Simulator.

1. Configure the remote device as explained above.
2. In Qt Creator, click on the Target settings (bottom left with a monitor icon). Ensure you have Build set to Debug and Run set to testapp on MeeGo device (the remote device).
3. Click on the green arrow overlaid with a bug to start the application remotely in debug mode.

If you used the same code as above, try clicking on the Click me button in the application (running on the netbook). The application should pause at the breakpoint; and in Qt Creator, the message variable should then be visible in the Locals and Watchers tab, set to "I have been well and truly clicked". (No screenshot this time, as Qt Creator looks the same as it does for local debugging.)