|
|
| (7 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| = Qt 4 / kdelibs 4 =
| | {{Moved To Community | Guidelines_and_HOWTOs/Debugging }} |
| | |
| When you start a konsole and type the commands to start an application you
| |
| will see all sorts of statements are printed in the konsole while the
| |
| application is running. All applications print these messages, to look
| |
| at them you have to know where to look. The application will have to be
| |
| compiled with the debugging enabled. So using a precompiled package from a distribution
| |
| probably will not give you this information. If you compiled the application
| |
| yourself, make sure the configure option <tt>--disable-debug</tt> was not used.
| |
| | |
| In KDE all debugging text-output can be switched on or off based on so
| |
| called '''areas'''. One application can be one or more area. One part of the kde base libraries can be another area. Enabling/disabling these areas from being printed can be done using the '''kdebugdialog''' application. For simple debugging selecting all
| |
| sections is probably wise.
| |
| | |
| When you are debugging it is best to simply start a konsole and start the
| |
| application from there. In a konsole you could simply type:
| |
| <pre>
| |
| kicker
| |
| </pre>
| |
| and in the konsole kicker could return a message like:
| |
| <pre>
| |
| ERROR: kicker is already running!
| |
| </pre>
| |
| When a lot of output is written to the konsole it might go out of view before
| |
| you could read it, therefor it is easy to create a text file which contains
| |
| all this information, to do so type the following:
| |
| <pre>
| |
| application 2>&1 | tee debug.log
| |
| </pre>
| |
| where 'application' can be replaced with the application you are debugging.
| |
| Afterwards you could open the file 'debug.log' to look at the messages again.
| |
| | |
| If you are NOT starting the application from a konsole the messages will be
| |
| logged somewhere else, or they could have been discarded by the program that
| |
| started your application.
| |
| | |
| If your application is started by clicking on an icon your best bet is to check
| |
| the following log files. Beware; they contain logs for a lot of applications,
| |
| not just the application you are debugging!
| |
| | |
| '''Case 1: Graphical login (i.e. kdm, gdm, xdm, etc.)'''
| |
| | |
| The debug messages get redirected into the file {{path|~/.xsession-errors}} or
| |
| {{path|~/.X.err}} in your home directory (that is with a leading dot '.' also
| |
| watch the Capital).
| |
| | |
| '''Case 2: You are using startx:'''
| |
| | |
| Use the following command to restart your session:
| |
| startx 2>&1 | tee startx.log
| |
| | |
| so that all the debug messages of applications started at KDE's startup (and
| |
| any application launched from the panel etc.) go to the file "startx.log"
| |
| | |
| == Links ==
| |
| | |
| The debug messages are usually printed in C++ with the kDebug or kWarning statement. Example:
| |
| <pre>
| |
| kDebug(1210) << "arbitrary message";
| |
| kWarning(1210) << "this rather should not happen";
| |
| </pre>
| |
| The number 1210 (so called ''debug area'') in this case represents kicker. You can omit the number.
| |
| | |
| See also: [http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/group__kdebug.html kDebug/kWarning API documentation] and [http://websvn.kde.org/trunk/KDE/kdelibs/kdecore/kdebug.areas?view=markup kdebug.areas] for list of debug areas numbers.
| |
| Note that you can use ''add_definition(-DKDE_DEFAULT_DEBUG_AREA=<number>)'' in CMakeLists.txt to specify default debug area.
| |
| | |
| = 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.
| |
