Debugging Techniques

Debugging Macros

The header file <QtGlobal> contains some debugging macros and #defines.

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.