1
/****************************************************************************
3
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
** Contact: Nokia Corporation (qt-info@nokia.com)
6
** This file is part of the documentation of the Qt Toolkit.
8
** $QT_BEGIN_LICENSE:LGPL$
10
** Licensees holding valid Qt Commercial licenses may use this file in
11
** accordance with the Qt Commercial License Agreement provided with the
12
** Software or, alternatively, in accordance with the terms contained in
13
** a written agreement between you and Nokia.
15
** GNU Lesser General Public License Usage
16
** Alternatively, this file may be used under the terms of the GNU Lesser
17
** General Public License version 2.1 as published by the Free Software
18
** Foundation and appearing in the file LICENSE.LGPL included in the
19
** packaging of this file. Please review the following information to
20
** ensure the GNU Lesser General Public License version 2.1 requirements
21
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23
** In addition, as a special exception, Nokia gives you certain
24
** additional rights. These rights are described in the Nokia Qt LGPL
25
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
28
** GNU General Public License Usage
29
** Alternatively, this file may be used under the terms of the GNU
30
** General Public License version 3.0 as published by the Free Software
31
** Foundation and appearing in the file LICENSE.GPL included in the
32
** packaging of this file. Please review the following information to
33
** ensure the GNU General Public License version 3.0 requirements will be
34
** met: http://www.gnu.org/copyleft/gpl.html.
36
** If you are unsure which license is appropriate for your use, please
37
** contact the sales department at http://www.qtsoftware.com/contact.
40
****************************************************************************/
42
/****************************************************************************
44
** Qt Debugging Techniques
46
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
47
** Contact: Nokia Corporation (qt-info@nokia.com)
49
** This file is part of the Qt GUI Toolkit.
50
** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE
52
****************************************************************************/
56
\title Debugging Techniques
59
Here we present some useful hints to help you with debugging your
64
\section1 Configuring Qt for Debugging
66
When \l{Installation}{configuring Qt for installation}, it is possible
67
to ensure that it is built to include debug symbols that can make it
68
easier to track bugs in applications and libraries. However, on some
69
platforms, building Qt in debug mode will cause applications to be larger
72
\section2 Debugging in Mac OS X and Xcode
74
\section3 Debugging With/Without Frameworks
76
The basic stuff you need to know about debug libraries and
77
frameworks is found at developer.apple.com in:
78
\l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECDEBUGLIB}
79
{Apple Technicle Note TN2124} Qt follows that.
81
When you build Qt, frameworks are built by default, and inside the
82
framework you will find both a release and a debug version (e.g.,
83
QtCore and QtCore_debug). If you pass the \c{-no-framework} flag
84
when you build Qt, two dylibs are built for each Qt library (e.g.,
85
libQtCore.4.dylib and libQtCore_debug.4.dylib).
87
What happens when you link depends on whether you use frameworks
88
or not. We don't see a compelling reason to recommend one over the
91
\section4 With Frameworks:
93
Since the release and debug libraries are inside the framework,
94
the app is simply linked against the framework. Then when you run
95
in the debugger, you will get either the release version or the
96
debug version, depending on whether you set \c{DYLD_IMAGE_SUFFIX}.
97
If you don't set it, you get the release version by default (i.e.,
98
non _debug). If you set \c{DYLD_IMAGE_SUFFIX=_debug}, you get the
101
\section4 Without Frameworks:
103
When you tell \e{qmake} to generate a Makefile with the debug
104
config, it will link against the _debug version of the libraries
105
and generate debug symbols for the app. Running this program in
106
GDB will then work like running GDB on other platforms, and you
107
will be able to trace inside Qt.
109
\section3 Debug Symbols and Size
111
The amount of space taken up by debug symbols generated by GCC can
112
be excessively large. However, with the release of Xcode 2.3 it is
113
now possible to use Dwarf symbols which take up a significantly
114
smaller amount of space. To enable this feature when configuring
115
Qt, pass the \c{-dwarf-2} option to the configure script.
117
This is not enabled by default because previous versions of Xcode
118
will not work with the compiler flag used to implement this
119
feature. Mac OS X 10.5 will use dwarf-2 symbols by default.
121
dwarf-2 symbols contain references to source code, so the size of
122
the final debug application should compare favorably to a release
126
Although it is not necessary to build Qt with debug symbols to use the
127
other techniques described in this document, certain features are only
128
available when Qt is configured for debugging.
131
\section1 Command Line Options Recognized by Qt
133
When you run a Qt application, you can specify several
134
command-line options that can help with debugging. These are
135
recognized by QApplication.
138
\header \o Option \o Description
140
\o The application should never grab \link QWidget::grabMouse()
141
the mouse\endlink or \link QWidget::grabKeyboard() the
142
keyboard \endlink. This option is set by default when the
143
program is running in the \c gdb debugger under Linux.
145
\o Ignore any implicit or explicit \c{-nograb}. \c -dograb wins over
146
\c -nograb even when \c -nograb is last on the command line.
148
\o Runs the application in X synchronous mode. Synchronous mode
149
forces the X server to perform each X client request
150
immediately and not use buffer optimization. It makes the
151
program easier to debug and often much slower. The \c -sync
152
option is only valid for the X11 version of Qt.
155
\section1 Warning and Debugging Messages
157
Qt includes four global functions for writing out warning and debug
158
text. You can use them for the following purposes:
161
\o qDebug() is used for writing custom debug output.
162
\o qWarning() is used to report warnings and recoverable errors in
164
\o qCritical() is used for writing critical error mesages and
165
reporting system errors.
166
\o qFatal() is used for writing fatal error messages shortly before exiting.
169
If you include the <QtDebug> header file, the \c qDebug() function
170
can also be used as an output stream. For example:
172
\snippet doc/src/snippets/code/doc_src_debug.qdoc 0
174
The Qt implementation of these functions prints the text to the
175
\c stderr output under Unix/X11 and Mac OS X. With Windows, if it
176
is a console application, the text is sent to console; otherwise, it
177
is sent to the debugger. You can take over these functions by
178
installing a message handler using qInstallMsgHandler().
180
If the \c QT_FATAL_WARNINGS environment variable is set,
181
qWarning() exits after printing the warning message. This makes
182
it easy to obtain a backtrace in the debugger.
184
Both qDebug() and qWarning() are debugging tools. They can be
185
compiled away by defining \c QT_NO_DEBUG_OUTPUT and \c
186
QT_NO_WARNING_OUTPUT during compilation.
188
The debugging functions QObject::dumpObjectTree() and
189
QObject::dumpObjectInfo() are often useful when an application
190
looks or acts strangely. More useful if you use \l{QObject::setObjectName()}{object names}
191
than not, but often useful even without names.
193
\section1 Providing Support for the qDebug() Stream Operator
195
You can implement the stream operator used by qDebug() to provide
196
debugging support for your classes. The class that implements the
197
stream is \c QDebug. The functions you need to know about in \c
198
QDebug are \c space() and \c nospace(). They both return a debug
199
stream; the difference between them is whether a space is inserted
200
between each item. Here is an example for a class that represents
203
\snippet doc/src/snippets/qdebug/qdebugsnippet.cpp 0
205
Integration of custom types with Qt's meta-object system is covered
206
in more depth in the \l{Creating Custom Qt Types} document.
208
\section1 Debugging Macros
210
The header file \c <QtGlobal> contains some debugging macros and
213
Three important macros are:
215
\o \l{Q_ASSERT()}{Q_ASSERT}(cond), where \c cond is a boolean
216
expression, writes the warning "ASSERT: '\e{cond}' in file xyz.cpp, line
217
234" and exits if \c cond is false.
218
\o \l{Q_ASSERT_X()}{Q_ASSERT_X}(cond, where, what), where \c cond is a
219
boolean expression, \c where a location, and \c what a message,
220
writes the warning: "ASSERT failure in \c{where}: '\c{what}', file xyz.cpp, line 234"
221
and exits if \c cond is false.
222
\o \l{Q_CHECK_PTR()}{Q_CHECK_PTR}(ptr), where \c ptr is a pointer.
223
Writes the warning "In file xyz.cpp, line 234: Out of memory" and
224
exits if \c ptr is 0.
227
These macros are useful for detecting program errors, e.g. like this:
229
\snippet doc/src/snippets/code/doc_src_debug.qdoc 1
231
Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if
232
\c QT_NO_DEBUG is defined during compilation. For this reason,
233
the arguments to these macro should not have any side-effects.
234
Here is an incorrect usage of Q_CHECK_PTR():
236
\snippet doc/src/snippets/code/doc_src_debug.qdoc 2
238
If this code is compiled with \c QT_NO_DEBUG defined, the code in
239
the Q_CHECK_PTR() expression is not executed and \e alloc returns
240
an unitialized pointer.
242
The Qt library contains hundreds of internal checks that will
243
print warning messages when a programming error is detected. We
244
therefore recommend that you use a debug version of Qt when
245
developing Qt-based software.
247
\section1 Common Bugs
249
There is one bug that is so common that it deserves mention here:
250
If you include the Q_OBJECT macro in a class declaration and
251
run \link moc.html the meta-object compiler\endlink (\c{moc}),
252
but forget to link the \c{moc}-generated object code into your
253
executable, you will get very confusing error messages. Any link
254
error complaining about a lack of \c{vtbl}, \c{_vtbl}, \c{__vtbl}
255
or similar is likely to be a result of this problem.