KDevelop/Debugging

From KDE Community Wiki
Revision as of 14:03, 29 July 2018 by Frinring (talk | contribs) (Add more details, note about QLoggingCategory::setFilterRules in unit tests)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Debug logging

KDevelop makes use of the categorized logging system from Qt Core (see API documentation of QLoggingCategory for details).

Definition of logging categories

KDevelop codebase applies the CMake macro ecm_qt_declare_logging_category from Extra CMake Modules (ECM) to generate the code for defining the categories. Each KDevPlatform library, each plugin and the app all have their own category, and for that do in their respective top-level CMakeLists.txt file call the macro with their specific data.

Files in the library, plugin or app module then include that generated header and use the identifier for specifying the category. And in the runtime the user uses the category name to control the logging level.

Example, by the KDevPlatform library Sublime:

Definition in CMakeLists.txt:

ecm_qt_declare_logging_category(sublime_LIB_SRCS
    HEADER debug.h
    IDENTIFIER SUBLIME
    CATEGORY_NAME "kdevplatform.sublime"
)

Use in the C++ code:

#include <debug.h>

qCDebug(SUBLIME) << "Hello world!";

Use in the shell:

export QT_LOGGING_RULES="kdevplatform.sublime.debug=true"

Configure logging levels with kdebugsettings

Since version 5.2 KDevelop (and most plugins from the separate repos) installs files which enables to use the UI tool kdebugsettings for controlling the level of logging. kdebugsettings itself is a graphical tool for editing the user's global "qtlogging.ini" configuration file (cmp. details linked above to API documentation of QLoggingCategory). This avoids having to set QT_LOGGING_RULES manually in the shell.

Start "kdebugsettings" (needs to be from the commandline, no registration yet to the workspace app menus) and best filter by the string "kdev" to see all the categories of the KDevPlatform modules, the plugins and the app itself.

Note: Filtering by the code identifier is not supported yet, see BUG 396959. Only the category name (or the description as part of the installed *.categories file) is used.

Example, by the KDevPlatform library Sublime:

Start "kdebugsettings", then enter in the list filter line a part of the category name, e.g. "sublime" or "kdevplatform". The long list of entries is now reduced to those which are closer to our interest, among them the entry "KDevPlatform lib: sublime".

Enable debug logging in unit tests by default

For unit tests which should use verbose logging by default for some categories, one can use the C++ code QLoggingCategory::setFilterRules(...) in the initTestCase() method of the unit test.

Example, by the KDevPlatform library Sublime:

void TestSublimeUsingStuff::initTestCase()
{
    QLoggingCategory::setFilterRules(QStringLiteral("*.debug=false\ndefault.debug=true\nkdevplatform.sublime.debug=true\n"));
}