Add ecm_qt_install_logging_categories & ecm_qt_export_logging_category
ClosedPublic

Authored by kossebau on Feb 4 2020, 5:22 AM.

Details

Summary

Having to manually maintain a separate copy of all the data about qt logging
categories in the categories files comes with the usual disadvantages.
The new macro ecm_qt_install_logging_categories together with the additions
of arguments DESCRIPTION & EXPORT to ecm_qt_declare_logging_category allows
to have just one place with one copy of the data, and have the categories
file automatically generated from that data, linked via the EXPORT id.

For cases not using ecm_qt_declare_logging_category, but having categories
manually defined in code, yet wanting to have info about those categories in
the installed fiel, ecm_qt_export_logging_category allows to add those data
to the system.

Test Plan

Added unit tests work, porting of some repos created categories files whose
diff against the manually created files were only the DO_NOT_EDIT header.

Diff Detail

Repository
R240 Extra CMake Modules
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
kossebau created this revision.Feb 4 2020, 5:22 AM
Restricted Application added projects: Frameworks, Build System. · View Herald TranscriptFeb 4 2020, 5:22 AM
Restricted Application added subscribers: kde-buildsystem, kde-frameworks-devel. · View Herald Transcript
kossebau requested review of this revision.Feb 4 2020, 5:22 AM
kossebau added inline comments.Feb 4 2020, 5:28 AM
modules/ECMQtDeclareLoggingCategory.cmake
79

Why the need for explicit DESTINATION argument, where almost all use-cases will use ${KDE_INSTALL_LOGGINGCATEGORIESDIR}?
Because ECMQtDeclareLoggingCategory is part of modules, not kde-modules, so KDEInstallDirs cannot be used.

One could think about having a wrapper module in kde-modules. But such a wrapper script would be nice for more things actually, given all the repeated boilerpplate across e.g. all the KF repos :)

So asking for explicit mention of the installation destination is consistent.

See D27150 as an example next to the test and docs for how this would be used. The ecm_qt_export_logging_category also is kept similar to ecm_qt_declare_logging_category in case someone wants to turn the manual definition to a generated one, that wil just need addition of HEADER and the sources variable and change of macro name called.

BTW, core of this logic has been taken from KDevelop's internal util macros, where this served for some versions already :) https://phabricator.kde.org/source/kdevelop/browse/master/cmake/modules/KDevelopMacrosInternal.cmake though with some additional wrappers for repeated data & patterns.

Seems ok for me

kossebau updated this revision to Diff 75069.Feb 5 2020, 9:16 PM

in doc also be explicit that ecm_qt_install_logging_categories can be in
another directory, just needs to be called last

mlaurent accepted this revision.Feb 6 2020, 7:17 AM

Seems ok for me :)

This revision is now accepted and ready to land.Feb 6 2020, 7:17 AM

@mlaurent Thanks for review :)
Do you happen to know any more complex usages of ecm_qt_declare_logging_category and/or manual category definitions which can and should be checked for how these new methods would work out?
I have not really researched bigger parts of KDE code for if the currently proposed method calls will be sufficient to cover all use cases. So far it's mainly based on KDevelop, kcoreaddons, kservice & sonnet use-cases.
So far it was mainly: @broulik complained on irc, a day later I accidentally found another approach to the target-based hack we had in kdevelop, changed kdevelop cmake code, then pulled out the core logic and turned into this patch, after trying to port kcoreaddons, kservice & sonnet :)
Thus also hesitating to merge on first positive review, as I am not sure myself yet, still thinking of this as prototype to get feedback on.

I don't see other case. For me your macro works for all case that we can implement.

No other idea.
But avoiding to create by hand the file is a good idea. I never successed to create a macro for it
So thanks

Good. So will land this next Tuesday, Feb 11th then, so other people will have had 7 days of feedback opportunity.

@mlaurent Wasn't there also something which tells kdebugsettings about renamed categories? Is that documented anywhere? Could that be supported by some additional macro or adaption of the existing/new ones?

Yep you need to create a file name "foo.renamecategories" where you change the categorie name

old module name<space>new module name

for example "log_mailfilteragent org.kde.pim.mailfilteragent" in kmail

What do you need as " Could that be supported by some additional macro or adaption of the existing/new ones?" ?

Yep you need to create a file name "foo.renamecategories" where you change the categorie name

  1. old module name<space>new module name

    for example "log_mailfilteragent org.kde.pim.mailfilteragent" in kmail

Does kdebugsettings also support multiple renames? Like log1 > log2 > log3?

What do you need as " Could that be supported by some additional macro or adaption of the existing/new ones?" ?

We could have another argument for ecm_qt_declare_logging_category& ecm_qt_export_logging_category to pass old log names, and then have ecm_qt_install_logging_categories also generate & install a .renamecategories file. Should be easy to add, working on it next.

Yep you need to create a file name "foo.renamecategories" where you change the categorie name

  1. old module name<space>new module name

    for example "log_mailfilteragent org.kde.pim.mailfilteragent" in kmail

Does kdebugsettings also support multiple renames? Like log1 > log2 > log3?

Perhaps :) I will test it next week

What do you need as " Could that be supported by some additional macro or adaption of the existing/new ones?" ?

We could have another argument for ecm_qt_declare_logging_category& ecm_qt_export_logging_category to pass old log names, and then have ecm_qt_install_logging_categories also generate & install a .renamecategories file. Should be easy to add, working on it next.

oki

Yep you need to create a file name "foo.renamecategories" where you change the categorie name

  1. old module name<space>new module name

    for example "log_mailfilteragent org.kde.pim.mailfilteragent" in kmail

Does kdebugsettings also support multiple renames? Like log1 > log2 > log3?

Perhaps :) I will test it next week

Would be good if it does, as I just found two candidates :) kcontacts & kcalendarcore now that they have moved to KF ideally would get rid of the "pim" subelement (and kcalcore renamed to kcalendarcore)

Preparing the new macros to support that now (already had first working draft only supporting one rename).

kossebau updated this revision to Diff 75312.Feb 9 2020, 8:01 PM

Add support for also generating renamecategories files

This revision was automatically updated to reflect the committed changes.
bruns added a subscriber: bruns.Feb 28 2020, 10:34 PM

@kossebau - you have pushed commits depending on this change to several repositories, sometimes without waiting for acceptance, sometimes even bypassing Phabricator review completely.

You have ommited to update the minimum ECM version in all cases AFAICS.

kossebau added a comment.EditedFeb 28 2020, 10:36 PM

Edit 2: About the direct commits: this has been done because the principal ECMQtDeclareLoggingCategory change and its application to some reference KF repos had been reviewed and accepted. Applying the same change to all the other repos was mainly shifting data around, without security class risks. Given the amount of people who are capable to add value by reviews for all those other patches is very small in this case, me being a developer who thinks he is experienced with CMake, has a long tradition in working on ECM & KF, takes care and responsibility for his commits, the actual changes being rather small and their effect easily testable by me before pushing (comparing old manual & new generated files for having equivalent content, build still passing) it is more economical for everyone to have me just go and apply the respective changes to all other KF repos, to ensure they are all consistent and the matter can be checked off in short time.
Previous mass changes done in similar fashion also worked out noiselessly, at least to what was brought to my ears :) so it seems the exceptions done here have been acted out with all the needed responsibility,

You have ommited to update the minimum ECM version in all cases AFAICS.

Because that bump is done by the release scripts, and I did not want to mess with them.

In general it is expected that all of ECM & KF master depends on latest master of their peers. The dep version is only bumped in time for release preparation.

Edit: At least from what I have seen until now, other API additions to ECM & KF modules and their immediate usages in other KF modules also have not been done with a matching bump. Instead everyone seems to assume people make sure to update the other ECM & KF dependencies as needed when they run into such an issue.