Skip to content

Linux Build docs improvements - #1691

Merged
tdewey-rpi merged 5 commits into
raspberrypi:mainfrom
tdewey-rpi:dev/tdewey/linux-build-docs
Aug 13, 2026
Merged

Linux Build docs improvements#1691
tdewey-rpi merged 5 commits into
raspberrypi:mainfrom
tdewey-rpi:dev/tdewey/linux-build-docs

Conversation

@tdewey-rpi

Copy link
Copy Markdown
Collaborator

No description provided.

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.
@tdewey-rpi
tdewey-rpi merged commit 21c43d8 into raspberrypi:main Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant