Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Debugging Qt Extended Applications

Customizing Log Output

References

Introduction

This document describes useful techniques for debugging Qt Extended and Qt Extended 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 Qt Extended running on an embedded device
using the qLog function to output categorized logging of debug information.

Debugging Qt Extended using gdb

This section provides instructions on how to debug desktop builds of Qt Extended 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 qbuild.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:
```
    $QPEDIR/bin/qbuild
    $QPEDIR/bin/qbuild image
```

Run the Debugging Environment

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

    $QPEDIR/bin/runqtopia -runmode gdb

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

    (gdb) run

Alternatively to debug an application outside of the Qt Extended 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:

Create symlink from /opt/Qtopia to the directory containing the Qt Extended image.
```
    ln -s /path/to/Qtopia/image /opt/Qtopia
```

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

Qt Extended provides the qLog(CategoryIdentifier) function for categorized logging, built on top of the QDebug class in Qt for Embedded Linux.

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 Qt Extended 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 Log.conf are not reflected in running applications immediately. A QCop message (QPE/System LogConfChanged()) can be sent which will cause all applications to re-read Log.conf and re-process the categories created with QTOPIA_LOG_OPTION.

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

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
```
Start Qt Extended with logging output redirected to the system log using:
```
    qpe 2>&1 | logger -t Qtopia
```
Start Logging Settings to view log messages.
Select Categories... from the context menu to select the log messages to enable/disable. The effects are immediate for all categories created with QTOPIA_LOG_OPTION.
Log messages can be viewed on the console by running:
```
    logread -f
```

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

Customizing Log Output

The formatting of log messages can be modified globally by setting MessageHandler/Format in the Log2 settings file. This can be used to add additional information to all logged messages suitable for log analysis tools. A C-style format string determines the output format to be used, with the following specifiers being supported:

%s - The text of the message being logged.
%t - A timestamp, in milliseconds, since a fixed point in the past. All processes use the same fixed point so that timestamps can be compared between processes.
%p - The PID (process identifier) of the current process.
%n - The name of the current process as returned by QCoreApplication::applicationName(), or if a QCoreApplication has not yet been created, the filename of the process's executable.

For example, if $HOME/Settings/Trolltech/Log2.conf contains the following text:

    [MessageHandler]
    Format = %t %p %n: %s

Log messages will be formatted as in the following example:

Code	Output
`qLog(UI) << "Creating main user interface";`	`212 18755 myapp: UI : Creating main user interface`
`MainWindow win;`
`qLog(UI) << "Done creating main user interface";`	`320 18755 myapp: UI : Done creating main user interface`

As with changes to the qLog categories, sending the QPE/System LogConfChanged() QCop message is necessary for changes to log formatting to take effect in running applications.

References

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

Trademarks

Qt Extended 4.4.3