From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/debug.html | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 doc/html/debug.html (limited to 'doc/html/debug.html') diff --git a/doc/html/debug.html b/doc/html/debug.html new file mode 100644 index 000000000..f3bb5cd1b --- /dev/null +++ b/doc/html/debug.html @@ -0,0 +1,171 @@ + + + + + +Debugging Techniques + + + + + + + +

Debugging Techniques

+ + + +

Here we present some useful hints to debugging your TQt-based software. +

Command Line Options +

When you run a TQt program you can specify several command line options +that can help with debugging. +

Option	Result +
-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 TQt. +

Warning and Debugging Messages +

TQt includes three global functions for writing out warning and debug +text. +

qDebug() for writing debug output for testing etc. +
qWarning() for writing warning output when program +errors occur. +
qFatal() for writing fatal error messages +and exiting. +

The TQt implementation of these functions prints the text to the stderr +output under Unix/X11 and to the debugger under Windows. You can +take over these functions by installing a message handler; +qInstallMsgHandler(). +

The debugging functions TQObject::dumpObjectTree() and TQObject::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. +

Debugging Macros +

The header file qglobal.h contains many debugging macros and +#defines. +

Two important macros are: +

Q_ASSERT(b) where b is a boolean +expression, writes the warning: "ASSERT: 'b' in file file.cpp (234)" +if b is FALSE. +
Q_CHECK_PTR(p) where p is a pointer. +Writes the warning "In file file.cpp, line 234: Out of memory" if p is +0. +

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

+  char *alloc( int size )
+  {
+      Q_ASSERT( size > 0 );
+      char *p = new char[size];
+      Q_CHECK_PTR( p );
+      return 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. +

Note that the Q_ASSERT macro is a null expression if QT_CHECK_STATE (see +below) is not defined. Any code in it will simply not be +executed. Similarly Q_CHECK_PTR is a null expression if QT_CHECK_NULL is +not defined. Here is an example of how you should not use Q_ASSERT and +Q_CHECK_PTR: +

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

+ +

The problem is tricky: p 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 Q_CHECK_PTR expression is +not executed (correctly, since it's only a debugging aid) and alloc +returns a wild pointer. +

The TQt library contains hundreds of internal checks that will print +warning messages when some error is detected. +

The tests for sanity and the resulting warning messages inside TQt are +conditional, based on the state of various debugging flags: +

Flag	Meaning +
QT_CHECK_STATE	Check for consistent/expected object state +
QT_CHECK_RANGE	Check for variable range errors +
QT_CHECK_NULL	Check for dangerous null pointers +
QT_CHECK_MATH	Check for dangerous math, e.g. division by 0 +
QT_NO_CHECK	Turn off all QT_CHECK_... flags +
QT_DEBUG	Enable debugging code +
QT_NO_DEBUG	Turn off QT_DEBUG flag +

By default, both QT_DEBUG and all the QT_CHECK flags are on. To turn +off QT_DEBUG, define QT_NO_DEBUG. To turn off the QT_CHECK flags, +define QT_NO_CHECK. +

Example: +

+  void f( char *p, int i )
+  {
+  #if defined(QT_CHECK_NULL)
+      if ( p == 0 )
+          qWarning( "f: Null pointer not allowed" );
+  #endif
+
+  #if defined(QT_CHECK_RANGE)
+      if ( i < 0 )
+          qWarning( "f: The index cannot be negative" );
+  #endif
+  }
+

+ +

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 +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. +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1