SDK/Docs/1.1/Debugging with Qt Creator

Revision as of 14:15, 27 October 2010

This is a very rough working draft, in progress (2010-10-25); most of the screenshots are wrong

This is a brief introduction to debugging Qt applications running on a remote MeeGo device, using Qt Creator. The instructions will work with any kind of remote MeeGo device, real or emulated.

Prerequisites

You will need gdb to be installed before you can do any debugging with Qt Creator. On Linux, use the package manager to install it; for example, on Fedora:

sudo yum install gdb

On MeeGo (useful if you're using Qt Creator from a chroot):

zypper install gdb

Create a project with Qt Creator

Start Qt Creator (meego-sdk-qt-creator) and setup a project:

1. Create a new project (File > New File or Project). Under Projects, select Qt C++ Project then Mobile Qt Application. Click Choose....
2. In the Location section, enter helloworld for the name; choose a directory to save it to. Click on Next >.
3. In the Qt Versions section, make sure the MeeGo 4.7.0 version of Qt is selected and click Next >.
4. In the Details section, accept the defaults and click Next >.
5. In the Project Management section, click Finish.

Next write some code:

1. Open the Forms folder and double-click mainwindow.ui to open it in the graphical forms editor.
2. Drag a label from the list of widgets on the left-hand side of the forms editor (under Display Widgets) and drop it into the editable area.
3. Change the text to something else ("Hello world" works well).

Configure the project for debugging

First, ensure that debugging is enabled for the version of Qt in use:

1. Click on the Projects button in the left-hand panel.
2. Under General, click on the Manage button next to Qt Version.
3. Select the Qt version you are using: use the MeeGo Qt version for your particular target (in this case, MeeGo 4.7.0).
4. Click on the Rebuild button next to Debugging helpers (near the bottom of the dialog box). This builds the debugging helper for this version of Qt.

Next, you need something to debug. For example, add a Push Button to the form:

Then add 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();

private:
    Ui::MainWindow *ui;

// our new handler
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::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 22 after message is initialized.)

To put Qt Creator into debug mode, click on Debug/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 to change the configuration, so that Qt with debugging enabled is used to run the project.

1. In the left-hand panel, click on Projects.
2. Under Build Settings, select Debug from the drop-down box next to Edit build configuration.
3. From the Build menu, select Rebuild all. This recompiles the project using the debug-enabled Qt.

Setup emulator

???

Run and debug the project

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

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 http://doc.qt.nokia.com/qtcreator-snapshot/creator-debugging.html.

Prepare the remote 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:

Note: If you are using N900 for debugging, installing OpenSSH or gdbserver is not required.

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 zypper 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 remote device:

   sudo zypper install gdb-gdbserver

Run the application on the device

In Qt Creator:

1. From the Tools menu, select Options.
2. Select the Projects section.
3. Click on the MeeGo Device Configurations tab.
4. Click on the Add button to start adding a new configuration.
5. Click on the Add button (top-right) and complete the fields so they resemble the screenshot below:
   
   You'll need to set Host Name to the IP address or domain name of the device, and enter the User Name and Password you used when you set up the device. 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 this:
   
7. Click on OK to save your changes.










8. Select the option corresponding to the device from the Device Configuration drop-down.

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

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

Debugging on the remote device is as simple as debugging locally.

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 because Qt Creator looks the same as it does for local debugging.)