|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# Debugging Techniques

Here we present some useful hints to help you with debugging your Qt-based software.

## Command-Line Options Recognized by Qt

When you run a Qt application, you can specify several command-line options that can help with debugging. These are recognized by QApplication.

Option | Description
--- | ---
`-nograb` | The application should never grab the mouse or the keyboard. This option is set by default when the program is running in the `gdb` debugger under Linux.
`-dograb` | Ignore any implicit or explicit `-nograb`. `-dograb` wins over `-nograb` even when `-nograb` is last on the command line.
`-sync` | Runs the application in X synchronous mode. Synchronous mode forces the X server to perform each X client request immediately and not use buffer optimization. It makes the program easier to debug and often much slower. The `-sync` option is only valid for the X11 version of Qt.

## Warning and Debugging Messages

Qt includes four global functions for writing out warning and debug text. You can use them for the following purposes:

- qDebug() is used for writing custom debug output.
- qWarning() is used to report warnings and recoverable errors in your application.
- qCritical() is used for writing critical error mesages and reporting system errors.
- qFatal() is used for writing fatal error messages shortly before exiting.

If you include the <QtDebug> header file, the `qDebug()` function can also be used as an output stream. For example:

     qDebug() << "Widget" << widget << "at position" << widget->pos();

The Qt implementation of these functions prints the text to the `stderr` output under Unix/X11 and Mac OS X, and to the debugger under Windows. You can take over these functions by installing a message handler using qInstallMsgHandler().

If the `QT_FATAL_WARNINGS` environment variable is set, qWarning() exits after printing the warning message. This makes it easy to obtain a backtrace in the debugger.

Both qDebug() and qWarning() are debugging tools. They can be compiled away by defining `QT_NO_DEBUG_OUTPUT` and `QT_NO_WARNING_OUTPUT` during compilation.

The debugging functions QObject::dumpObjectTree() and QObject::dumpObjectInfo() are often useful when an application looks or acts strangely. More useful if you use object names than not, but often useful even without names.

## Providing Support for the qDebug() Stream Operator

You can implement the stream operator used by qDebug() to provide debugging support for your classes. The class that implements the stream is `QDebug`. The functions you need to know about in `QDebug` are `space()` and `nospace()`. They both return a debug stream; the difference between them is whether a space is inserted between each item. Here is an example for a class that represents a 2D coordinate.

     QDebug operator<<(QDebug dbg, const Coordinate &c)
     {
         dbg.nospace() << "(" << c.x() << ", " << c.y() << ")";

         return dbg.space();
     }

## Debugging Macros

The header file `<QtGlobal>` contains some debugging macros and `#define`s.

Three important macros are:

- Q_ASSERT(cond), where `cond` is a boolean expression, writes the warning "ASSERT: 'cond' in file xyz.cpp, line 234" and exits if `cond` is false.
- Q_ASSERT_X(cond, where, what), where `cond` is a boolean expression, `where` a location, and `what` a message, writes the warning: "ASSERT failure in `where`: '`what`', file xyz.cpp, line 234" and exits if `cond` is false.
- Q_CHECK_PTR(ptr), where `ptr` is a pointer. Writes the warning "In file xyz.cpp, line 234: Out of memory" and exits if `ptr` is 0.

These macros are useful for detecting program errors, e.g. like this:

     char *alloc(int size)
     {
         Q_ASSERT(size > 0);
         char *ptr = new char[size];
         Q_CHECK_PTR(ptr);
         return ptr;
     }

Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if `QT_NO_DEBUG` is defined during compilation. For this reason, the arguments to these macro should not have any side-effects. Here is an incorrect usage of Q_CHECK_PTR():

     char *alloc(int size)
     {
         char *ptr;
         Q_CHECK_PTR(ptr = new char[size]);  // WRONG
         return ptr;
     }

If this code is compiled with `QT_NO_DEBUG` defined, the code in the Q_CHECK_PTR() expression is not executed and alloc returns an unitialized pointer.

The Qt library contains hundreds of internal checks that will print warning messages when a programming error is detected. We therefore recommend that you use a debug version of Qt when developing Qt-based software.

## Common Bugs

There is one bug that is so common that it deserves mention here: If you include the Q_OBJECT macro in a class declaration and run the meta-object compiler (`moc`), but forget to link the `moc`-generated object code into your executable, you will get very confusing error messages. Any link error complaining about a lack of `vtbl`, `_vtbl`, `__vtbl` or similar is likely to be a result of this problem.