<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qt-4.3/doc/src/debug.qdoc -->
<head>
<title>Debugging Techniques</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">Debugging Techniques<br /><small></small></h1>
<p>Here we present some useful hints to help you with debugging your Qt-based software.</p>
<a name="command-line-options-recognized-by-qt"></a>
<h2>Command-Line Options Recognized by Qt</h2>
<p>When you run a Qt application, you can specify several command-line options that can help with debugging. These are recognized by <a href="gui/QApplication.html"><tt>QApplication</tt></a>.</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Option</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><tt>-nograb</tt></td><td>The application should never grab the mouse</tt> or the keyboard</tt>. This option is set by default when the program is running in the <tt>gdb</tt> debugger under Linux.</td></tr>
<tr valign="top" class="even"><td><tt>-dograb</tt></td><td>Ignore any implicit or explicit <tt>-nograb</tt>. <tt>-dograb</tt> wins over <tt>-nograb</tt> even when <tt>-nograb</tt> is last on the command line.</td></tr>
<tr valign="top" class="odd"><td><tt>-sync</tt></td><td>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 <tt>-sync</tt> option is only valid for the X11 version of Qt.</td></tr>
</table></p>
<a name="warning-and-debugging-messages"></a>
<h2>Warning and Debugging Messages</h2>
<p>Qt includes four global functions for writing out warning and debug text. You can use them for the following purposes:</p>
<ul>
<li>qDebug() is used for writing custom debug output.</li>
<li>qWarning() is used to report warnings and recoverable errors in your application.</li>
<li>qCritical() is used for writing critical error mesages and reporting system errors.</li>
<li>qFatal() is used for writing fatal error messages shortly before exiting.</li>
</ul>
<p>If you include the <QtDebug> header file, the <tt>qDebug()</tt> function can also be used as an output stream. For example:</p>
<pre> qDebug() << "Widget" << widget << "at position" << widget->pos();</pre>
<p>The Qt implementation of these functions prints the text to the <tt>stderr</tt> 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().</p>
<p>If the <tt>QT_FATAL_WARNINGS</tt> environment variable is set, qWarning() exits after printing the warning message. This makes it easy to obtain a backtrace in the debugger.</p>
<p>Both qDebug() and qWarning() are debugging tools. They can be compiled away by defining <tt>QT_NO_DEBUG_OUTPUT</tt> and <tt>QT_NO_WARNING_OUTPUT</tt> during compilation.</p>
<p>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</tt> than not, but often useful even without names.</p>
<a name="providing-support-for-the-qdebug-stream-operator"></a>
<h2>Providing Support for the qDebug() Stream Operator</h2>
<p>You can implement the stream operator used by qDebug() to provide debugging support for your classes. The class that implements the stream is <tt>QDebug</tt>. The functions you need to know about in <tt>QDebug</tt> are <tt>space()</tt> and <tt>nospace()</tt>. 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.</p>
<pre> QDebug operator<<(QDebug dbg, const Coordinate &c)
{
dbg.nospace() << "(" << c.x() << ", " << c.y() << ")";
return dbg.space();
}</pre>
<a name="debugging-macros"></a>
<h2>Debugging Macros</h2>
<p>The header file <tt><QtGlobal></tt> contains some debugging macros and <tt>#define</tt>s.</p>
<p>Three important macros are:</p>
<ul>
<li>Q_ASSERT(cond), where <tt>cond</tt> is a boolean expression, writes the warning "ASSERT: '<i>cond</i>' in file xyz.cpp, line 234" and exits if <tt>cond</tt> is false.</li>
<li>Q_ASSERT_X(cond, where, what), where <tt>cond</tt> is a boolean expression, <tt>where</tt> a location, and <tt>what</tt> a message, writes the warning: "ASSERT failure in <tt>where</tt>: '<tt>what</tt>', file xyz.cpp, line 234" and exits if <tt>cond</tt> is false.</li>
<li>Q_CHECK_PTR(ptr), where <tt>ptr</tt> is a pointer. Writes the warning "In file xyz.cpp, line 234: Out of memory" and exits if <tt>ptr</tt> is 0.</li>
</ul>
<p>These macros are useful for detecting program errors, e.g. like this:</p>
<pre> char *alloc(int size)
{
Q_ASSERT(size > 0);
char *ptr = new char[size];
Q_CHECK_PTR(ptr);
return ptr;
}</pre>
<p>Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if <tt>QT_NO_DEBUG</tt> 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():</p>
<pre> char *alloc(int size)
{
char *ptr;
Q_CHECK_PTR(ptr = new char[size]); <span class="comment">// WRONG</span>
return ptr;
}</pre>
<p>If this code is compiled with <tt>QT_NO_DEBUG</tt> defined, the code in the Q_CHECK_PTR() expression is not executed and <i>alloc</i> returns an unitialized pointer.</p>
<p>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.</p>
<a name="common-bugs"></a>
<h2>Common Bugs</h2>
<p>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 <a href="moc.html">the meta-object compiler</tt></a> (<tt>moc</tt>), but forget to link the <tt>moc</tt>-generated object code into your executable, you will get very confusing error messages. Any link error complaining about a lack of <tt>vtbl</tt>, <tt>_vtbl</tt>, <tt>__vtbl</tt> or similar is likely to be a result of this problem.</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
287
