Home · All Classes · Grouped Classes · Annotated · Functions

Debugging Qtopia Applications

• Introduction
• Using gdb
• Build the Application with Debug Symbols
• Run the Debugging Environment
• Debug Crashes
• qLog - Categorized Logging
• References

Introduction

Qtopia provides GNU Debugger gdb to monitor program execution and to examine program status in the event of a crash and the qLog function to provide categorized logging of debug information. The following sections describe how to used gdb in a Linux environment and how to call implement the qLog function.

Using gdb

This section provides instructions on how to debug Qtopia applications using igdb 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

To run the debugging environmnent:

• start the virtual framebuffer environment
• start the Qtopia environment
• start gdb

using the following commands:

    $ qvfb &
    $ qpe &
    $ gdb theProgram
    (gdb) r # run

Alternatively to debug an application outside of the Qtopia environment:

• start the virtual framebuffer environment
• ensure the application hooks into the virtual frame buffer

using the following commands:

    $ qvfb &
    $ gdb theProgram
    (gdb) set args - qws # we need this to hook to the virtual frame buffer.
    (gdb) list # if you want to list the main.cpp file
    (gdb) b 6 # break at line six
    (gdb) r # run
    (gdb) s # step into
    (gdb) r # continue

Debug Crashes

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

    $ gdb theapplication core
    (gdb) backtrace full

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)