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