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