fix(npm): run on glibc older than the builder's — route Ubuntu 22.04 / Debian 12 / RHEL 9 to the static build (#6298)

[proggeramlug]

Closes #6298.

The hole

release-packages.yml builds every glibc Linux target on ubuntu-24.04 / ubuntu-24.04-arm — glibc 2.39. The npm launcher (npm/perry/bin/perry.js) only ever appended -musl when it detected a musl host; there was no glibc version check anywhere in npm/, and packaging/install.sh had no libc detection at all.

So every glibc distro below 2.39 gets a binary its dynamic loader refuses:

Distro	glibc	before
Ubuntu 22.04 LTS	2.35	GLIBC_2.39 not found
Debian 12 (bookworm)	2.36	GLIBC_2.39 not found
RHEL 9 / Rocky 9 / Alma 9	2.34	GLIBC_2.39 not found
Amazon Linux 2023	2.34	GLIBC_2.39 not found
Alpine (via install.sh)	musl	downloaded the glibc tarball

Perry already publishes exactly the artifact these hosts need: perry-linux-{x86_64,aarch64}-musl is a fully-static PIE — I checked the shipped ELF, it has no PT_INTERP and no libc dependency at all.

What this PR does

Routes old-glibc hosts to that static build.

• npm/perry/bin/detect.cjs (new) — resolution rules, split out so they can be tested without the machine under them. GLIBC_BUILD_FLOOR = "2.39" is a named constant documented against the builder image; below it, Linux hosts resolve to @perryts/perry-linux-{x64,arm64}-musl.
• npm/perry/bin/perry.js — walks candidate packages in preference order, prints a one-time notice when it lands on the static build (stamped in tmpdir; PERRY_NO_FALLBACK_NOTICE=1 silences), and when the musl package isn't installed replaces the loader error with the exact command to fix it.
• packaging/install.sh — detects musl and old glibc, downloads perry-linux-<arch>-musl.tar.gz. This path needs no user action at all.
• .github/workflows/npm-launcher.yml (new) — path-filtered CI: the hermetic self-test, plus an end-to-end job on a real ubuntu-22.04 runner.
• Docs — glibc floor + fallback in installation.md and the npm README. Also corrects the README release-matrix section, which still claimed the Linux legs build on ubuntu-22.04 (they moved to ubuntu-24.04 in v0.5.860 — that move is what raised the floor).

Bonus robustness: a musl-detected host now falls back to the glibc package if the musl one is missing, which un-breaks the empty-glibcVersionRuntime case from #116.

Verification

Self-test (node npm/perry/test/detect.test.cjs) — 2.31 / 2.34 / 2.35 / 2.36 / 2.39 / 2.41 / musl / no-report hosts, both arches, plus a check that the packages it names really are optionalDependencies built by the release matrix:

glibc / musl routing (linux-x64, floor = 2.39)
  2.31 (Ubuntu 20.04)      linux-x64-musl       glibc-too-old
  2.34 (RHEL 9 / AL2023)   linux-x64-musl       glibc-too-old
  2.35 (Ubuntu 22.04)      linux-x64-musl       glibc-too-old
  2.36 (Debian 12)         linux-x64-musl       glibc-too-old
  2.39 (Ubuntu 24.04)      linux-x64            native
  2.41 (newer)             linux-x64            native
  (musl / Alpine)          linux-x64-musl       musl

The floor is pinned to reality: the self-test parses the release matrix and fails if the -unknown-linux-gnu legs move off ubuntu-24.04 without GLIBC_BUILD_FLOOR being revisited. Bumping the builder can't silently re-break this.

End-to-end on a real Ubuntu 22.04 runner (npm-launcher workflow, this PR): installs the published packages the way a user does, reproduces the bug, then runs the patched launcher against them.

Run: https://github.com/PerryTS/perry/actions/runs/29233234338 — Ubuntu 22.04 (glibc 2.35) end-to-end, green. Verbatim:

ldd (Ubuntu GLIBC 2.35-0ubuntu3.13) 2.35
node reports glibcVersionRuntime: 2.35

# 1. the bug — the binary npm actually picks today
$ ./node_modules/@perryts/perry-linux-x64/bin/perry --version
.../perry-linux-x64/bin/perry: /lib/x86_64-linux-gnu/libc.so.6:
    version `GLIBC_2.39' not found (required by .../perry-linux-x64/bin/perry)
exit=1

# 2. the launcher from this PR, same machine
$ node node_modules/@perryts/perry/bin/perry.js --version
[perry] glibc 2.35 is older than the prebuilt glibc binary requires (>= 2.39), so Perry is
        running its fully-static Linux build (@perryts/perry-linux-x64-musl).
[perry] Same compiler; the static build cannot produce perry/ui (GTK4) apps. Set
        PERRY_NO_FALLBACK_NOTICE=1 to silence this. Details: .../issues/6298
perry 0.5.1220

# 3. it is a working compiler, not just a binary that loads
$ node node_modules/@perryts/perry/bin/perry.js hello.ts -o hello && ./hello
hello 22.04 2,4,6            # assertion in the job: test "$(./hello)" = "hello 22.04 2,4,6"

$ ldd ./hello
        linux-vdso.so.1
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6      # ordinary glibc-dynamic output

Two things worth calling out from that run:

• The notice is genuinely one-time. It appears on the --version invocation and not on the subsequent compile invocation.
• The static compiler emits ordinary glibc binaries. The musl-built libperry_runtime.a / libperry_stdlib.a link cleanly under the host's glibc cc, and the output is a normal dynamic glibc executable — the static-ness is confined to the compiler, it does not leak into what users ship. I checked why before trusting it: those archives bundle no musl libc objects (only Rust CGUs + compiler-builtins), and all 380 of their libc-facing undefined symbols are plain POSIX/ISO-C names (__errno_location, __xpg_strerror_r, __cxa_thread_atexit_impl, __tls_get_addr, accept4, …) that glibc exports. Nothing musl-internal to resolve.

Local verification of the launcher itself (perry.js, with fake platform packages and a stubbed process.report) covers the paths CI doesn't: notice-once + suppression, the --force instruction when the musl package is absent (exit 1, no loader error), and the #116 rescue.

What the fallback costs the user

• perry/ui (GTK4) desktop apps. The musl package doesn't ship libperry_ui_gtk4.a (GTK4 is glibc-only), and the musl target hard-errors on perry/ui by design. Everything else — server, CLI, native compile, stdlib — is the same compiler.
• One manual step on npm. npm won't install a package tagged libc: ["musl"] on a glibc machine, so the launcher can't silently pull it in. It now prints npm install --force @perryts/perry-linux-x64-musl@<version> instead of a loader error. If you'd rather it be zero-touch, dropping the libc field from the two musl package.json.tmpls makes npm install the static build alongside the glibc one on every Linux host — that costs every Linux user ~67 MB of unpacked package they may not need, which is why I didn't do it unilaterally. Say the word and it's a two-line change.
• No perf cliff in compiled output: the runtime archive bundles mimalloc, so musl's slower malloc isn't in the hot path of the programs you build.

Separate blocker found on 22.04 (not a libc issue)

Once the binary loads, jammy's default clang is 14, which rejects Perry's opaque-pointer IR:

/tmp/perry_llvm_...ll:28:36: error: expected type

Perry's LLVM backend emits ptr and shells out to clang -c, so Linux needs clang ≥ 15. perry doctor reports clang as OK without ever checking its version, so this surfaces as a mysterious codegen error. Documented here (apt install clang-15 + PERRY_LLVM_CLANG); the doctor gate is filed separately.

Is a native glibc-2.35 build leg worth adding? Not in this PR — and it wouldn't remove the launcher logic

I looked at it properly; it is not a clean matrix addition:

1. Moving the glibc legs back to ubuntu-22.04 is blocked by perry-ui-gtk4. Jammy has neither libwebkitgtk-6.0-dev (WebView, perry/ui WebView component: cross-platform native WebView for auth / payments / embedded pages #658) nor libshumate-dev (MapView, Provide a widget for showing a map #517) — that is precisely why v0.5.860 moved the runners 22.04 → 24.04. Going back means feature-gating both widgets out of the Linux desktop build, and it still leaves RHEL 9 / AL2023 (2.34) broken.
2. Adding a third Linux glibc leg + npm package doesn't fix distribution: npm has no glibc-version selector, so the new package could only ever be selected by the launcher — i.e. by the exact logic in this PR — and would still need --force or an unconditional ~110 MB optional dep. It doubles the slowest part of the release matrix (dist-profile LTO Linux builds) and buys nothing over the musl fallback.
3. An old-sysroot / manylinux-style container (glibc 2.28, would cover RHEL 9 and AL2023 too) is the best end state — and the compiler side is genuinely feasible, since Perry has no system-LLVM build dependency (it shells to clang at runtime rather than linking llvm-sys). The blocker is perry-ui-gtk4 again.

So the proper fix is a perry-ui-gtk4 feature-gating project plus a release-matrix change, not a packaging tweak — filed as a follow-up. Whatever we do there, a launcher that understands glibc versions is still required, because npm's selector cannot express one.

Still open (not fixable from the launcher)

The apt .deb is built from the perry-linux-x86_64 glibc artifact, so apt install perry stays broken below glibc 2.39 — a deb can't fall back at runtime. It should either declare Depends: libc6 (>= 2.39) so it fails cleanly at install time, or ship the static binary. Folded into the follow-up issue.

Notes

• No Rust code touched — nothing to rebuild.
• conformance-smoke shards are known-flaky and unrelated to anything here.

Summary by CodeRabbit

• New Features
  • Linux installation and the npm launcher now detect whether you’re on glibc or musl and select the appropriate prebuilt artifact.
  • Systems with glibc older than 2.39 automatically fall back to the fully-static musl build.
  • Enhanced launcher selection with clearer errors and a one-time fallback notice (can be disabled with PERRY_NO_FALLBACK_NOTICE=1).
• Documentation
  • Updated Linux prerequisites to require clang ≥ 15.
  • Added clear glibc ≥ 2.39 requirements and musl fallback guidance/limitations.
• Tests
  • Added platform-detection self-tests covering glibc/musl routing and version threshold edge cases.
• Chores
  • Added release CI coverage to verify correct platform resolution and musl/glibc behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0ae70dac-7385-4aac-98b0-22300fcfa2c6

📥 Commits

Reviewing files that changed from the base of the PR and between a3fea0a and be074a4.

📒 Files selected for processing (8)

• .github/workflows/npm-launcher.yml
• README.md
• docs/src/getting-started/installation.md
• npm/perry/README.md
• npm/perry/bin/detect.cjs
• npm/perry/bin/perry.js
• npm/perry/test/detect.test.cjs
• packaging/install.sh

🚧 Files skipped from review as they are similar to previous changes (7)

• packaging/install.sh
• npm/perry/bin/detect.cjs
• README.md
• docs/src/getting-started/installation.md
• npm/perry/README.md
• npm/perry/bin/perry.js
• npm/perry/test/detect.test.cjs

---

📝 Walkthrough

Walkthrough

Adds Linux glibc-floor detection and musl fallback routing for the npm launcher and shell installer, updates installation and CI documentation, and introduces workflow coverage for platform detection, package resolution, launcher execution, and fallback compilation.

Changes

Linux libc fallback

Layer / File(s)	Summary
Platform detection contract and tests npm/perry/bin/detect.cjs, npm/perry/test/detect.test.cjs	Defines platform mappings, glibc comparison and host classification, then verifies routing, package manifests, musl targets, and release builder versions.
NPM launcher fallback routing npm/perry/bin/perry.js	Resolves ordered platform candidates, reports missing binaries with accumulated errors, and persists a one-time glibc fallback notice.
Shell installer libc selection packaging/install.sh	Detects musl or glibc below 2.39, selects the matching archive, and includes the selected libc in status output.
Release validation and installation guidance .github/workflows/npm-launcher.yml, README.md, docs/src/getting-started/installation.md, npm/perry/README.md	Adds end-to-end launcher and compilation checks, updates glibc build-floor documentation, and documents clang requirements and musl limitations.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Launcher as perry.js
  participant Detect as detect.cjs
  participant Package as Platform package
  participant Binary as Perry binary
  User->>Launcher: invoke perry
  Launcher->>Detect: inspect host and detectPlatform
  Detect-->>Launcher: ordered glibc or musl candidates
  Launcher->>Package: resolve candidate binary
  Package-->>Launcher: binary path
  Launcher->>Binary: execute selected binary

Loading

Possibly related issues

• PerryTS/perry#6351: The PR implements the distribution-layer glibc fallback and launcher/install routing described by the issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: routing older-glibc Linux hosts to the static build for npm.
Description check	✅ Passed	The description covers summary, changes, related issue, verification, and checklist intent, even if not in the exact template headings.
Linked Issues check	✅ Passed	The PR resolves #6298 by making Ubuntu 22.04 and other older-glibc Linux hosts run Perry via the static fallback.
Out of Scope Changes check	✅ Passed	The added workflow, tests, docs, and launcher/install updates all support the glibc-fallback objective; no unrelated changes stand out.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/6298-glibc-235-fallback

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

.github/workflows/npm-launcher.yml (1)

29-31: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Exercise installer routing rather than only its syntax.

sh -n cannot catch incorrect glibc parsing or artifact suffix selection, and the Ubuntu end-to-end job never invokes install.sh. Add a dry-run or mocked-command harness covering musl, glibc below/at the floor, and both architectures.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/npm-launcher.yml around lines 29 - 31, Extend the
workflow’s installer validation after the existing syntax check to execute
packaging/install.sh through a dry-run or mocked-command harness. Cover musl,
glibc below and at the supported floor, and both relevant architectures,
asserting the detected libc and selected artifact suffix; ensure the Ubuntu
end-to-end job actually invokes this harness.

npm/perry/test/detect.test.cjs (1)

190-220: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Also enforce the installer’s glibc floor.

This test guards the release matrix against GLIBC_BUILD_FLOOR, but packaging/install.sh duplicates the floor as two independent constants. Assert that those values compose to GLIBC_BUILD_FLOOR so npm and shell installations cannot silently diverge.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@npm/perry/test/detect.test.cjs` around lines 190 - 220, Extend the existing
glibc floor test around the release-matrix assertions to read
packaging/install.sh and verify its two glibc floor constants compose to
GLIBC_BUILD_FLOOR. Parse or otherwise identify both installer constants, assert
their combined value equals GLIBC_BUILD_FLOOR, and retain the current matrix
validation unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/npm-launcher.yml:
- Around line 10-16: Harden both jobs in the npm-launcher workflow by setting
read-only workflow permissions and configuring each actions/checkout step with
credential persistence disabled. Update the workflow-level permissions and both
checkout invocations, preserving the existing triggers and job behavior.

In `@npm/perry/bin/perry.js`:
- Around line 127-155: Update the recovery messages in the glibc-too-old branch
and the generic fallback around the launcher’s console.error calls to
distinguish local and global installations: retain the existing local npm
command, add the corresponding npm install -g --force command for globally
installed Perry, and clearly label both paths.

---

Nitpick comments:
In @.github/workflows/npm-launcher.yml:
- Around line 29-31: Extend the workflow’s installer validation after the
existing syntax check to execute packaging/install.sh through a dry-run or
mocked-command harness. Cover musl, glibc below and at the supported floor, and
both relevant architectures, asserting the detected libc and selected artifact
suffix; ensure the Ubuntu end-to-end job actually invokes this harness.

In `@npm/perry/test/detect.test.cjs`:
- Around line 190-220: Extend the existing glibc floor test around the
release-matrix assertions to read packaging/install.sh and verify its two glibc
floor constants compose to GLIBC_BUILD_FLOOR. Parse or otherwise identify both
installer constants, assert their combined value equals GLIBC_BUILD_FLOOR, and
retain the current matrix validation unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 44a6ec7f-7f32-46b0-a99a-79b7741d4992

📥 Commits

Reviewing files that changed from the base of the PR and between cb750dd and e83bba7.

📒 Files selected for processing (8)

• .github/workflows/npm-launcher.yml
• README.md
• docs/src/getting-started/installation.md
• npm/perry/README.md
• npm/perry/bin/detect.cjs
• npm/perry/bin/perry.js
• npm/perry/test/detect.test.cjs
• packaging/install.sh