Bundled Qt 6 XCB QPA private headers
====================================

Why they are needed
-------------------

The dxcb platform plugin subclasses and hooks into Qt's own XCB platform
plugin (QXcbIntegration, QXcbWindow, QXcbConnection, ...). Doing so
requires the private headers of the Qt xcb-qpa module.

Debian's qt6-base-private-dev does not ship those headers yet. Upstream Qt
builds the xcb-qpa module with NO_MODULE_HEADERS, so no QtXcb private
headers are installed at all -- unlike the Qt 5 situation, where
qtbase5-private-dev did ship them. There is therefore nothing in the
archive that this package could build-depend on to get them.

This has been reported against qt6-base as

  * https://bugs.debian.org/1142437
  * qt6-base: Please enable installation of QtXcbQpa private headers,
    similar to Qt5

Once that wishlist bug is addressed, the patch described below becomes
unnecessary and should be dropped -- see "Refreshing for a new Qt
version" at the end of this file.

Upstream works around this by vendoring a copy of the headers for each
Qt version it supports, under:

    xcb/libqt6xcbqpa-dev/<qt-version>/

and selecting the directory matching the Qt version being built against.
Upstream currently ships older versions that do not match the Qt version
in Debian unstable.

What this package does
----------------------

debian/patches/0001-Add-libqt6xcbqpa-dev-6.10.2-private-headers.patch
adds a further directory:

    xcb/libqt6xcbqpa-dev/<version>/

The headers are taken verbatim from the qtbase source
(src/plugins/platforms/xcb/), i.e. from the same upstream release as the
libqt6gui6/qt6-base binaries currently in Debian unstable. They are not
modified beyond what is needed to build.

Refreshing for a new Qt version
-------------------------------

These headers are tightly coupled to the Qt build they are compiled
against. The binary package picks up a versioned dependency

    qt6-base-private-abi (= <qt-version>)

via dh_shlibdeps, so a package built will not be
installable once Debian moves to a different Qt 6 private ABI. That
makes the breakage loud rather than subtle, but it does mean the headers
must be refreshed on every Qt 6 transition.

If Debian's qt6-base-private-dev ever starts shipping the QtXcb private
headers (see https://bugs.debian.org/1142437), this patch should be
dropped entirely. In that case the first branch of the same logic picks
them up automatically from
    <includedir>/QtXcb/<version>/QtXcb/private
or the build can be pointed at them explicitly by passing
    -DQT_XCB_PRIVATE_HEADERS=<path>
in debian/rules, which takes precedence over everything above.

Licensing
---------

The bundled headers are Qt sources and are covered by the
"xcb/libqt6xcbqpa-dev/*" paragraph in debian/copyright
(LGPL-3 or GPL-2 or GPL-3, with an additional proprietary Qt Commercial
option that is not exercised here). They are not Deepin code and are
deliberately kept separate from the rest of the tree.

 -- Boyuan Yang <byang@debian.org>, Sat, 08 Aug 2026 14:41:58 -0400
