| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page debug.html |
| \title Debugging Techniques |
| |
| Here we present some useful hints to help you with debugging your |
| Qt-based software. |
| |
| \tableofcontents |
| |
| \section1 Configuring Qt for Debugging |
| |
| When \l{Qt Configure Options}{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 \macos 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 Technical Note TN2124}. |
| |
| 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. |
| |
| \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 \li Option \li Description |
| \row \li \c -nograb |
| \li 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 \li \c -dograb |
| \li Ignore any implicit or explicit \c{-nograb}. \c -dograb wins over |
| \c -nograb even when \c -nograb is last on the command line. |
| \endtable |
| |
| \section1 Environment Variables Recognized by Qt |
| |
| At runtime, a Qt application recognizes many environment variables, some of which can |
| be helpful for debugging: |
| |
| \table |
| \header \li Variable \li Description |
| \row \li \c QT_DEBUG_PLUGINS |
| \li Set to a non-zero value to make Qt print out diagnostic information about the each |
| (C++) plugin it tries to load. |
| \row \li \c QML_IMPORT_TRACE |
| \li Set to a non-zero value to make QML print out diagnostic information from the import |
| loading mechanism. |
| \row \li \c QT_HASH_SEED |
| \li Set to an integer value to disable QHash and QSet using a new random ordering for |
| each application run, which in some cases might make testing and debugging difficult. |
| \endtable |
| |
| \section1 Warning and Debugging Messages |
| |
| Qt includes global macros for writing out warning and debug |
| text. You can use them for the following purposes: |
| |
| \list |
| \li qDebug() is used for writing custom debug output. |
| \li qInfo() is used for informational messages. |
| \li qWarning() is used to report warnings and recoverable errors in |
| your application. |
| \li qCritical() is used for writing critical error messages and |
| reporting system errors. |
| \li qFatal() is used for writing fatal error messages shortly before exiting. |
| \endlist |
| |
| If you include the <QtDebug> header file, the \c qDebug() macro |
| can also be used as an output stream. For example: |
| |
| \snippet snippets/code/doc_src_debug.cpp 0 |
| |
| The Qt implementation of these macros prints to the |
| \c stderr output under Unix/X11 and \macos. With Windows, if it |
| is a console application, the text is sent to console; otherwise, it |
| is sent to the debugger. |
| |
| By default, only the message is printed. You can include additional information |
| by setting the \c QT_MESSAGE_PATTERN environment variable. For example: |
| |
| \code |
| QT_MESSAGE_PATTERN="[%{type}] %{appname} (%{file}:%{line}) - %{message}" |
| \endcode |
| |
| The format is documented in qSetMessagePattern(). You can also install your |
| own message handler using qInstallMessageHandler(). |
| |
| 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. |
| |
| qDebug(), qInfo(), and qWarning() are debugging tools. They can be |
| compiled away by defining \c QT_NO_DEBUG_OUTPUT, \c |
| QT_NO_INFO_OUTPUT, or \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. Use \c QDebugStateSaver to temporarily |
| save the formatting options of the stream. Use |
| \l{QDebug::nospace()}{nospace()} and \l{QTextStream manipulators} |
| to further customize the formatting. |
| |
| Here is an example for a class that represents a 2D coordinate. |
| |
| \snippet 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 |
| \li \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. |
| \li \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. |
| \li \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 snippets/code/doc_src_debug.cpp 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 snippets/code/doc_src_debug.cpp 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 uninitialized 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. |
| */ |