KF5’s big ramp of deprecations to KF6
A major part of the on-going preparations of version 6 of the KDE Frameworks is to see that the API breakage due to happen versus version 5 is mostly an API dropage. And software using KDE Frameworks 5 can already find and use the future-proof API in the version 5 series, next to the legacy one. So that the very hurdle to take on porting from KF5 to KF6 is minimal, ideally just changing “5” to “6”, once one has managed to get rid of using the legacy API. This also matches the approach taken by Qt for Qt5 & Qt6, so there is a common API consumer experience. And adding new API already in KF5 allows to field-test its practicability, so KF 6.0 starts with proven API.
Preparing the Ground
To direct developers to the future-proof API there are at least two places:
- adding notes in the API documentation, to help those writing new code to avoid the outdated API
- having the compiler emit warnings when building existing code using outdated API
C++ does not come with a native system for integrated tagging and conditional usage of deprecated API and build of its implementation or control over library and version specific emission of warnings. All there is are documentation tools like doxygen which require to have a separate tool-specific tag like @deprecated in the documentation comment, while in the C++ syntax since C++14 there is the [[deprecated(text)]] attribute available (before there were compiler specific attributes), where the API developer has to maintain both separately, and a global option for the compiler like -Wno-deprecated-declarations to not be bothered by any warnings.
For KDE Frameworks therefore almost 3 years ago (ECM/KF 5.64) the CMake utility ECMGenerateExportHeader was introduced: it generates next to the symbol visibility tagging C++ macros (“export macros”) also version-controlled macros for adding compiler deprecation warnings as well as for wrapping code blocks to be visible to the compiler (see blog post for more details). It just does not solve the need for duplication in the documentation comment sadly.
A typical deprecation using those macros looks in the declaration like this
#include <foo_export.h>
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0. Use bar().
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 0, "Use bar()")
void foo();
#endifand in the implementation like this
#include "foo.h"
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
void foo()
{
}
#endifWhich by default will then have the compiler notify an API consumer in a build like this (note also the automatic version hint):
/.../fooconsumer.cpp:27:65: warning: ‘void foo()’ is deprecated: Since 5.0. Use bar() [-Wdeprecated-declarations]See the guidelines how to deprecate API for further details.
Piling up
The deprecation macros available by that have since been massively deployed: as of the current development version of KF5 there are more than 1000 hits in the installed headers when grepping for deprecated methods and enumerators. So quite some things learned and changed since KF 5.0 in July 2014 (but also before, see below).
As the internal logic generated with ECMGenerateExportHeader requires to list specific version at which API is deprecated, this also gives easy access to interesting insight into the activity. Note also that the new macros allowed to properly deprecate API that was even considered outdated before KF5, but due to missing systematic support failed to be removed on next chance (especially in the KIO core library).
| Library | Versions with new deprecations |
| attica | 0.2 5.4 5.23 |
| baloo | 5.55 5.69 |
| bluez-qt | 5.57 |
| karchive | 5.0 5.85 |
| kauth (core) | 5.71 |
| kauth (widgets) | 5.92 |
| kbookmarks | 5.0 5.65 5.69 |
| kcalendarcore | 5.64 5.89 5.91 5.95 5.96 5.97 |
| kcmutils | 5.66 5.76 5.82 5.85 5.87 5.88 5.90 |
| kcodecs | 5.5 5.56 |
| kcompletion | 4.0 4.5 5.0 5.46 5.66 5.81 5.83 |
| kconfig (core) | 4.0 5.0 5.24 5.42 5.82 5.89 |
| kconfig (gui) | 5.11 5.39 5.71 5.82 |
| kconfigwidgets | 4.0 5.0 5.23 5.32 5.38 5.39 5.64 5.78 5.80 5.82 5.83 5.84 5.85 5.90 5.93 |
| kcontacts | 5.88 5.89 5.92 |
| kcoreaddons | 4.0 5.0 5.2 5.65 5.67 5.70 5.72 5.75 5.76 5.78 5.79 5.80 5.84 5.86 5.87 5.88 5.89 5.92 5.95 5.97 |
| kdbusaddons | 5.68 |
| kdeclarative (kdeclarative) | 5.0 5.45 5.75 5.91 5.95 |
| kdeclarative (quickaddons) | 5.88 5.93 |
| kdesu | 5.0 |
| kdnssd | 4.0 |
| kfilemetadata | 5.50 5.60 5.76 5.82 5.89 5.91 |
| kglobalaccel | 4.2 4.4 5.9 5.90 |
| kglobalaccel (runtime) | 4.3 5.90 |
| kholidays | 5.95 |
| ki18n | 5.0 |
| kiconthemes | 4.8 5.0 5.63 5.64 5.65 5.66 5.82 |
| kidletime | 5.76 |
| kio (core) | 3.0 3.1 3.4 4.0 4.3 4.5 4.6 5.0 5.2 5.8 5.24 5.45 5.48 5.63 5.61 5.64 5.65 5.66 5.69 5.72 5.78 5.79 5.80 5.81 5.82 5.83 5.84 5.86 5.88 5.90 5.91 5.94 5.96 5.97 |
| kio (filewidgets) | 4.3 4.5 5.0 5.33 5.66 5.70 5.76 5.78 5.86 5.97 |
| kio (kntlm) | 5.91 |
| kio (widgets) | 4.0 4.1 4.3 4.4 4.5 4.6 4.7 5.0 5.4 5.6 5.25 5.31 5.32 5.64 5.66 5.71 5.75 5.76 5.79 5.80 5.82 5.83 5.84 5.86 5.87 5.88 |
| kirigami | 5.80 5.86 |
| kitemmodels | 4.8 5.65 5.80 |
| kitemviews | 4.2 4.4 5.0 5.50 |
| kjobwidgets | 5.79 |
| knewstuff (core) | 5.31 5.36 5.53 5.71 5.74 5.77 5.83 |
| knewstuff (qtquick) | 5.81 |
| knewstuff (widgets) | 5.91 |
| knewstuff | 5.29 5.76 5.77 5.78 5.79 5.80 5.82 5.85 5.91 5.94 |
| knotifications | 5.67 5.75 5.76 5.79 |
| kpackage | 5.21 5.84 5.85 5.86 |
| kparts | 3.0 4.4 5.0 5.72 5.77 5.78 5.80 5.81 5.82 5.83 5.88 5.90 |
| kquickcharts | 5.78 |
| krunner | 5.28 5.71 5.72 5.73 5.76 5.77 5.79 5.81 5.82 5.85 5.86 5.88 |
| kservice | 5.0 5.15 5.61 5.63 5.66 5.67 5.70 5.71 5.79 5.80 5.81 5.82 5.83 5.86 5.87 5.88 5.89 5.90 |
| ktexteditor | 5.80 |
| ktextwidgets | 5.0 5.65 5.70 5.71 5.81 5.83 |
| kunitconversion | 5.91 |
| kwallet | 5.72 |
| kwayland (client) | 5.49 5.50 5.52 5.53 5.73 5.82 |
| kwidgetsaddons | 5.0 5.13 5.63 5.65 5.72 5.77 5.78 5.85 5.86 5.97 |
| kwindowsystem | 5.0 5.18 5.38 5.62 5.67 5.69 5.80 5.81 5.82 |
| kxmlgui | 4.0 4.1 5.0 5.75 5.83 5.84 |
| plasma-framework (plasma) | 5.6 5.19 5.28 5.30 5.36 5.46 5.67 5.77 5.78 5.81 5.83 5.85 5.86 5.88 5.94 |
| plasma-framework (plasmaquick) | 5.12 5.25 5.36 |
| prison | 5.69 5.72 |
| solid | 5.0 |
| sonnet (core) | 5.65 |
| sonnet (ui) | 5.65 |
| syntax-highlighting | 5.87 |
| threadweaver | 5.0 5.80 |
On the QML side deprecations are not that simple (and also not my personal domain), so that is not covered here.
On an expected question: It will be ready, when it is ready. Please join the effort if you can. Find more info e.g. in Volker’s more recent update.