KDevelop/Debugging: Difference between revisions

From KDE Community Wiki
(Created page with "== Debug logging == KDevelop makes use of the categorized logging system from Qt Core (see [http://doc.qt.io/qt-5/qloggingcategory.html#details API documentation of QLoggingC...")
 
(Add more details, note about QLoggingCategory::setFilterRules in unit tests)
 
Line 5: Line 5:
=== Definition of logging categories ===
=== Definition of logging categories ===


KDevelop codebase applies the CMake macro [https://api.kde.org/ecm/module/ECMQtDeclareLoggingCategory.html ecm_qt_declare_logging_category] from Extra CMake Modules to generate the code for defining the categories.
KDevelop codebase applies the CMake macro [https://api.kde.org/ecm/module/ECMQtDeclareLoggingCategory.html 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.
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.
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:
'''Example, by the KDevPlatform library Sublime:'''
 
Definition in CMakeLists.txt:
<syntaxhighlight lang="cmake">
<syntaxhighlight lang="cmake">
ecm_qt_declare_logging_category(sublime_LIB_SRCS
ecm_qt_declare_logging_category(sublime_LIB_SRCS
Line 18: Line 20:
)
)
</syntaxhighlight>
</syntaxhighlight>
 
Use in the C++ code:
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
#include <debug.h>
#include <debug.h>
Line 24: Line 26:
qCDebug(SUBLIME) << "Hello world!";
qCDebug(SUBLIME) << "Hello world!";
</syntaxhighlight>
</syntaxhighlight>
 
Use in the shell:
<syntaxhighlight lang="shell">
<syntaxhighlight lang="shell">
export QT_LOGGING_RULES="kdevplatform.sublime.debug=true"
export QT_LOGGING_RULES="kdevplatform.sublime.debug=true"
Line 31: Line 33:
=== Configure logging levels with kdebugsettings ===
=== 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).
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.
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 [https://bugs.kde.org/show_bug.cgi?id=396959 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 [http://doc.qt.io/qt-5/qloggingcategory.html#setFilterRules QLoggingCategory::setFilterRules(...)] in the initTestCase() method of the unit test.
'''Example, by the KDevPlatform library Sublime:'''
<syntaxhighlight lang="cpp-qt">
void TestSublimeUsingStuff::initTestCase()
{
    QLoggingCategory::setFilterRules(QStringLiteral("*.debug=false\ndefault.debug=true\nkdevplatform.sublime.debug=true\n"));
}
</syntaxhighlight>

Latest revision as of 14:03, 29 July 2018

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"));
}