summaryrefslogtreecommitdiffstats
path: root/doc/src/debug.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/debug.qdoc')
-rw-r--r--doc/src/debug.qdoc256
1 files changed, 256 insertions, 0 deletions
diff --git a/doc/src/debug.qdoc b/doc/src/debug.qdoc
new file mode 100644
index 0000000..da5a82f
--- /dev/null
+++ b/doc/src/debug.qdoc
@@ -0,0 +1,256 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/****************************************************************************
+**
+** Qt Debugging Techniques
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the Qt GUI Toolkit.
+** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE
+**
+****************************************************************************/
+
+/*!
+ \page debug.html
+ \title Debugging Techniques
+ \ingroup buildsystem
+
+ Here we present some useful hints to help you with debugging your
+ Qt-based software.
+
+ \tableofcontents
+
+ \section1 Configuring Qt for Debugging
+
+ When \l{Installation}{configuring Qt for installation}, it is possible
+ to ensure that it is built to include debug symbols that can make it
+ easier to track bugs in applications and libraries. However, on some
+ platforms, building Qt in debug mode will cause applications to be larger
+ than desirable.
+
+ \section2 Debugging in Mac OS X and Xcode
+
+ \section3 Debugging With/Without Frameworks
+
+ The basic stuff you need to know about debug libraries and
+ frameworks is found at developer.apple.com in:
+ \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECDEBUGLIB}
+ {Apple Technicle Note TN2124} Qt follows that.
+
+ When you build Qt, frameworks are built by default, and inside the
+ framework you will find both a release and a debug version (e.g.,
+ QtCore and QtCore_debug). If you pass the \c{-no-framework} flag
+ when you build Qt, two dylibs are built for each Qt library (e.g.,
+ libQtCore.4.dylib and libQtCore_debug.4.dylib).
+
+ What happens when you link depends on whether you use frameworks
+ or not. We don't see a compelling reason to recommend one over the
+ other.
+
+ \section4 With Frameworks:
+
+ Since the release and debug libraries are inside the framework,
+ the app is simply linked against the framework. Then when you run
+ in the debugger, you will get either the release version or the
+ debug version, depending on whether you set \c{DYLD_IMAGE_SUFFIX}.
+ If you don't set it, you get the release version by default (i.e.,
+ non _debug). If you set \c{DYLD_IMAGE_SUFFIX=_debug}, you get the
+ debug version.
+
+ \section4 Without Frameworks:
+
+ When you tell \e{qmake} to generate a Makefile with the debug
+ config, it will link against the _debug version of the libraries
+ and generate debug symbols for the app. Running this program in
+ GDB will then work like running GDB on other platforms, and you
+ will be able to trace inside Qt.
+
+ \section3 Debug Symbols and Size
+
+ The amount of space taken up by debug symbols generated by GCC can
+ be excessively large. However, with the release of Xcode 2.3 it is
+ now possible to use Dwarf symbols which take up a significantly
+ smaller amount of space. To enable this feature when configuring
+ Qt, pass the \c{-dwarf-2} option to the configure script.
+
+ This is not enabled by default because previous versions of Xcode
+ will not work with the compiler flag used to implement this
+ feature. Mac OS X 10.5 will use dwarf-2 symbols by default.
+
+ dwarf-2 symbols contain references to source code, so the size of
+ the final debug application should compare favorably to a release
+ build.
+
+ \omit
+ Although it is not necessary to build Qt with debug symbols to use the
+ other techniques described in this document, certain features are only
+ available when Qt is configured for debugging.
+ \endomit
+
+ \section1 Command Line Options Recognized by Qt
+
+ When you run a Qt application, you can specify several
+ command-line options that can help with debugging. These are
+ recognized by QApplication.
+
+ \table
+ \header \o Option \o Description
+ \row \o \c -nograb
+ \o The application should never grab \link QWidget::grabMouse()
+ the mouse\endlink or \link QWidget::grabKeyboard() the
+ keyboard \endlink. This option is set by default when the
+ program is running in the \c gdb debugger under Linux.
+ \row \o \c -dograb
+ \o Ignore any implicit or explicit \c{-nograb}. \c -dograb wins over
+ \c -nograb even when \c -nograb is last on the command line.
+ \row \o \c -sync
+ \o 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 \c -sync
+ option is only valid for the X11 version of Qt.
+ \endtable
+
+ \section1 Warning and Debugging Messages
+
+ Qt includes four global functions for writing out warning and debug
+ text. You can use them for the following purposes:
+
+ \list
+ \o qDebug() is used for writing custom debug output.
+ \o qWarning() is used to report warnings and recoverable errors in
+ your application.
+ \o qCritical() is used for writing critical error mesages and
+ reporting system errors.
+ \o qFatal() is used for writing fatal error messages shortly before exiting.
+ \endlist
+
+ If you include the <QtDebug> header file, the \c qDebug() function
+ can also be used as an output stream. For example:
+
+ \snippet doc/src/snippets/code/doc_src_debug.qdoc 0
+
+ The Qt implementation of these functions prints the text to the
+ \c stderr output under Unix/X11 and Mac OS X. With Windows, if it
+ is a console application, the text is sent to console; otherwise, it
+ is sent to the debugger. You can take over these functions by
+ installing a message handler using qInstallMsgHandler().
+
+ If the \c QT_FATAL_WARNINGS environment variable is set,
+ qWarning() exits after printing the warning message. This makes
+ it easy to obtain a backtrace in the debugger.
+
+ Both qDebug() and qWarning() are debugging tools. They can be
+ compiled away by defining \c QT_NO_DEBUG_OUTPUT and \c
+ QT_NO_WARNING_OUTPUT during compilation.
+
+ The debugging functions QObject::dumpObjectTree() and
+ QObject::dumpObjectInfo() are often useful when an application
+ looks or acts strangely. More useful if you use \l{QObject::setObjectName()}{object names}
+ than not, but often useful even without names.
+
+ \section1 Providing Support for the qDebug() Stream Operator
+
+ You can implement the stream operator used by qDebug() to provide
+ debugging support for your classes. The class that implements the
+ stream is \c QDebug. The functions you need to know about in \c
+ QDebug are \c space() and \c nospace(). They both return a debug
+ stream; the difference between them is whether a space is inserted
+ between each item. Here is an example for a class that represents
+ a 2D coordinate.
+
+ \snippet doc/src/snippets/qdebug/qdebugsnippet.cpp 0
+
+ Integration of custom types with Qt's meta-object system is covered
+ in more depth in the \l{Creating Custom Qt Types} document.
+
+ \section1 Debugging Macros
+
+ The header file \c <QtGlobal> contains some debugging macros and
+ \c{#define}s.
+
+ Three important macros are:
+ \list
+ \o \l{Q_ASSERT()}{Q_ASSERT}(cond), where \c cond is a boolean
+ expression, writes the warning "ASSERT: '\e{cond}' in file xyz.cpp, line
+ 234" and exits if \c cond is false.
+ \o \l{Q_ASSERT_X()}{Q_ASSERT_X}(cond, where, what), where \c cond is a
+ boolean expression, \c where a location, and \c what a message,
+ writes the warning: "ASSERT failure in \c{where}: '\c{what}', file xyz.cpp, line 234"
+ and exits if \c cond is false.
+ \o \l{Q_CHECK_PTR()}{Q_CHECK_PTR}(ptr), where \c ptr is a pointer.
+ Writes the warning "In file xyz.cpp, line 234: Out of memory" and
+ exits if \c ptr is 0.
+ \endlist
+
+ These macros are useful for detecting program errors, e.g. like this:
+
+ \snippet doc/src/snippets/code/doc_src_debug.qdoc 1
+
+ Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if
+ \c 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():
+
+ \snippet doc/src/snippets/code/doc_src_debug.qdoc 2
+
+ If this code is compiled with \c QT_NO_DEBUG defined, the code in
+ the Q_CHECK_PTR() expression is not executed and \e 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.
+
+ \section1 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 \link moc.html the meta-object compiler\endlink (\c{moc}),
+ but forget to link the \c{moc}-generated object code into your
+ executable, you will get very confusing error messages. Any link
+ error complaining about a lack of \c{vtbl}, \c{_vtbl}, \c{__vtbl}
+ or similar is likely to be a result of this problem.
+*/