[Development] Semi-private headers in Qt

[Volker Hilsheimer]

> Am 21.05.26 um 13:30 schrieb Volker Hilsheimer via Development:
>>> On 21 May 2026, at 20:07, Edward Welbourne via Development <development at qt-project.org> wrote:
>>> 
>>> Artem Dyomin (21 May 2026 12:49) wrote:
>>> 
>>>> Well, according to the input, the word "experimental" brings messages
>>>> regarding temporary status and transferring to public API in the future,
>>>> that doesn't fit well to some cases.  To address this, I'd rather choose
>>>> the word that reflects its semiprivate status and limited compatibility
>>>> guarantees.
>>>> 
>>>> * protected - for me, it doesn't sound clear in terms of headers
>>>> * limited_compat - looks good, but doesn't reflect private status
>>>> * semiprivate - perhaps better as it reflects what it does
>>>> 
>>>> So, what about "semiprivate"?
>>> It's a half-way decent answer.
>>> One other name springs to mind, more apt at least than "protected", but
>>> likewise inspired by terms from C++: "mutable" - after all, we're
>>> talking about APIs on which we don't promise compatibility - they may
>>> change from one release to the next.
>>> 
>>> Eddy.
>> 
>> 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.
>> 
>> […]

> On 21 May 2026, at 23:55, Mathias Hasselmann via Development <development at qt-project.org> wrote:
> 
> This goes into the same direction I was thinking of: Versioning.
> 
> What speaks against putting these APIs into versioned headers and namespaces?
> 
> Mathias


We wouldn’t be able to maintain multiple versions of those APIs in parallel anyway, so a <QtGui/6.12/qrhi.h> would be gone once we bump the version that dev build to 6.13. Or they would linger as stale headers in self-built Qt.

And as we are using those headers ourselves as installed headers in Qt modules (i.e. Qt Multimedia has to #include <QtGui/rhi/qrhi.h> today), it would be very impractical indeed to use that scheme, probably requiring some weeks of submodule update catch-up just to get to a worktree that builds.

Volker