[Development] Reduce usage of Qt private API

[Tor Arne Vestbø]

Hi Jan,

Thanks for looking into the private API use!

The “modern” version of qplatformnativeinterface.h is the public QNativeInterface namespace and the various QFoo::nativeInterface<T>() accessors, so we should transition the former to the latter.

Similarly, the QX11Extras can find a new home in the QNativeInterfaces.

However we should look at each API on a case by case basis, and not just dump everything into e.g. the QGuiApplication native interface (like https://codereview.qt-project.org/c/qt/qtbase/+/677957 currently does). E.g. some of these APIs might have a more specific place in the QScreen native interface.

We should also limit the amount of trivial wrapper helpers we provide, so these interfaces don’t blow up to a kitchen sink. If something can be solved by having a small helper module in KDE, that uses hooks in the native interface to e.g. get the underlying xcb_screen_t or xcb_window_t, then that’s preferably to maintaining code in Qt if in reality it's a 99% KDE use-case.

So I think we have a plan, if someone is willing to work on it (thanks Vlad!), and as long as we do it step by step and with some considerations of the scope/use-cases :)

Cheers,
Tor Arne


On 22 Sep 2025, at 13:18, Jan Grulich via Development <development at qt-project.org> wrote:

Hi,

As a Fedora/RHEL packager responsible for Qt packages, I often spend more time doing rebuilds of all the packages using Qt private API than updating Qt packages itself. This got to the point where we have to rebuild over 100 packages in Fedora for every minor update. Under normal circumstances we would do these rebuilds even for patch releases, but we ship a patch<https://src.fedoraproject.org/rpms/qt6-qtbase/blob/rawhide/f/qtbase-use-only-major-minor-for-private-api-tag.patch> that tracks only the MAJOR.MINOR version. I brought this for discussion during KDE Akademy two weeks ago, but the decision was to bring this to Qt mailing list to get more opinions.

I have tried to do some research and identify what private API is used. From the majority it is qtx11extras_p.h and qplatformnativeinterface.h. In Qt 5 times the qtx11extras was a separate module and not a problem, with Qt 6 it was moved to qtbase and made private. Both qtx11extras_p.h and qplatformnativeinterface.h have not been touched or modified for years, with qtx11extras_p.h not being actually touched at all since it was imported. Yet, we have to rebuild all the packages using these, because they are part of the private API, even though there is no practical reason to rebuild them. There are like ~40 packages in Fedora using exclusively one of these two includes (see gemini-one-include.txt).

There are some possible solutions to this:
1) Make some API public instead
2) For qtx11extras we can have a KDE wrapper that all the KDE apps will use instead and we will have to rebuild just this wrapper instead of all the other packages, but that doesn't fix all the packages and other private APIs.
3) Make these API versioned separately and bump version only when it becomes incompatible so for example we wouldn't need to rebuild for qtx11extras as it won't likely change in the future

Also Vlad already started with some work here https://codereview.qt-project.org/c/qt/qtbase/+/677957 that would also help reduce the private API usage of qtx11extras. There are obviously more private API used besides qtx11extras_p.h and qplatformnativeinterface.h, but I was focusing on these as even only these two would  reduce the number of rebuilds by half.

Would any approach from above suggested (or combination) be something feasible?

Thank you for any ideas and help in advance.

Best regards,
--
Jan Grulich,
Principal Software Engineer, Desktop Team
Red Hat
<gemini-report-per-include.txt><gemini-one-include.txt>--
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20250923/1f06664b/attachment.htm>