[Development] Semi-private headers in Qt

[Artem Dyomin]

  *
 c++ keywords (volatile, mutable), they might suggest that the folder has something to do with c++ mutables, volatiles, etc.
  *
include <QtGui/6.12/qrhi.h> requires updates all usages in Qt code before each release, not sure that we want to handle this dogfood.
  *
spi makes sense for me.


Confidential
________________________________
From: Tor Arne Vestbø <Tor.arne.Vestbo at qt.io>
Sent: Thursday, May 21, 2026 1:41 PM
To: Volker Hilsheimer <volker.hilsheimer at qt.io>
Cc: Edward Welbourne <edward.welbourne at qt.io>; development at qt-project.org <development at qt-project.org>; Artem Dyomin <artem.dyomin at qt.io>
Subject: Re: [Development] Semi-private headers in Qt


On 21 May 2026, at 13:30, Volker Hilsheimer via Development <development at qt-project.org> wrote:

One idea I just had was to use the major.minor version number of Qt.

#include <QtGui/6.12/qrhi.h>

The advantage is that you are clearly seeing that you are using an API that is specific to that Qt version.
The disadvantage is that you have to change the include statement when upgrading Qt version, but that might as much be an advantage because it creates awareness - just because things still compile doesn't necessary mean that they also still work the same way. And it can be made very simple by having a single wrapper-header for a project.

Failing that my preference would be either

unstable, unsupported, or semiprivate

I suggest we squash all these uses-cases into an opaque `spi` suffix, which can covers both semi-private (experimental), and service-provider (system integration) interfaces. It’s also short to write :)

#include <QtGui/spi/qplatformwindow.h> // Technically both semi-private and service-provider interface

#include <QtMultimedia/spi/qgstreamvervideosource.h> // Semi private API

Tor Arne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20260521/7231989e/attachment.htm>