|
|
| (6 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| = Qt 4 / kdelibs 4 =
| | {{Moved To Community | Guidelines_and_HOWTOs/Debugging }} |
| | |
| kdelibs provides a [http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/group__kdebug.html family of functions] that output information to <tt>stderr</tt>, meaning that if you run an application from the terminal, it will be displayed in that terminal window. If you run the application from the desktop (using KRunner or the application menu, for example), the output will normally appear in {{path|~/.xsession-errors}} or {{path|~/.X.err}} if you use a login manager like KDM, or on the console you ran <tt>startx</tt> from if you started X that way.
| |
| | |
| To use these functions in your code, you need to include the correct header file <syntaxhighlight lang="cpp-qt">
| |
| #include <KDebug>
| |
| </syntaxhighlight>
| |
| and then you can use the functions <syntaxhighlight lang="cpp-qt">
| |
| kDebug() << "Something happened that only developers care about" << someVariable;
| |
| kWarning() << "Something bad happened that users (end-users, or application developers using this library) should be aware of";
| |
| kError() << "Something even worse happened";
| |
| kFatal() << "Something happened so bad we had to terminate the application";
| |
| </syntaxhighlight>
| |
| | |
| The syntax is much like <tt>cout</tt>, and most native C++ types, Qt-provided types and kdelibs-provided types can be passed directly (like with <tt>someVariable</tt> in the example).
| |
| | |
| Note that the <tt>kDebug</tt> calls will only do anything if the code was compiled with debugging enabled (and so will generally not work in packages from a distribution). This means <tt>cmake</tt> should be run with the <tt>-DCMAKE_BUILD_TYPE=debugfull</tt> argument. The other functions, however, will produce output no matter how the code was compiled.
| |
| | |
| == Debug Areas ==
| |
| | |
| The debugging output can be controlled at runtime using debugging areas. This allows enabling debugging output for only certain libraries or plugins, for example. Debugging areas are numbers, so the <tt>KStatusNotifierItemPrivate::registerToDaemon</tt> method in the kdeui library, for example, has the call <syntaxhighlight lang="cpp-qt">
| |
| kDebug(299) << "Registering a client interface to the KStatusNotifierWatcher";
| |
| </syntaxhighlight>
| |
| The file <tt>kdebug.areas</tt> in the <tt>kdecore</tt> directory of kdelibs indicates that the number 299 is associated with "kdeui (KNotification)".
| |
| | |
| This information is used by the <tt>kdebugdialog</tt> utility (which you can just run from the commandline or using KRunner) to turn these areas on and off, enabling or disabling those <tt>kDebug</tt> statements. It is also used by <tt>kDebug</tt>, <tt>kWarning</tt>, <tt>kError</tt> and <tt>kFatal</tt> to indicate which component output the line. For example, the line in the above example, found in the method <tt>KStatusNotifierItemPrivate::registerToDaemon</tt>, would produce the line <pre>kwalletmanager(642)/kdeui (KNotification) KStatusNotifierItemPrivate::registerToDaemon: Registering a client interface to the KStatusNotifierWatcher</pre> when executed from within the application kwalletmanager, with PID 642.
| |
| | |
| For applications, you can generally just omit the area number, and <tt>kDebug</tt> will use the default area. If you are developing a library or a plugin, though, you should get a number assigned (via the kde-core-devel mailing list) for your library or plugin, and use it in your code. Rather than using the number directly in every call to <tt>kDebug</tt> and friends, you can just add<syntaxhighlight lang="cmake">
| |
| add_definition(-DKDE_DEFAULT_DEBUG_AREA=<number>)'
| |
| </syntaxhighlight>
| |
| to your <tt>CMakeLists.txt</tt> file.
| |
| | |
| == Improving Log Output ==
| |
| | |
| There are a couple of useful environment variables to control the output of <tt>kDebug</tt> and friends. <syntaxhighlight lang="bash">
| |
| export KDE_COLOR_DEBUG=1
| |
| </syntaxhighlight> will make them produce colored output, and <syntaxhighlight lang="bash">
| |
| export KDE_DEBUG_TIMESTAMP=1
| |
| </syntaxhighlight> will include timestamps in the output. <syntaxhighlight lang="bash">
| |
| export KDE_DEBUG_TIMESTAMP=2
| |
| </syntaxhighlight> can be used to include milliseconds in the timestamps.
| |
| | |
| == Managing Lots of Output ==
| |
| | |
| If you have lots of debugging statements, they may appear too fast and leave the terminal window before you can read them. There are three main ways to deal with this:
| |
| # Use <tt>kdebugdialog</tt> to disable some logging areas to limit the amount of output generated
| |
| # Increase the amount of scrollback in the terminal so that output is not lost; in Konsole, you can go to <tt>Settings > Edit Current Profile...</tt> and click on the <tt>Scrollback</tt> tab to change this. Konsole also has a useful search feature: just press <tt>Ctrl+Shift+F</tt> or click <tt>Find...</tt> on the <tt>Edit</tt> menu.
| |
| # Save the output to a file; <tt>tee</tt> is useful for this. For example, you can run <pre>application 2>&1 | tee debug.log</pre> to save the output to the file <tt>debug.log</tt> while still viewing it in the terminal. This can also be used to capture output from <tt>startx</tt>.
| |
| | |
| = Qt 5 / KDE Frameworks 5 =
| |
| | |
| <tt>kDebug()</tt> and friends have been deprecated in KDE Frameworks 5, and you should use Qt's built-in debugging instead. We recommend that you use [http://doc-snapshot.qt-project.org/qt5-stable/qloggingcategory.html QLoggingCategory], particularly for libraries and plugins. Note that this is only available in Qt 5.2 and later.
| |
| | |
| In particular, for a library or plugin called "Foo", you should have a common header that contains the following declaration
| |
| #include <QLoggingCategory>
| |
| Q_DECLARE_LOGGING_CATEGORY(LOG_FOO)
| |
| and exactly one source file containing
| |
| Q_LOGGING_CATEGORY(LOG_FOO, "foo")
| |
| | |
| You should treat the string as something like reverse DNS; it cannot contain spaces, and dots indicate a heirarchy. For example, a Plasma dataengine called "Foo" might use the category <tt>"plasma.engine.foo"</tt>.
| |
| | |
| Logging lines then look like
| |
| qCDebug(LOG_FOO) << "Log something:" << stuff();
| |
| qCWarning(LOG_FOO) << "Something bad happened that users (end-users, or application developers using this library) should be aware of";
| |
| qCCritical(LOG_FOO) << "Something happened so bad we had to terminate the application";
| |
| | |
| With Qt 5.2, the <tt>qCDebug</tt> line will not produce any output; this is because logging categories are disabled by default. You need to include the line
| |
| QLoggingCategory::setFilterRules(QStringLiteral("foo.debug = true"));
| |
| somewhere in the application code, generally in the <tt>main()</tt> function. Of course, you would typically disable this call in release versions. Qt 5.3 will hopefully include a way to change this configuration externally, without recompiling.
| |
| | |
| If you run your application from within a terminal application, like [http://www.kde.org/applications/system/konsole/ Konsole], you will see the logging output in that terminal window. Otherwise, it will usually appear in <tt>~/.xsession-errors</tt>.
| |
| | |
| == Improving Logging Output ==
| |
| | |
| Qt provides a way of controlling the output of the logging methods via an environment variable. You can tell it to include the application name and PID, as well as the debugging category, and color-code the text. For example, running the following lines in your shell will produce something that looks quite like <tt>kDebug</tt>'s colored output:
| |
| c=`echo -e "\033"`
| |
| export QT_MESSAGE_PATTERN="%{appname}(%{pid})/(%{category}) $c\[31m%{if-debug}$c\[34m%{endif}%{function}$c\[0m: %{message}"
| |
| unset c
| |
| | |
| == Managing Lots of Output ==
| |
| | |
| If you have lots of debugging statements, they may appear too fast and leave the terminal window before you can read them. There are three main ways to deal with this:
| |
| # [http://doc-snapshot.qt-project.org/qt5-stable/qloggingcategory.html#setFilterRules Disable some logging categories] to limit the amount of output generated
| |
| # Increase the amount of scrollback in the terminal so that output is not lost; in Konsole, you can go to <tt>Settings > Edit Current Profile...</tt> and click on the <tt>Scrollback</tt> tab to change this. Konsole also has a useful search feature: just press <tt>Ctrl+Shift+F</tt> or click <tt>Find...</tt> on the <tt>Edit</tt> menu.
| |
| # Save the output to a file; <tt>tee</tt> is useful for this. For example, you can run <pre>application 2>&1 | tee debug.log</pre> to save the output to the file <tt>debug.log</tt> while still viewing it in the terminal.
| |
