Home · All Classes · Grouped Classes · Annotated · Functions

Debugging Qtopia Applications

• Introduction
• Debugging Qtopia using gdb
• Build the Application with Debug Symbols
• Run the Debugging Environment
• Examining Application Crashes
• Remote Debugging
• qLog - Categorized Logging
• References

Introduction

This document describes useful techniques for debugging Qtopia and Qtopia applications. These techniques include:

• using the GNU Debugger, gdb, to monitor program execution and examine program status in the event of a crash
• using the GNU Debugger to remotely debug Qtopia running on an embedded device
• using the qLog function to output categorized logging of debug information.

Debugging Qtopia using gdb

This section provides instructions on how to debug desktop builds of Qtopia using gdb in a Linux environment.

Build the Application with Debug Symbols

To build an application with debug symbols:

• pass -debug to configure or add debug to the .pro file CONFIG settings as follows:

      CONFIG += debug

• build the application and install the application binary into the /opt/Qtopia/bin directory using the following commands:

      $ make clean
      $ make
      $ make install

Run the Debugging Environment

The runqtopia script supports running Qtopia in several different debugging environments. To run Qtopia in using gdb:

    runqtopia -runmode gdb

Once the gdb command prompt is displayed enter the following command to run Qtopia:

    (gdb) run

Alternatively to debug an application outside of the Qtopia environment:

    runqtopia -qpe theProgram -runmode gdb

Once the gdb command prompt is displayed enter the following command to run the application

    (gdb) set args -qws
    (gdb) run

Examining Application Crashes

If an application crashes, a core file is produced. Use the following commands to examine the core file contents:

    $ runqtopia -qpe theProgram -runmode gdb
    (gdb) core <core file>
    (gdb) backtrace full

Note: If no core file is generated run: ulimit -c 64000.

Remote Debugging

Remote debugging using the GNU Debugger is possible between machines of the same or different architecture. In both instances the procedure is the same. However, when cross-debugging you must ensure that gdb finds and loads the correct shared libraries for the remote architecture.

• Binaries on the remote and host machine must match.
• Debug symbols may be stripped from the binaries on the remote machine.

On the remote machine run:

    gdbserver :22222 qpe

On the host machine run:

1. Create symlink from /opt/Qtopia to the directory containing the Qtopia image.

       ln -s /path/to/Qtopia/image /opt/Qtopia

2. Run gdb and connect to the remote debugging session

       $ /opt/toolchains/.../bin/gdb /opt/Qtopia/bin/qpe
       (gdb) target remote REMOTE_IP_ADDRESS:22222
       (gdb) handle SIG32 nostop noprint
       (gdb) handle SIGTRAP nostop noprint
       (gdb) handle SIGPIPE nostop noprint
       (gdb) break main
       (gdb) cont

qLog - Categorized Logging

Qtopia provides the qLog(CategoryIdentifier) function for categorized logging, built on top of the QDebug class in Qtopia Core.

The following is an example of using a log message in the source code:

    #include <qtopialog.h>

    qLog(Type) << "Test";
    qLog(Type) << "string=" << str << ", int=" << i;

where Type is a category as defined in qtopialog-config.h.

The categories are declared by using one of the following macros:

• QLOG_DISABLE(CategoryIdentifier) - no logging code is generated.
• QLOG_ENABLE(CategoryIdentifier) - logging code is always generated and invoked.
• QTOPIA_LOG_OPTION(CategoryIdentifier) - logging code is always generated, invoked depending on the settings in the Log.conf settings file.
• QLOG_OPTION(CategoryIdentifier,expr) - logging code is always generated, invoked if expr is true at the time the log is issued, expr may be cached.
• QLOG_OPTION_VOLATILE(CategoryIdentifier,expr) - as above, but expr is not cached.

The CategoryIdentifier has _QLog appended within the macros, so it can be any identifier you choose. The associated type name might be a useful choice:

    qLog(QWidget) << "Created" << name;

For categories declared with QTOPIA_LOG_OPTION, the output of logging depends on the Log settings. As with all Qtopia settings files, the defaults are found in:

    /opt/Qtopia/etc/default/Trolltech/Log.conf

and these are overridden by settings in:

    $HOME/Settings/Trolltech/Log.conf

For example, the following enables logging messages related to the user interface:

    [UI]
    Enabled = 1
    Name[] = User interface
    Help[] = Anything to do with the user interface.

Note: Changes to the qLog only take effect when applications or the server restart.

To assist field testing, there is a Logging Settings application that uses the logread program to interface with the BusyBox syslogd output. To forward Qtopia's output to syslogd, use the logger program:

1. Start the syslog daemon in circular buffer mode. With the command:

       syslogd -C <buffersize>

   For example, to start syslogd with a 512 byte circular buffer use:

       syslogd -C 512

2. Start Qtopia with logging output redirected to the system log using:

       qpe 2>&1 | logger -t Qtopia

3. Start Logging Settings to view log messages.
4. Select Categories... from the context menu to select the log messages to enable/disable. Note: you will need to restart Qtopia for the changes to take effect.
5. Log messages can be viewed on the console by running:

       logread -f

For an example of a script that uses syslogd when starting Qtopia see <source>/devices/example/src/devtools/startup/qpe.sh

References

• Qt Debugging Techniques
• gdb: The GNU Project Debugger - (http://www.gnu.org/software/gdb/gdb.html)
• gdb Reference Card - (http://www.refcards.com/)