Frameworks/Frameworks Logging Policy
Introduction
KDE Frameworks make use of Qt's categorized logging system. To enable controlling the logging across KDE Frameworks in a consistent way, the logging categories have to follow some patterns.
The goal of the pattern is to allow:
- to control logging for the whole of KF in one go
- to control logging for a whole KF module in one go, including external plugins for the module
- to control logging for a certain feature across all KF modules implementing it in one go
- to derive the main category name from the name of the KF module, library or helper executable
Category Naming Patterns
Category names for KF modules are made from the following patterns:
- "kf".<module>[.<library>][.<internalfeature>]
- "kf".<module>.<type-of-plugins>.<plugin>[.<internalfeature>]
- "kf".<module>.<demon/tool>[.<internalfeature>]
- "kf".<module>.<publicfeature>[.<othercode>]
"kf." namespace prefix
Follows the "qt." example, having the product name (it's abbreviation) as the first name component. The prefix is without the "5", so with KF v6 things do not need a change (again follows "qt." example).
Enables control of all KF categories via:
"kf*[.<type>]=true|false"
<module>[.<library>]
A small challenge here is that some KF modules actually consist of multiple libraries, usually split for core, gui or widgets (matching Qt libs) as well as having some qml extension plugin, usually for QtQuick. Naming of such libraries is not consistent (so no pattern of *core, *(g)ui, *widgets),
Some module even have multiple separate libraries for a type, grouped by feature (e.g. KIOFileWidgets & KIOWidgets).
There is also a client & server variant (KWaylandClient, KWaylandServer). One things currently common to all such libraries is that the module name is used as prefix for the library name, which we can make use of (and should also add as requirement to the KF policies).
<module>: the KF module name, lowercased and with the "K" prefix stripped, unless special-no-k-name or abbreviation
Examples:
| "Baloo" | -> | "kf.baloo" |
| "KArchive" | -> | "kf.archive" |
| "KIO" | -> | "kf.kio" |
| "KDED" | -> | "kf.kded" |
Enables control of all module categories via:
"kf.<module>*[.<type>]=true|false"
<library>: the library name, lowercased and with "libKF5" prefix and KF module name stripped, or "quick" for QtQuick QML extension plugins
Examples:
| "libKF5NewStuffCore" | -> | "kf.newstuff.core" |
| "libnewstuffqmlplugin.so" | -> | "kf.newstuff.quick" |
| "libKF5KIOFileWidgets" | -> | "kf.kio.filewidgets" |
Enables control of all library categories via:
"kf.<module>.<library>*[.<type>]=true|false"
<type-of-plugins>
There could be multiple types of plugins & extensions per module. To allow bulk control separated per type, each type of plugins is namespaced with the name of the type using a plural "s". The <plugin> would be named with or without origina category namespace, depending whether there is no doubt where the plugin is from, or with full category namespace of the origin (like another KF module) if there could be doubt. A full origin namespace also enables to use filter rules with leading "*" and the module namespace to also cover the plugin then.
Examples:
| kf.kio.slaves.ftp |
| kf.kio.urifilters.localdomain |
| kf.sonnet.clients.aspell |
| kf.configwidgets.cms.kf.kio.useragentdlg |
Enables control of all categories specific to all plugins via:
"kf.<module>.<type-of-plugins>*[.<type>]=true|false"
<demon/tool>
Helper executables, like demons and tools, would be named by their full executable name. Even if specific to a library only, their category would be a subcategory directly to the module, not the library, so they are on same level as libraries.
Examples:
| kf.config.kconf_update |
| kf.kio.kiod |
Enables control of all executable specific categories via:
"kf.<module>.<demon/tool>*[.<type>]=true|false"
<publicfeature>
For features extended by other modules or projects not via plugins, but subclasses or similar library-internal methods, having the option to group logging by a namespace matching the feature is good to have (this was used with the old KDebug a lot, sadly got lost during unorganized porting to QLoggingCategory and no more central registry). <othercode> is the full category name of the module/library where the feature is extended.
Examples (made up):
| kf.texteditor.inlinenotes |
| kf.texteditor.inlinenotes.kdevelop.plugins.problemreporter |
Enables control of all categories across libraries and other consumers via:
"kf.<module>.<publicfeature>*[.<type>]=true|false"
<internalfeature>
For code where more fine-grained control about the scope of logging can be useful. Can be one subcategory or have more subcategories internally.
Examples:
| kf.coreaddons.kdelibs4configmigrator |
| kf.kio.core.copyjob |
| kf.kio.widgets.kdirmodel |
| kf.windowsystem.keyserver.x11 |
Enables control of all categories across libraries and other consumers via:
"kf.<module>.<publicfeature>*[.<type>]=true|false"