Call for action: applying version-based deprecation macros for KDE Frameworks API

[Friedrich W. H. Kossebau]

Hi,

for those who missed things so far, quick recap first (everyone else please 
jump to next section below):

To better assist users of KDE Frameworks in dealing with its deprecated API, 
we might want to give them more control over visibility of such API to the 
compiler when building their software or if deprecation warnings are emitted.

For some weeks there has been work on a cmake-based technique which uses the 
usually already present generated export macros header (e.g. foo_export.h) as 
injector for new respective C++ prepocessor macros which enable to mark 
deprecated API like this:

#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
 * @deprecated Since 5.0. Use bar(). // Sadly doxygen needs data duplicated
 */
FOO_DEPRECATED_VERSION(5, 0, "Use bar()")
void foo();
#endif

Which then allows users of the API to control visibility or warnings by macro 
flags like
-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0xXYZ
-DFOO_DEPRECATED_WARNINGS_SINCE=0xXYZ
-DFOO_NO_DEPRECATED (short for:FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=latest)
-DFOO_NO_DEPRECATED_WARNINGS (short for: FOO_DEPRECATED_WARNINGS_SINCE=0)
similar to what we know from Qt.

Next to that, the developed solution also supports:
* optional group default flags, so users can easily control settings for
  groups of libraries (like all the KDE Frameworks)
* disabling build of implementation code of deprecated API (like useful for
  bundled shared libraries)

This solution is ECMGenerateExportHeader, up for review process at
    https://phabricator.kde.org/D23789

There are also patches for two KDE Frameworks modules as examples:
    KCoreAddons: https://phabricator.kde.org/D23800
    KService: https://phabricator.kde.org/D23802

See also related blog post for some more details:
https://frinring.wordpress.com/2019/09/09/more-control-over-warnings-for-and-visibility-of-deprecated-library-api-via-generated-export-macro-header/


PROTOTYPE BECOMING PRODUCTION VERSION

So far feedback has been positive (thanks especially David, but also Christian 
& Albert for comments). Could have been more feedback, but I project the 
silence onto "seems fine with me, nothing to object" :) If this does not 
represent you, now is your time to break your silence, please.

The current state of the proposed ECMGenerateExportHeader seems solid to me 
and future-proof. While there are some ideas for more features, those should 
be implementable on & next to the current public interface, both of the cmake 
macros as well as of the generated C++ preprocessor macros.
There is also the undecided question how to implement the detection of support 
for deprecated(text) attribute (generation time vs. compiler time), which is a 
detail not further influencing public API. Currently there is a placeholder 
detecting only GCC at compiler time, the final solution will be developed in 
parallel/as follow-up.

Next to the uploaded two patches I locally have some more KF modules patched 
to use ECMGenerateExportHeader and the generated version-based deprecation 
macros, and compiled them as such the recent weeks multiple times, with no 
issues seen.


EXECUTION PLAN

Now that KF 5.63 is branched this WE...
1) ECMGenerateExportHeader would be added to ECM master in the week after 
(Wed/Thu), unless there are new objections
2) KF contribution documentation gets extended to describe how to do 
deprecation (https://phabricator.kde.org/T11824 has snippets, wants comments)
3) people write patches for the different KF modules

Given the number of KF modules I would not be thrilled to have to write the 
patches for all of them myself ;), also would it be good to have more people 
test-drive the usage of ECMGenerateExportHeader as well as the generated 
deprecation macros, so we have more feedback on it before it gets public in 
ECM/KF 5.64.

So I added a list of modules to the mother task https://phabricator.kde.org/
T11490 (see end of description). You are invited/asked now to note there 
manually before which modules you are going to write a patch for (by adding 
your name behind) and, once done, then note the created review request (one 
could use real phabricator subtasks for this, but not sure that is worth the 
extra effort).
IMHO the Porting Aid modules like KWebKit, KHtml, KDELibs4Support & Co. shall 
not be using the new macros. I kept them in the list for now, as one still 
might to check them if they emit proper compile-time deprecation warnings and 
what could be done there.

So, who is up to join the team of improving handling of deprecated KF API? :)

Please pick you set of libraries, and comment (confirming/positive comments 
only also welcome, so get a better idea how well this is supported by you).

Cheers
Friedrich