Move the binary Qt pin from 6.8.3 to Qt 6.12 LTS (supersedes #4688)

Summary

Tracking issue for moving AetherSDR's binary Qt pin from 6.8.3 to Qt 6.12 LTS. Supersedes #4688, which tracked getting every artifact onto one pinned 6.8.3 and is now down to two documentation checkboxes (carried forward below).

Qt 6.12.0 is scheduled for 2026-09-22 and is the next LTS (Qt shifted the LTS cadence so 6.12 follows 6.8; 6.11 is not LTS). It is also the last Qt release that supports Windows 10, with LTS support running to roughly 2031.

Policy carried over from #4688, unchanged: 6.8 stays the source floor (Debian 13 / Pi OS Trixie ship 6.8.2; the Constitution requires Pi 5), 6.12.x becomes the binary pin. That means the pin and the floor diverge for the first time, which is what most of the work below is about.

Where every pin lives today

What we lose (or must decide)

1. Intel macOS DMG floor rises from 12 to 13 — the only hard user-facing loss

Qt ≥ 6.10 requires macOS 13. The Intel leg deploys at 12.0 specifically to serve aging hardware (#4532). With 6.12 the artifact will not launch on Monterey regardless of CMAKE_OSX_DEPLOYMENT_TARGET. Decision: re-floor the Intel DMG to 13.0, or retire it.

2. Windows 10 gets a ceiling

6.12 still supports Windows 10 1809+ (MSIX manifest already targets 19041+). Nothing lost now, but 6.12 becomes the last Qt for Win10 users; the bump after this one drops them.

3. x86_64 AppImage glibc floor probably rises — must verify with readelf

Qt now builds Linux binaries on Ubuntu 24.04. #4670 verified the 6.8.3 arm64 tree needs GLIBC_2.38; the x86_64 6.8.3 tree ran on jammy. The 6.11 docs say binaries are "linked against glibc 2.34" and "built on Ubuntu 24.04", which is contradictory. If the 6.12 x86_64 libQt6Gui.so.6 needs 2.38, the x86_64 leg moves to noble and users on Ubuntu 22.04 / Debian 12 / RHEL 9 lose the AppImage. Gate the runner change on the readelf result, not on the docs.

4. Pin ≠ floor means 6.12-only APIs can slip in unnoticed

Three version-guarded branches already exist in the tree because contributors build on newer distro Qt:

• src/gui/FreeDvReporterDialog.cpp:44, src/gui/DxClusterDialog.cpp:284 — beginFilterChange/endFilterChange (6.10+)
• src/core/AudioEngine.cpp:364 — QAudio::UnderrunError removed in 6.11

Once CI is on 6.12, nothing compiles the 6.8 floor. #4688 item 5 (a floor-version CI job) becomes mandatory, not optional.

5. QRhi has no source/binary compatibility guarantee across minors

Qt states QRhi is semi-public: "no source or binary compatibility guarantees… source incompatible changes… will only be made in minor releases." We are jumping four minors. Exposure:

• ~60 QRhiWidget refs + full QRhi surface (pipelines, samplers, texture uploads, SRBs) in SpectrumWidget, WaveformWidget, PanadapterStack, DssRenderer
• Three hand-located private-header include paths in CMakeLists.txt (Debian multiarch, aqtinstall SDK, macOS framework) keyed on ${Qt6_VERSION}
• The QRhiWidgetPrivate cleanup-callback crash workarounds at src/gui/PanadapterStack.cpp:1185, src/gui/SpectrumWidget.cpp:2366, src/gui/WaveformWidget.cpp:321 (#2495) encode 6.8 private internals and must be re-validated on Metal, D3D, Vulkan and OpenGL — a changed QRhiWidgetPrivate could silently invalidate the sequencing.
• #4704 (Wayland waitForFrameSync deadlock) should be re-tested; 6.11 Wayland stability fixes may move it either way.

6. Qt Multimedia audio backends were reworked 6.9→6.12

Several hundred QAudioSink/QAudioSource/QAudioDevice/QMediaDevices refs. 6.10 adds a native PipeWire backend (device names, default-device tracking and hotplug change on Linux). Needs a live audio smoke pass on PulseAudio, PipeWire, WASAPI and CoreAudio — green CI proves nothing here.

7. Cost items (not losses)

• qtkeychain rebuilds once per leg (cache keys embed the Qt version).
• TSan/ASan suppressions were tuned against 6.8.3 signatures; expect churn in sanitizers.yml.
• Every table row above is a hand-edit; easy to leave one behind (that is exactly what #4688 was filed about).

What we gain (project-relevant only)

Audio — the two items that unlock something we cannot do today

• Callback-based QAudioSink::start(Callback&&) / QAudioSource (6.11). Every sink today is push/pull through a QIODevice fed by our own timers — AudioEngine, CwSidetoneQAudioSink ("(push, 2ms timer)"), QuindarLocalSink. The callback API is the one that deletes the 2 ms polling loop on the path where latency is audible, and is the same model PortAudio gives us. May let the "try each buffer rung with a real start()" ladder go away.
• nativePeriodFrameCount / setNativePeriodFrameCount (6.12). AudioEngine sizes the Windows RX buffer by hand (~L3964) and only reports bufferSize(). Device period control is the missing knob for underrun tuning.
• Native PipeWire backend (6.10) — see §6; gain and test bill together.
• Frame-count buffer ops (6.10) — removes repeated bytes↔frames arithmetic.

Accessibility (JAWS commitment, #4896)

• QWidget::accessibleIdentifier (6.9): stable, non-localized ID separate from the spoken name; shared handle for screen readers and the automation bridge (700+ a11y call sites).
• QStyleHints::accessibility() / QAccessibilityHints (6.10, motionPreference in 6.12): OS contrast + reduced-motion prefs. We have ~22 animation sites and no reduced-motion handling. Contrast-mode support landed in Fusion/Windows 11 styles alongside.
• AT-SPI Collection interface + Orca browse mode (6.11, Linux); Windows top-level/focus a11y fixes (6.11). Free.
• New Switch role and Orientation attribute (6.11) fit the applets' toggles and vertical sliders.

Rendering

• QRhi::enumerateAdapters() (6.10): GpuSelector::applyAtStartup() currently picks a GPU blind via env vars before QApplication; real enumeration lets the Display menu show adapter names.
• D3D vblank watcher thread (6.9): lower CPU/latency on Windows, no code change.

Models / views

• beginFilterChange/endFilterChange become the single path (drops the ifdefs + 3 remaining invalidateFilter() calls) — only if the floor moves, otherwise the guards stay.
• QAbstractItemView::updateThreshold (6.9), QHeaderView memory work: spot tables.

Platform / infra

• Wayland: xdg-toplevel-icon (6.9), server-side key repeat + SSD preference + session management (6.11/6.12). main.cpp already prefers native Wayland.
• Windows: manifest auto-generation (6.11), windeployqt --appx (6.12) — could shrink packaging/windows/AetherSDR.exe.manifest and create-msix.ps1 (then check-dpi-awareness.ps1 verifies the generated one).
• QThread::setServiceLevel() (6.9): portable QoS hints; we set no thread priorities anywhere today — DSP/audio threads could declare latency-sensitive.
• Network: per-request TCP keepalive (6.11) for SmartLink/PSK Reporter long-lived connections; QHostInfo::clearCache() (6.12) for reconnect after network change.
• QTest: defaultTryTimeout (6.11) for our 65 QTRY_* sites; benchmark variance (6.12); failOnWarning() catches criticals.
• QSerialPort::writeBufferSize (6.10) for CAT/rotator streams.

Not relevant despite the headlines

Qt Quick 3D XR, QRangeModelAdapter, Network Auth device flow (SmartLink has its own Auth0 flow), FFmpeg pitch compensation, HarmonyOS.

Plan

• Gate: wait for Qt 6.12.0 (2026-09-22) + first aqt/install-qt-action availability; do not bump to 6.12 beta.
• readelf -V the 6.12 x86_64 and arm64 Linux trees; record the GLIBC_ floor here before touching appimage.yml runners.
• Decide the Intel DMG: re-floor to 13.0 or retire (#4532 context).
• Add the floor-version (6.8) CI lane (#4688 item 5) before the pin moves.
• Bump the pin in all seven places in the table; keep find_package(Qt6 6.8).
• Port/re-validate the QRhi path on all four backends; re-test #2495 workarounds and #4704.
• Live audio smoke on PulseAudio, PipeWire, WASAPI, CoreAudio (device enumeration, default-device follow, hotplug, underrun).
• Re-tune sanitizer suppressions.
• Docs: README dependency section, CMake floor error text, AGENTS.md Qt claims.

Carried over from #4688 (still open there)

• QRhiWidget was Technology Preview in 6.7 and supported only from 6.8 — fix the wording.
• Update the README "ship Qt 6.8.3 LTS" claim (becomes "6.12.x LTS" once the pins above land — not before).

Follow-ups worth their own issues once on 6.12

• Callback-based audio sinks (sidetone first, then AudioEngine)
• Reduced-motion / contrast via QAccessibilityHints
• accessibleIdentifier on bridge-addressable widgets
• enumerateAdapters() in the Display menu
• QThread::setServiceLevel on DSP/audio threads

Sources: Qt 6.12 Release wiki · Qt 6.12 Beta 1 · What's New 6.12 (dev snapshot) · 6.11 · 6.10 · 6.9 · Supported Platforms 6.11 · Supported Platforms 6.10 · Windows 10 EOL plans in Qt · QRhi compatibility statement · LTS schedule change