Linux Build docs improvements - #1691
Merged
tdewey-rpi merged 5 commits intoAug 13, 2026
Merged
Conversation
A gitignore pattern containing no slash matches by basename at every
depth, not just where it was meant to apply. Every build product in this
file lives at the repository root, but five of the patterns were written
unanchored, so they also matched tracked source files further down the
tree:
* build-** every qt/build-qt*.sh (five scripts)
* qt-build** qt/qt-build-common.sh
* appimage-* debian/appimage-pack.sh
* timezones.txt src/timezones.txt, the fallback data the generator
falls back to; the generated file is
timezones_generated.txt and lives in the build tree
* screenshot.png tracked, and displayed by README.md
Being already tracked, those files kept working, and the breakage only
showed up on a fresh git add. debian/appimage-pack.sh is where it did:
written, silently ignored, and so never committed.
The existing !debian/build-*.sh negation was this bug being patched once
already, for one directory. Anchoring the patterns fixes it generally and
makes the negation unnecessary, so drop it. Also anchor the remaining
root-only patterns (obj-, AppDir-, debroot-embedded-, test-cli-, .debian/,
out/) which had the same latent problem, and replace the appimage-* catch
with the directory it was actually for, appimage-tools/.
Verified no tracked file is ignored any more, and that out, .debian,
AppDir-*, appimage-tools, qt-build*, qt-src, build-*, debroot-embedded-*
and *.AppImage are all still ignored.
QT_VERSION_DEFAULT in qt/qt-build-common.sh is what the build-qt*.sh scripts use, but debian/lib.sh carried its own copy of the version literal, and the release pipeline invokes those scripts with --version="$QT_VERSION". The two agreed today by coincidence; nothing made them agree tomorrow, and disagreeing would have meant the pipeline asking for one version and validating the cache against another. Read QT_VERSION_DEFAULT out of qt-build-common.sh instead. Extract it with sed rather than sourcing the file: it also sets ARCH, PLATFORM and CORES, which would clobber the scripts that source debian/lib.sh. QT_MIN_VERSION had the same problem against a different authority — it duplicated the minimum from the find_package(Qt6 ...) call in src/CMakeLists.txt, which is what actually enforces it. Read it from there, keeping the previous literal as a fallback. Environment overrides still take precedence in both cases, so a one-off build against another version works as before.
The rootless multi-architecture chroot build was essentially undocumented: debian/release.sh --help lists the commands, and everything else was recoverable only by reading roughly 2,800 lines of shell across twenty-odd scripts. Add doc/linux-build.md covering the model (every architecture, the host's own included, builds in its own bookworm mmdebstrap chroot, and why there is deliberately no host-native path), prerequisites, the commands, the on-disk layout, and each of the five stages: keyrings, chroot, Qt, AppImages and binary packages. Then the embedded package, the bundling policy, the full configuration table, troubleshooting and cleanup. Weighted towards the things that are surprising rather than the things that are merely true, since the latter can be read off the scripts: * AppDirs are built inside the target chroot but packed on the host, because linuxdeploy and appimagetool are themselves AppImages and must match the machine executing them, not the target. * appimagetool silently embeds its own host runtime when ARCH is all you give it, which is why --runtime-file is mandatory for a cross-pack and why release.sh status re-checks staged AppImages with file(1). * dpkg-buildpackage writes to $TOP/.., only $TOP is bind-mounted, so the artifacts land inside the chroot rootfs and have to be collected back out. * The AppImage and embedded exclusion predicates are deliberately different, and pruning QML means pruning modules, never libraries. No Qt version is quoted; the doc points at the script that selects it.
The Linux section of CONTRIBUTING.md still described the build as it was before the crossbuild pipeline, and had stopped working rather than merely aged: * git clone --depth 1 leaves no submodules for the vendored third-party dependencies and no tags for the git describe that produces the version string. * sudo ./qt/build-qt.sh into /opt/Qt, then a bare ./create-appimage.sh, bypasses the chroot entirely and links the result against the host's libraries — the thing the pipeline exists to prevent. Replace it with the pipeline, plus a separate short CMake loop for people iterating on the application rather than producing artifacts. The embedded section claimed the package "uses the same vendored release Qt as the desktop and CLI packages ... so there is no separate embedded Qt to build". That has not been true since the embedded Qt became its own -no-opengl -no-dbus -qpa linuxfb build in its own cache variant. State what it actually builds and why the netboot image forces it. create-embedded.sh suggested ./qt/build-qt.sh --version=6.9.1 when it could not find Qt: the wrong script, since that builds the desktop Qt this package cannot use, and a version that has not been current for some time. Point at build-qt-embedded.sh and name no version. Also drop the hardcoded Qt versions from the Windows and macOS Qt6_ROOT examples, which had drifted to three different values between them.
The four guides named a concrete Qt version on 29 lines between them, in install paths, --help transcripts and prose. They had drifted to four different values (6.8.0, 6.9.1, 6.9.3, 6.11.1), none of which was the version the scripts actually build. Replace them all with <version>, and explain it once per guide with a note pointing at QT_VERSION_DEFAULT in qt-build-common.sh — the single place the version is selected, and now the only place it is written down. Also note in the armhf guide that release builds do not need that script: the pipeline builds armhf Qt inside an armhf chroot via debian/ensure-qt.sh.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.