<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt - 3.3.8 - espenr - 2499/qt - x11 - free - 3.3.8/doc/debug.doc:36 -->
< html >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=ISO-8859-1" >
< title > Debugging Techniques< / title >
< style type = "text/css" > < ! - -
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
-->< / style >
< / head >
< body >
< table border = "0" cellpadding = "0" cellspacing = "0" width = "100%" >
< tr bgcolor = "#E5E5E5" >
< td valign = center >
< a href = "index.html" >
< font color = "#004faf" > Home< / font > < / a >
| < a href = "classes.html" >
< font color = "#004faf" > All Classes< / font > < / a >
| < a href = "mainclasses.html" >
< font color = "#004faf" > Main Classes< / font > < / a >
| < a href = "annotated.html" >
< font color = "#004faf" > Annotated< / font > < / a >
| < a href = "groups.html" >
< font color = "#004faf" > Grouped Classes< / font > < / a >
| < a href = "functions.html" >
< font color = "#004faf" > Functions< / font > < / a >
< / td >
< td align = "right" valign = "center" > < img src = "logo32.png" align = "right" width = "64" height = "32" border = "0" > < / td > < / tr > < / table > < h1 align = center > Debugging Techniques< / h1 >
< p > Here we present some useful hints to debugging your TQt-based software.
< p > < h2 > Command Line Options
< / h2 >
< a name = "1" > < / a > < p > When you run a TQt program you can specify several command line options
that can help with debugging.
< p > < center > < table cellpadding = "4" cellspacing = "2" border = "0" >
< tr bgcolor = "#a2c511" > < th valign = "top" > Option < th valign = "top" > Result
< tr bgcolor = "#f0f0f0" > < td valign = "top" > -nograb
< td valign = "top" > The application should never grab < a href = "tqwidget.html#grabMouse" > the mouse< / a > or < a href = "tqwidget.html#grabKeyboard" > the
keyboard< / a > . This option is set by default when the
program is running in the < tt > gdb< / tt > debugger under Linux.
< tr bgcolor = "#d0d0d0" > < td valign = "top" > -dograb
< td valign = "top" > Ignore any implicit or explicit -nograb. -dograb wins over
-nograb even when -nograb is last on the command line.
< tr bgcolor = "#f0f0f0" > < td valign = "top" > -sync
< td valign = "top" > 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 TQt.
< / table > < / center >
< p > < h2 > Warning and Debugging Messages
< / h2 >
< a name = "2" > < / a > < p > TQt includes three global functions for writing out warning and debug
text.
< ul >
< li > < a href = "ntqapplication.html#qDebug" > tqDebug()< / a > for writing debug output for testing etc.
< li > < a href = "ntqapplication.html#qWarning" > tqWarning()< / a > for writing warning output when program
errors occur.
< li > < a href = "ntqapplication.html#qFatal" > tqFatal()< / a > for writing fatal error messages
and exiting.
< / ul >
< p > The TQt implementation of these functions prints the text to the < tt > stderr< / tt >
output under Unix/X11 and to the debugger under Windows. You can
take over these functions by installing a message handler;
< a href = "ntqapplication.html#qInstallMsgHandler" > qInstallMsgHandler()< / a > .
< p > The debugging functions < a href = "tqobject.html#dumpObjectTree" > TQObject::dumpObjectTree< / a > () and < a href = "tqobject.html#dumpObjectInfo" > TQObject::dumpObjectInfo< / a > () 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.
< p > < h2 > Debugging Macros
< / h2 >
< a name = "3" > < / a > < p > The header file < a href = "qglobal-h.html" > ntqglobal.h< / a > contains many debugging macros and
< tt > #define< / tt > s.
< p > Two important macros are:
< ul >
< li > < a href = "ntqapplication.html#Q_ASSERT" > Q_ASSERT(b)< / a > where b is a boolean
expression, writes the warning: "ASSERT: 'b' in file file.cpp (234)"
if b is FALSE.
< li > < a href = "ntqapplication.html#TQ_CHECK_PTR" > TQ_CHECK_PTR(p)< / a > where p is a pointer.
Writes the warning "In file file.cpp, line 234: Out of memory" if p is
0.
< / ul >
< p > These macros are useful for detecting program errors, e.g. like this:
< pre >
char *alloc( int size )
{
< a href = "ntqapplication.html#Q_ASSERT" > Q_ASSERT< / a > ( size > 0 );
char *p = new char[size];
< a href = "ntqapplication.html#TQ_CHECK_PTR" > TQ_CHECK_PTR< / a > ( p );
return p;
}
< / pre >
< p > If you define the flag QT_FATAL_ASSERT, Q_ASSERT will call fatal()
instead of warning(), so a failed assertion will cause the program to
exit after printing the error message.
< p > Note that the Q_ASSERT macro is a null expression if < tt > QT_CHECK_STATE< / tt > (see
below) is not defined. Any code in it will simply not be
executed. Similarly TQ_CHECK_PTR is a null expression if < tt > QT_CHECK_NULL< / tt > is
not defined. Here is an example of how you should < em > not< / em > use Q_ASSERT and
TQ_CHECK_PTR:
< p > < pre >
char *alloc( int size )
{
char *p;
< a href = "ntqapplication.html#TQ_CHECK_PTR" > TQ_CHECK_PTR< / a > ( p = new char[size] ); // WRONG!
return p;
}
< / pre >
< p > The problem is tricky: < em > p< / em > is set to a sane value only as long as the
correct checking flags are defined. If this code is compiled without
the QT_CHECK_NULL flag defined, the code in the TQ_CHECK_PTR expression is
not executed (correctly, since it's only a debugging aid) and < em > alloc< / em >
returns a wild pointer.
< p > The TQt library contains hundreds of internal checks that will print
warning messages when some error is detected.
< p > The tests for sanity and the resulting warning messages inside TQt are
conditional, based on the state of various debugging flags:
< center > < table cellpadding = "4" cellspacing = "2" border = "0" >
< tr bgcolor = "#a2c511" > < th valign = "top" > Flag < th valign = "top" > Meaning
< tr bgcolor = "#d0d0d0" > < td valign = "top" > QT_CHECK_STATE < td valign = "top" > Check for consistent/expected object state
< tr bgcolor = "#f0f0f0" > < td valign = "top" > QT_CHECK_RANGE < td valign = "top" > Check for variable range errors
< tr bgcolor = "#d0d0d0" > < td valign = "top" > QT_CHECK_NULL < td valign = "top" > Check for dangerous null pointers
< tr bgcolor = "#f0f0f0" > < td valign = "top" > QT_CHECK_MATH < td valign = "top" > Check for dangerous math, e.g. division by 0
< tr bgcolor = "#d0d0d0" > < td valign = "top" > TQT_NO_CHECK < td valign = "top" > Turn off all QT_CHECK_... flags
< tr bgcolor = "#f0f0f0" > < td valign = "top" > QT_DEBUG < td valign = "top" > Enable debugging code
< tr bgcolor = "#d0d0d0" > < td valign = "top" > TQT_NO_DEBUG < td valign = "top" > Turn off QT_DEBUG flag
< / table > < / center >
< p > By default, both QT_DEBUG and all the QT_CHECK flags are on. To turn
off QT_DEBUG, define TQT_NO_DEBUG. To turn off the QT_CHECK flags,
define TQT_NO_CHECK.
< p > Example:
< pre >
void f( char *p, int i )
{
#if defined(QT_CHECK_NULL)
if ( p == 0 )
< a href = "ntqapplication.html#qWarning" > tqWarning< / a > ( "f: Null pointer not allowed" );
#endif
#if defined(QT_CHECK_RANGE)
if ( i < 0 )
< a href = "ntqapplication.html#qWarning" > tqWarning< / a > ( "f: The index cannot be negative" );
#endif
}
< / pre >
< p > < h2 > Common bugs
< / h2 >
< a name = "4" > < / a > < p > There is one bug that is so common that it deserves mention here: If
you include the < a href = "metaobjects.html#TQ_OBJECT" > TQ_OBJECT< / a > macro in a class declaration and run the
< a href = "moc.html" > moc< / a > , but forget to link the < a href = "moc.html#moc" > moc< / a > -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 >
<!-- eof -->
< p > < address > < hr > < div align = center >
< table width = 100% cellspacing = 0 border = 0 > < tr >
< td > Copyright © 2007
< a href = "troll.html" > Trolltech< / a > < td align = center > < a href = "trademarks.html" > Trademarks< / a >
< td align = right > < div align = right > TQt 3.3.8< / div >
< / table > < / div > < / address > < / body >
< / html >
