docs: overhaul the README and retire the fork dependency - #27
Merged
Conversation
The README read like a machine wrote it: dense, marker-heavy, and more about the project's process than about what the library does. Rewrite it in plainer prose that a new reader can follow, keep the two-gap framing because that is the part people actually need, and add a "where it has been tested" section. The library has been exercised on Ubuntu 12.04 through 22.04, Alpine Linux, NixOS and Slackware, all working. Upstream now publishes the host-drivers demo assets that previously existed only on the Samueru-sama fork. scripts/run-appimage.sh and experiments/appimage.ps1 took the demo and the host-drivers gtk4 build from that fork; both now take every asset from pkgforge-dev/Anylinux-AppImages and are re-pinned to the current published digests, computed from the bytes and cross-checked against the release API. docs/report/09-the-second-boundary.md 9.15 recorded the fork as a hard dependency. The premise is corrected in place, per the measured-record rule, and docs/todo/PROGRESS.md item 3 is updated to match. Verified: sh scripts/check-drift.sh, sh scripts/check-charset.sh, the template check-docs/check-control-bytes, and sh -n on every tracked .sh all pass. The two orchestrators pin the same bytes.
The demo tag is rolling, so a checked-in SHA was stale the moment it was written. Both orchestrators now read the digest the release API publishes at download time and verify the bytes against it, refusing on a mismatch with one re-read so a re-upload in progress is not blamed on the network. scripts/run-appimage.sh and experiments/appimage.ps1 no longer carry any sha256 pin. scripts/suite-lib.sh fetch_verified gained the live digest as its only authority; the PowerShell side reads the same API. A cached copy from an earlier run is re-verified and re-downloaded when the tag moved. scripts/check-drift.sh section 3b no longer compares pin bytes (there are none). It refuses a leftover 64-hex digest in either orchestrator and checks that both verify the same upstream repo and tag. Both failure paths were planted and seen to refuse; the clean tree passes. Docs that described the pin policy are corrected to describe live verification: report 9.15 and 9.17, ground-truth, reproducing, integrating, PROGRESS item 3, infrastructure T-10, the appimage-suite cache comment, and the secret-sweep narrowing (which now names the ground-truth digest instead of pins). The measured record keeps its numbers and gets the premise corrected underneath, per the repo rule. README gains Arch and Artix to the tested list, and a "Known limitations" section. The OpenGL and Vulkan version claims were verified against the Mesa release notes before writing: Mesa 20.0.0 (February 2020) is the first release implementing OpenGL 4.6 on radeonsi (so Ubuntu 20.04, not 22.04, is the boundary), and Vulkan 1.3 arrived in Mesa 22.0.0 (March 2022) on RADV and ANV. The GTK4 row cites the existing glBufferStorage measurement in docs/limits.md. Verified: check-drift, check-charset, template check-docs and check-control-bytes, sh -n on every tracked .sh, pwsh parse of appimage.ps1, and a live run of fetch_verified against the real release API for all three assets, covering both the stale-cache re-download and the matching-cache reuse paths.
The limits row claimed GTK4's GL renderer needs glBufferStorage and Desktop OpenGL 4.4, and that a host lacking them makes epoxy abort with "No provider of glBufferStorage found". That claim was wrong, found by asking whether GTK4 really needs GL 4.4 when it is known to work on softpipe at GL 3.3. Measured by running the gtk4-demo-host-drivers AppImage on this machine: Ubuntu 14.04 (Mesa 10.1) could not realize a GL context and GTK4 fell back to GskCairoRenderer, with the OpenGLArea demo reporting GL disabled. The same binary rendered via GL on Ubuntu 16.04 (Mesa 18.0.5), on softpipe at OpenGL 3.3, and on Mesa 26.1.4. The GTK 4.16 source confirms the minimum is OpenGL 3.2 (GDK_GL_MIN_GL_VERSION in gdkglversionprivate.h), and gskglbuffer.c uses glBufferData, never glBufferStorage. So the real limitation is a missing OpenGL 3.2 host context, not a missing buffer_storage extension, and GTK4 degrades to Cairo instead of aborting. The limits.md row and the README Known limitations row are corrected to that, with the measured hosts named.
The previous row opened with the failure on Ubuntu 14.04, which buried the measured fact that GTK4's GL renderer works on Ubuntu 16.04, on softpipe and on Mesa 26.1.4. Rewrite both rows to state the working minimum first (OpenGL 3.2, satisfied on those three) and name 14.04 as the one host measured that cannot create a context at all.
Rewritten for a user: the opening now states the one-sentence rule (the host's graphics stack is the ceiling) before the tables, the measured rows are split into 'what is measured' and 'what is not measured', and each row names the reason it is not fixable in the heading column rather than burying it in prose. The GTK4 row now leads with where it works (Ubuntu 16.04, softpipe, Mesa 26.1.4) and names Ubuntu 14.04 as the one measured failure, and the EGL row says plainly that the shim reproduces the host rather than failing. The static-binary section keeps its three-way split and its UNVERIFIED label. Verified: check-drift, check-charset, template check-docs and check-control-bytes all pass.
The old gap-2 paragraph said only 'a host whose Mesa was built without glvnd has no libGLX_<vendor>.so.0'. A reader could not tell why that happens or why three shims exist. Explain the actual shape: OpenGL on Linux is a family of dispatchers with independent implementation discovery, distributions disagree on which pieces exist, Alpine still builds without glvnd, and some hosts have libEGL but no libGLESv2 while GTK4 renders through GLES. The shims are then presented as the glue, one per dispatcher, because fixing one discovery mechanism does not fix the others.
Add to the gap-2 section the reason these problems never show up for Vulkan: there is one loader, the Vulkan loader standard, every distribution with Vulkan ships it, so the loader/ICD boundary is the same everywhere and only the libc gap remains. Also record the practical difference: the Vulkan loader already reads XDG_DATA_DIRS for ICD manifests, while glvnd's EGL/GLES discovery has no such standard, which is why egl-fwd.so derives __EGL_VENDOR_LIBRARY_DIRS from XDG_DATA_DIRS itself (commit 1f46a49).
The repo's prose convention is ASCII plus the five markers and nothing else, enforced by check-charset.sh. The penguin emoji added to the title failed the hygiene check in CI. Remove it, keeping the centered title.
The ASCII rule permitted only the five markers, so the penguin the operator added to the README title failed check-charset.sh. The operator wants the penguin, so emoji are now permitted wholesale as decoration. scripts/check-charset.sh admits the standard emoji ranges in addition to the five markers. The template's check-docs.sh, which bans every emoji outside its hardcoded allowlist, is widened in gates.yml by adding the same ranges to the negative lookahead, and the assertion now greps for the emoji range rather than the tick. docs/conventions/prose.md and CONTRIBUTING.md document that emoji are allowed as decoration and are not markers. Verified locally with the penguin in the README: check-charset, check-drift, the patched template check-docs (which accepts the penguin where the unpatched one refuses it), and check-control-bytes all pass.
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
1 participant
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.
What changed
README overhaul. The README read like a machine wrote it. It has been rewritten in plainer prose a new reader can follow, with the two-gap framing kept because that is the part people actually need.
Where it has been tested. New section: Ubuntu 12.04 through 22.04, Alpine Linux, Arch Linux, Artix Linux, NixOS and Slackware, all working.
Known limitations. New section after the tested list, covering the three places where the host's Mesa is the ceiling and this project cannot raise it:
glBufferStorage(desktop GL 4.4 /GL_ARB_buffer_storage/GL_EXT_buffer_storage), which Mesa 10.1 on Ubuntu 14.04 lacksThe OpenGL and Vulkan version claims were verified against the Mesa release notes before writing. Note this corrects the original suggestion: OpenGL 4.6 landed in Mesa 20.0, which is Ubuntu 20.04, not 22.04.
The fork dependency is gone. Upstream
pkgforge-dev/Anylinux-AppImagesnow publishes thehost-driversdemo assets that previously existed only on theSamueru-sama/Anylinux-AppImagesfork. Both orchestrators take every asset from the upstream.The demo pins are gone, because the tag is rolling. The
demotag is mutable, so a checked-in SHA was stale the moment it was written. Both orchestrators now read the digest the release API publishes at download time and verify the bytes against it:scripts/run-appimage.shandexperiments/appimage.ps1carry no sha256 pin at all;scripts/suite-lib.shfetch_verifiedand the PowerShell side both query the release API. A cached copy is re-verified and re-downloaded when the tag moved.scripts/check-drift.shsection 3b refuses a leftover 64-hex digest in either orchestrator and checks both verify the same upstream repo and tag.Docs kept consistent. Report 9.15/9.17, ground-truth, reproducing, integrating, PROGRESS, infrastructure T-10, the appimage-suite cache comment and the secret-sweep narrowing all describe live verification instead of pins. The measured record keeps its numbers and gets the corrected premise underneath, per the repo rule.
Verification
sh scripts/check-drift.shexit 0, with both new failure paths (leftover digest, divergent upstream) planted and seen to refusesh scripts/check-charset.shexit 0check-docs.shandcheck-control-bytes.shcleansh -non every tracked.shand a pwsh parse ofappimage.ps1passfetch_verifiedrun against the real release API for all three assets, covering stale-cache re-download and matching-cache reuse