[Development] Reduce usage of Qt private API

[Jan Grulich]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20250922/cafcdbe0/attachment-0001.htm>
-------------- next part --------------
Of course! Here is the overview of the private header usage, excluding the packages you requested.

### **`qtx11extras_p.h`**
- **Used 92 times**
- **Packages using it:** `dolphin`, `gwenview`, `kate`, `kcm_wacomtablet`, `kde-cli-tools`, `kde-connect`, `kf6-kdbusaddons`, `kf6-kglobalaccel`, `kf6-kio`, `kf6-kjobwidgets`, `kf6-kwindowsystem`, `kglobalacceld`, `koko`, `konqueror`, `kontactinterface`, `krfb`, `kruler`, `kscreenlocker`, `ktouch`, `kwin`, `kwin-x11`, `libkscreen`, `okular`, `plasma-desktop`, `plasma-integration`, `plasma-oxygen`, `plasma-workspace`, `plasma-workspace-x11`, `plasma5support`, `powerdevil`, `spectacle`, `xwaylandvideobridge`, `yakuake`, `zeal`

---
### **`qguiapplication_p.h`**
- **Used 11 times**
- **Packages using it:** `calibre`, `kf6-kcolorscheme`, `kf6-kconfigwidgets`, `kf6-kiconthemes`, `kf6-kio`, `kf6-kirigami`, `libportal`, `libqtxdg`, `plasma-integration`, `tiled`

---
### **`qplatformnativeinterface.h`**
- **Used 29 times**
- **Packages using it:** `LabPlot`, `Qt-Advanced-Docking-System`, `calibre`, `copyq`, `dolphin-emu`, `gwenview`, `kde-connect`, `kf6-kwindowsystem`, `kpipewire`, `krdc`, `krfb`, `kwayland`, `kwin`, `kwin-x11`, `lxqt-panel`, `obs-studio`, `plasma-dialer`, `plasma-integration`, `plasma-workspace`, `plasma-workspace-x11`, `spectacle`, `xdg-desktop-portal-kde`

---
### **`qobject_p.h`**
- **Used 5 times**
- **Packages using it:** `libqtxdg`, `python-pyside6`

---
### **`qquickitem_p.h`**
- **Used 2 times**
- **Packages using it:** `maui-mauikit-documents`

---
### **`qplatformwindow_p.h`**
- **Used 12 times**
- **Packages using it:** `crystal-dock`, `kf6-kguiaddons`, `kf6-kwindowsystem`, `kscreen`, `kwin`, `kwin-x11`, `libplasma`, `plasma-integration`, `plasma-workspace`, `plasma-workspace-x11`

---
### **`qplatformwindow.h`**
- **Used 6 times**
- **Packages using it:** `calibre`, `kddockwidgets`, `kwin`, `kwin-x11`, `libplasma`, `olive`

---
### **`qiconloader_p.h`**
- **Used 3 times**
- **Packages using it:** `kf6-kiconthemes`, `libqtxdg`, `qt6ct`

---
### **`qplatformtheme.h`**
- **Used 8 times**
- **Packages using it:** `calibre`, `kf6-kcolorscheme`, `kf6-kconfigwidgets`, `kf6-kiconthemes`, `kf6-kio`, `libqtxdg`, `lxqt-qtplugin`, `plasma-integration`, `qt6ct`

---
### **`qwaylandwindow_p.h`**
- **Used 5 times**
- **Packages using it:** `kwayland`, `layer-shell-qt`, `plasma-mobile`, `plasma-workspace`, `plasma-workspace-x11`

---
### **`qandroidextras_p.h`**
- **Used 9 times**
- **Packages using it:** `AusweisApp2`, `elisa-player`, `itinerary`, `kpublictransport`

---
### **`qicon_p.h`**
- **Used 3 times**
- **Packages using it:** `libqtxdg`

---
### **`qhighdpiscaling_p.h`**
- **Used 3 times**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`qplatformintegration.h`**
- **Used 5 times**
- **Packages using it:** `calibre`, `kwin`, `kwin-x11`, `libportal`, `plasma-integration`

---
### **`qplatformscreen.h`**
- **Used 5 times**
- **Packages using it:** `calibre`, `kwin`, `kwin-x11`, `plasma-workspace`, `plasma-workspace-x11`

---
### **`qwaylanddisplay_p.h`**
- **Used 3 times**
- **Packages using it:** `layer-shell-qt`, `plasma-workspace`, `plasma-workspace-x11`

---
### **`qwidget_p.h`**
- **Used 3 times**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`qgenericunixservices_p.h`**
- **Used 4 times**
- **Packages using it:** `calibre`, `kwin`, `kwin-x11`, `libportal`, `plasma-integration`

---
### **`qhexstring_p.h`**
- **Used 1 time**
- **Packages using it:** `libqtxdg`

---
### **`qmetaobjectbuilder_p.h`**
- **Used 3 times**
- **Packages using it:** `python-pyside6`

---
### **`qqmlmetatype_p.h`**
- **Used 1 time**
- **Packages using it:** `python-pyside6`

---
### **`qwaylandsurface_p.h`**
- **Used 2 times**
- **Packages using it:** `layer-shell-qt`

---
### **`qxkbcommon_p.h`**
- **Used 4 times**
- **Packages using it:** `kwin`, `kwin-x11`, `xdg-desktop-portal-kde`

---
### **`qzipreader_p.h`**
- **Used 3 times**
- **Packages using it:** `LabPlot`, `QXlsx`, `stellarium`

---
### **`qeventdispatcher_glib_p.h`**
- **Used 3 times**
- **Packages using it:** `kwayland`, `kwin`, `kwin-x11`

---
### **`qeventdispatcher_unix_p.h`**
- **Used 3 times**
- **Packages using it:** `calibre`, `kwayland`

---
### **`qjnihelpers_p.h`**
- **Used 3 times**
- **Packages using it:** `digikam`

---
### **`qlocale_p.h`**
- **Used 1 time**
- **Packages using it:** `kf6-kxmlgui`

---
### **`qlocale_tools_p.h`**
- **Used 2 times**
- **Packages using it:** `kosmindoormap`

---
### **`qplatformbackingstore.h`**
- **Used 3 times**
- **Packages using it:** `calibre`, `kwin`, `kwin-x11`

---
### **`qplatformdialoghelper.h`**
- **Used 3 times**
- **Packages using it:** `libfm-qt`, `plasma-integration`

---
### **`qplatformintegrationplugin.h`**
- **Used 3 times**
- **Packages using it:** `calibre`, `kwin`, `kwin-x11`

---
### **`qplatformmenu.h`**
- **Used 3 times**
- **Packages using it:** `lxqt-qtplugin`, `plasma-integration`

---
### **`qplatformservices.h`**
- **Used 1 time**
- **Packages using it:** `calibre`

---
### **`qplatformsystemtrayicon.h`**
- **Used 3 times**
- **Packages using it:** `lxqt-qtplugin`, `plasma-integration`

---
### **`qrhi_p.h`**
- **Used 2 times**
- **Packages using it:** `digikam`, `gstreamer1-plugins-good`

---
### **`qwindowsysteminterface.h`**
- **Used 3 times**
- **Packages using it:** `kwin`, `kwin-x11`, `plasma-integration`

---
### **`qzipwriter_p.h`**
- **Used 2 times**
- **Packages using it:** `LabPlot`, `QXlsx`

---
### **`MainWindowQuick_p.h`**
- **Used 2 times**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`QWidgetAdapter_quick.cpp`**
- **Used 2 times**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`qabstractitemmodel_p.h`**
- **Used 1 time**
- **Packages using it:** `texmaker`

---
### **`qcore_mac_p.h`**
- **Used 1 time**
- **Packages using it:** `qbs`

---
### **`qcups_p.h`**
- **Used 1 time**
- **Packages using it:** `xdg-desktop-portal-kde`

---
### **`qdesktopunixservices_p.h`**
- **Used 2 times**
- **Packages using it:** `calibre`, `kwin`, `kwin-x11`, `plasma-integration`

---
### **`qdnd_p.h`**
- **Used 1 time**
- **Packages using it:** `libfm-qt`

---
### **`qgenericunixtheme_p.h`**
- **Used 2 times**
- **Packages using it:** `kwin`, `kwin-x11`, `plasma-integration`, `qt6ct`

---
### **`qgenericunixthemes_p.h`**
- **Used 2 times**
- **Packages using it:** `kwin`, `kwin-x11`, `plasma-integration`, `qt6ct`

---
### **`qjsvalue_p.h`**
- **Used 1 time**
- **Packages using it:** `qcoro`

---
### **`qjson_p.h`**
- **Used 2 times**
- **Packages using it:** `itinerary`, `libquotient`

---
### **`qpixmap_raster_p.h`**
- **Used 1 time**
- **Packages using it:** `calibre`

---
### **`qplatformfontdatabase.h`**
- **Used 1 time**
- **Packages using it:** `calibre`

---
### **`qplatforminputcontext.h`**
- **Used 2 times**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qplatformthemefactory_p.h`**
- **Used 2 times**
- **Packages using it:** `qt6ct`

---
### **`qquickimage_p.h`**
- **Used 1 time**
- **Packages using it:** `qcoro`

---
### **`qwaylandinputdevice_p.h`**
- **Used 2 times**
- **Packages using it:** `layer-shell-qt`, `plasma-workspace`, `plasma-workspace-x11`

---
### **`qwaylandscreen_p.h`**
- **Used 2 times**
- **Packages using it:** `layer-shell-qt`, `lxqt-panel`

---
### **`FrameQuick_p.h`**
- **Used 1 time**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`Helpers_p.h`**
- **Used 1 time**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`TitleBarQuick_p.h`**
- **Used 1 time**
- **Packages using it:** `kddockwidgets`, `olive`

---
### **`qabstracteventdispatcher_p.h`**
- **Used 1 time**
- **Packages using it:** `kwayland`

---
### **`qabstracttestlogger_p.h`**
- **Used 1 time**
- **Packages using it:** `AusweisApp2`

---
### **`qabstractvideobuffer_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qeventdispatcher_win_p.h`**
- **Used 1 time**
- **Packages using it:** `calibre`

---
### **`qfontconfigdatabase_p.h`**
- **Used 1 time**
- **Packages using it:** `calibre`

---
### **`qhwvideobuffer_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qjni_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qplatformaccessibility.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qplatformclipboard.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qplatformcursor.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qplatformoffscreensurface.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qplatformopenglcontext.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qplatformscreen_p.h`**
- **Used 1 time**
- **Packages using it:** `libkscreen`

---
### **`qqmlglobal_p.h`**
- **Used 1 time**
- **Packages using it:** `maui-mauikit-documents`

---
### **`qqmlincubator_p.h`**
- **Used 1 time**
- **Packages using it:** `nheko`

---
### **`qqmlobjectcreator_p.h`**
- **Used 1 time**
- **Packages using it:** `nheko`

---
### **`qquickanimation_p.h`**
- **Used 1 time**
- **Packages using it:** `maui-mauikit-documents`

---
### **`qquickflickable_p.h`**
- **Used 1 time**
- **Packages using it:** `maui-mauikit-documents`

---
### **`qquickitemchangelistener_p.h`**
- **Used 1 time**
- **Packages using it:** `maui-mauikit-documents`

---
### **`qquickpixmapcache_p.h`**
- **Used 1 time**
- **Packages using it:** `plasma-wallpapers-dynamic`

---
### **`qremoteobjectrepparser_p.h`**
- **Used 1 time**
- **Packages using it:** `python-pyside6`

---
### **`qrhid3d11_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qspiaccessiblebridge_p.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qtestelementattribute_p.h`**
- **Used 1 time**
- **Packages using it:** `AusweisApp2`

---
### **`qtcore-config_p.h`**
- **Used 1 time**
- **Packages using it:** `qbittorrent`

---
### **`qtgui-config_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qtldurl_p.h`**
- **Used 1 time**
- **Packages using it:** `falkon`

---
### **`qtriangulator_p.h`**
- **Used 1 time**
- **Packages using it:** `kosmindoormap`

---
### **`qtriangulatingstroker_p.h`**
- **Used 1 time**
- **Packages using it:** `kosmindoormap`

---
### **`quniquehandle_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qunixeventdispatcher_qpa_p.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
### **`qurl_p.h`**
- **Used 1 time**
- **Packages using it:** `falkon`

---
### **`qvideotexturehelper_p.h`**
- **Used 1 time**
- **Packages using it:** `digikam`

---
### **`qwaylandshellintegration_p.h`**
- **Used 1 time**
- **Packages using it:** `layer-shell-qt`

---
### **`qwaylandshellintegrationplugin_p.h`**
- **Used 1 time**
- **Packages using it:** `layer-shell-qt`

---
### **`qwaylandshellsurface_p.h`**
- **Used 1 time**
- **Packages using it:** `layer-shell-qt`

---
### **`qwindowsysteminterface_p.h`**
- **Used 1 time**
- **Packages using it:** `kwin`, `kwin-x11`

---
## Packages Without Private Header Usage

Based on your provided list, the following packages did not have any occurrences of the grepped private headers:

- `akonadi-server`
- `angelfish`
- `fcitx5-qt`
- `fielding`
- `kaccounts-integration`
- `kf6-kirigami-addons`
- `kf6-kstatusnotifieritem`
- `kf6-kuserfeedback`
- `kf6-qqc2-desktop-style`
- `kidentitymanagement`
- `kio-extras`
- `kmail-account-wizard`
- `ksanecore`
- `libksysguard`
- `merkuro`
- `mimetreeparser`
- `nextcloud-client`
- `optiimage`
- `photoqt`
- `python-pyqt6`
- `qstardict`
- `strawberry`
- `xdg-desktop-portal-lxqt`
-------------- next part --------------
Of course. Here are the packages that use only one unique private include, along with the specific include for each.

* **copyq**: `qplatformnativeinterface.h`
* **crystal-dock**: `qplatformwindow_p.h`
* **dolphin**: `qtx11extras_p.h`
* **dolphin-emu**: `qplatformnativeinterface.h`
* **elisa-player**: `qandroidextras_p.h`
* **gstreamer1-plugins-good**: `qrhi_p.h`
* **kate**: `qtx11extras_p.h`
* **kcm_wacomtablet**: `qtx11extras_p.h`
* **kde-cli-tools**: `qtx11extras_p.h`
* **kf6-kdbusaddons**: `qtx11extras_p.h`
* **kf6-kglobalaccel**: `qtx11extras_p.h`
* **kf6-kguiaddons**: `qplatformwindow_p.h`
* **kf6-kirigami**: `qguiapplication_p.h`
* **kf6-kjobwidgets**: `qtx11extras_p.h`
* **kf6-kxmlgui**: `qlocale_p.h`
* **kglobalacceld**: `qtx11extras_p.h`
* **koko**: `qtx11extras_p.h`
* **konqueror**: `qtx11extras_p.h`
* **kontactinterface**: `qtx11extras_p.h`
* **kpipewire**: `qplatformnativeinterface.h`
* **kpublictransport**: `qandroidextras_p.h`
* **krdc**: `qplatformnativeinterface.h`
* **krdp**: `qplatformnativeinterface.h`
* **kruler**: `qtx11extras_p.h`
* **kscreen**: `qplatformwindow_p.h`
* **kscreenlocker**: `qtx11extras_p.h`
* **ktouch**: `qtx11extras_p.h`
* **libquotient**: `qjson_p.h`
* **obs-studio**: `qplatformnativeinterface.h`
* **okular**: `qtx11extras_p.h`
* **plasma-desktop**: `qtx11extras_p.h`
* **plasma-dialer**: `qplatformnativeinterface.h`
* **plasma-mobile**: `qwaylandwindow_p.h`
* **plasma-oxygen**: `qtx11extras_p.h`
* **plasma-wallpapers-dynamic**: `qquickpixmapcache_p.h`
* **plasma5support**: `qtx11extras_p.h`
* **powerdevil**: `qtx11extras_p.h`
* **qbittorrent**: `qtcore-config_p.h`
* **qbs**: `qcore_mac_p.h`
* **Qt-Advanced-Docking-System**: `qplatformnativeinterface.h`
* **stellarium**: `qzipreader_p.h`
* **texmaker**: `qabstractitemmodel_p.h`
* **tiled**: `qguiapplication_p.h`
* **xwaylandvideobridge**: `qtx11extras_p.h`
* **yakuake**: `qtx11extras_p.h`
* **zeal**: `qtx11extras_p.h`