Skip to content

fix(release): bundle sharun AppImage loader#2307

Merged
senamakel merged 1 commit into
tinyhumansai:mainfrom
aqilaziz:codex/2297-appimage-sharun-loader
May 20, 2026
Merged

fix(release): bundle sharun AppImage loader#2307
senamakel merged 1 commit into
tinyhumansai:mainfrom
aqilaziz:codex/2297-appimage-sharun-loader

Conversation

@aqilaziz
Copy link
Copy Markdown
Contributor

@aqilaziz aqilaziz commented May 20, 2026

Summary

  • Bundles the glibc dynamic linker that sharun needs inside the Linux AppImage when the post-build AppImage cleanup runs.
  • Repackages and re-signs AppImage artifacts when the only mutation is adding the missing loader, not just when graphics libraries were stripped.
  • Keeps the existing Mesa/libdrm/libva stripping behavior intact and adds a release smoke item for the Ubuntu 24.04 Interpreter not found! regression.

Problem

  • OpenHuman_0.54.0_amd64.AppImage can exit immediately on Ubuntu 24.04 with Interpreter not found! because the AppImage contains a sharun launcher but no lib/ld-linux-x86-64.so.2.
  • The existing post-processing script only repacked when graphics libraries were removed, so it had no guard for a missing sharun interpreter.

Solution

  • Detect sharun-style launchers by checking the extracted AppDir launcher binaries for the Interpreter not found! marker.
  • Resolve the expected loader from the build target architecture and copy it into squashfs-root/lib/ when missing.
  • Fail the post-processing step if the AppImage uses sharun but the build host cannot provide the required loader.
  • Track all modified AppImages, whether modified by stripping graphics libs or by adding the loader, so updater tarballs and signatures stay in sync.

Submission Checklist

  • Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy — release smoke checklist updated; local function smoke covers loader injection path.
  • Diff coverage >= 80% — N/A: shell release packaging script and docs are not covered by Vitest/cargo diff coverage.
  • Coverage matrix updated — N/A: release packaging behavior, not a product feature row.
  • All affected feature IDs from the matrix are listed in the PR description under ## Related — N/A: no feature matrix row.
  • No new external network dependencies introduced (mock backend used per Testing Strategy)
  • Manual smoke checklist updated if this touches release-cut surfaces (docs/RELEASE-MANUAL-SMOKE.md)
  • Linked issue closed via Closes #NNN in the ## Related section

Impact

  • Linux AppImage release artifacts should launch on clean Ubuntu 24.04 hosts without requiring users to extract the AppImage and manually copy ld-linux-x86-64.so.2.
  • Packaging fails earlier if a future build cannot locate the required loader, preventing a known-broken AppImage from shipping.

Related


AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

  • Key: N/A
  • URL: N/A

Commit & Branch

  • Branch: codex/2297-appimage-sharun-loader
  • Commit SHA: 4260df24f5355a63df02e748e276586ebed0c53a

Validation Run

  • pnpm --filter openhuman-app format:check — N/A: no frontend files changed.
  • pnpm typecheck — N/A: no TypeScript files changed.
  • Focused tests: Git Bash smoke test for ensure_sharun_interpreter copies ld-linux-x86-64.so.2 into a synthetic sharun AppDir.
  • Rust fmt/check (if changed): N/A: no Rust files changed.
  • Tauri fmt/check (if changed): N/A: no Tauri Rust files changed.
  • Shell syntax/check: C:\Program Files\Git\bin\bash.exe -n scripts/release/strip-appimage-graphics-libs.sh; git diff --check.

Validation Blocked

  • command: Full AppImage rebuild and launch on Ubuntu 24.04.
  • error: No produced Linux AppImage artifact is available in this local Windows workspace.
  • impact: CI release packaging will exercise the changed script; manual release smoke checklist now covers the Ubuntu 24.04 launch regression.

Behavior Changes

  • Intended behavior change: AppImage post-processing now bundles the missing sharun dynamic linker when needed.
  • User-visible effect: Linux users should no longer hit Interpreter not found! on affected AppImages.

Parity Contract

  • Legacy behavior preserved: existing graphics-library stripping, re-signing, and updater tarball rebuild behavior remain intact.
  • Guard/fallback/dispatch parity checks: AppImages unchanged by stripping or loader injection are still left untouched; missing host loader now fails packaging instead of shipping a broken artifact.

Duplicate / Superseded PR Handling

  • Duplicate PR(s): N/A
  • Canonical PR: this PR
  • Resolution (closed/superseded/updated): N/A

Summary by CodeRabbit

  • Bug Fixes

    • AppImages now remove incompatible host graphics libraries and auto-include a missing bundled dynamic loader when needed, preventing "Interpreter not found" failures on clean Ubuntu 24.04 hosts.
  • Chores

    • Added a smoke-test checklist item to validate AppImage launches on Ubuntu 24.04.
    • Release tooling now only repacks and re-signs AppImages that were actually modified.

Review Change Stack

@aqilaziz aqilaziz requested a review from a team May 20, 2026 08:06
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 20, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4dc9e2b6-91a7-47cb-b211-63d1c609813b

📥 Commits

Reviewing files that changed from the base of the PR and between 183e4e8 and 4e71ea9.

📒 Files selected for processing (2)
  • docs/RELEASE-MANUAL-SMOKE.md
  • scripts/release/strip-appimage-graphics-libs.sh
✅ Files skipped from review due to trivial changes (1)
  • docs/RELEASE-MANUAL-SMOKE.md

📝 Walkthrough

Walkthrough

Adds helpers to detect sharun-based AppImages and bundle a host dynamic loader into AppDir/lib when missing, integrates that into strip_one_appimage so repack occurs if loader was added or graphics libs removed, switches tracking to MODIFIED_PATHS for selective re-signing, and adds a smoke-test step for Ubuntu 24.04.

Changes

Sharun dynamic linker bundling and modification tracking

Layer / File(s) Summary
Sharun interpreter bundling helper functions
scripts/release/strip-appimage-graphics-libs.sh
New helper functions appimage_loader_name(), host_dynamic_loader(), is_executable_elf(), emit_entry_if_elf(), emit_desktop_exec_candidate(), discover_appimage_entry_binaries(), uses_sharun_launcher(), and ensure_sharun_interpreter() map architecture to loader names, locate host loaders, detect sharun launchers, and bundle the loader into the extracted AppImage.
Track loader addition
scripts/release/strip-appimage-graphics-libs.sh
Introduces an added_loader flag in strip_one_appimage to record when the sharun interpreter loader was bundled.
Integrate sharun loader bundling into strip_one_appimage
scripts/release/strip-appimage-graphics-libs.sh
Updated strip_one_appimage to only remove excluded graphics libraries when known lib roots exist, call ensure_sharun_interpreter, and require both removed == 0 and added_loader == 0 to skip repacking.
Record modified artifacts
scripts/release/strip-appimage-graphics-libs.sh
After rebuilding and replacing an AppImage, the script appends the artifact path to MODIFIED_PATHS.
Refactor modification tracking for re-signing
scripts/release/strip-appimage-graphics-libs.sh
Replaced STRIPPED_PATHS with MODIFIED_PATHS and updated initialization and the re-sign/re-tar loop to iterate over MODIFIED_PATHS.
Smoke test documentation for sharun dynamic linker
docs/RELEASE-MANUAL-SMOKE.md
Added Linux smoke-test checklist item to validate that .AppImage launches on Ubuntu 24.04 from a clean directory (no extracted sibling), confirming sharun locates the bundled dynamic linker rather than failing with 'Interpreter not found!'.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • tinyhumansai/openhuman#2052: Introduced strip_one_appimage and initial repack/signing logic that this change extends with sharun loader bundling and MODIFIED_PATHS tracking.

Suggested reviewers

  • graycyrus

Poem

🐰 I dug through lib and found a missing thread,
sharun stumbled when its loader fled.
A tiny copy from host brought cheer,
now AppImage wakes — the window's here.
thump 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% 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
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix(release): bundle sharun AppImage loader' directly describes the main change: bundling the missing dynamic linker for sharun-based AppImages to resolve the 'Interpreter not found!' error.
Linked Issues check ✅ Passed The PR successfully addresses all coding requirements from #2297: detects sharun launchers, injects the missing glibc dynamic linker into the AppImage lib/ directory, repacks and re-signs artifacts, and adds smoke-test documentation.
Out of Scope Changes check ✅ Passed All changes remain focused on the core objective: AppImage post-build cleanup now detects sharun launchers and bundles missing dynamic linkers, with supporting smoke-test documentation and helper functions.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


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

Comment @coderabbitai help to get the list of available commands and usage tips.

@aqilaziz aqilaziz force-pushed the codex/2297-appimage-sharun-loader branch from 4260df2 to b7a3e41 Compare May 20, 2026 08:28
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
scripts/release/strip-appimage-graphics-libs.sh (1)

147-150: ⚡ Quick win

Consider failing for unsupported architecture when sharun is detected.

Per PR objectives, packaging should fail if the build host cannot provide the required loader. Currently, unsupported architectures print a WARNING but continue, potentially shipping a broken AppImage that will still fail with "Interpreter not found!".

For consistency with the exit 1 on line 160 (missing host loader), consider also failing here:

Proposed change
   local loader_name
   if ! loader_name="$(appimage_loader_name)"; then
-    echo "[strip-libs] WARNING: unsupported AppImage architecture for sharun interpreter check" >&2
-    return 1
+    echo "[strip-libs] ERROR: AppImage uses sharun but architecture is unsupported; cannot determine required loader" >&2
+    exit 1
   fi
🤖 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 `@scripts/release/strip-appimage-graphics-libs.sh` around lines 147 - 150, The
current check that calls appimage_loader_name and sets loader_name returns 1 on
unsupported architecture, which only prints a warning and lets packaging
continue; change this to fail the packaging consistently by exiting with a
non-zero status (use exit 1) when loader_name cannot be determined and sharun
will be used. Update the conditional block that currently echoes the WARNING and
returns 1 so that it instead logs the same message and calls exit 1 (matching
the behavior used later for the missing host loader), ensuring the script stops
packaging a broken AppImage; refer to the appimage_loader_name call and the
loader_name variable in your change.
🤖 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.

Nitpick comments:
In `@scripts/release/strip-appimage-graphics-libs.sh`:
- Around line 147-150: The current check that calls appimage_loader_name and
sets loader_name returns 1 on unsupported architecture, which only prints a
warning and lets packaging continue; change this to fail the packaging
consistently by exiting with a non-zero status (use exit 1) when loader_name
cannot be determined and sharun will be used. Update the conditional block that
currently echoes the WARNING and returns 1 so that it instead logs the same
message and calls exit 1 (matching the behavior used later for the missing host
loader), ensuring the script stops packaging a broken AppImage; refer to the
appimage_loader_name call and the loader_name variable in your change.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fb454933-a334-442f-ba6d-80ffd61992e8

📥 Commits

Reviewing files that changed from the base of the PR and between 4260df2 and b7a3e41.

📒 Files selected for processing (2)
  • docs/RELEASE-MANUAL-SMOKE.md
  • scripts/release/strip-appimage-graphics-libs.sh
✅ Files skipped from review due to trivial changes (1)
  • docs/RELEASE-MANUAL-SMOKE.md

@aqilaziz aqilaziz force-pushed the codex/2297-appimage-sharun-loader branch from b7a3e41 to 1e5b736 Compare May 20, 2026 09:00
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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 `@scripts/release/strip-appimage-graphics-libs.sh`:
- Around line 80-92: The new aarch64 branch in appimage_loader_name introduces
arm64 detection but strip_one_appimage still assumes x86_64 paths/roots, which
can lead to partial mutations; either remove/undo the aarch64/arm64 case from
appimage_loader_name or update strip_one_appimage to handle arm64 fully: detect
architecture via appimage_loader_name or MATRIX/APPIMAGE_TARGET, set correct lib
roots and loader names (use ld-linux-aarch64.so.1), and ensure
rebuild/relocation logic and path substitutions use arm64-specific directories;
alternatively make appimage_loader_name return failure for non-x86 to fail fast
until strip_one_appimage gains full arm64 support.
- Around line 147-150: When appimage_loader_name fails to detect a loader (the
block using loader_name="$(appimage_loader_name)"), make this condition fatal
instead of returning 1 so a sharun AppImage doesn't proceed; replace the current
'return 1' with an immediate script failure (e.g. 'exit 1') and ensure the
existing warning message remains so that when uses_sharun_launcher has matched
the absence of a loader aborts the whole run rather than being treated as
"nothing to do".
🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b5687a01-cfa1-42ca-8ea7-da1a6b65c44d

📥 Commits

Reviewing files that changed from the base of the PR and between b7a3e41 and 1e5b736.

📒 Files selected for processing (2)
  • docs/RELEASE-MANUAL-SMOKE.md
  • scripts/release/strip-appimage-graphics-libs.sh
✅ Files skipped from review due to trivial changes (1)
  • docs/RELEASE-MANUAL-SMOKE.md

Comment thread scripts/release/strip-appimage-graphics-libs.sh
Comment thread scripts/release/strip-appimage-graphics-libs.sh
@aqilaziz aqilaziz force-pushed the codex/2297-appimage-sharun-loader branch 2 times, most recently from 407d353 to 183e4e8 Compare May 20, 2026 09:30
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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 `@scripts/release/strip-appimage-graphics-libs.sh`:
- Around line 96-100: The candidates array used in the ld-linux-x86-64.so.2)
case doesn't include /usr/lib, so add "/usr/lib/$loader_name" to the candidates
list (the variable candidates and the case label ld-linux-x86-64.so.2) so the
script will find the loader installed at /usr/lib on some distros; update the
candidates array ordering as needed to include that path.
- Around line 125-128: The loop that hard-codes "$appdir/sharun",
"$appdir/bin/OpenHuman", and "$appdir/usr/bin/OpenHuman" will miss differently
named entrypoints (AppRun or other binaries); update the logic in
strip-appimage-graphics-libs.sh so it dynamically discovers candidate entry
binaries instead of using those literal names — e.g. check AppRun if present,
parse the .desktop Exec or iterate over all files under "$appdir"/{,usr/}bin and
the top-level AppDir root for executable ELF files, filter non-ELF/text files,
and run the loader-injection code against each discovered candidate (replace the
hard-coded list in the for candidate in ... loop with this discovery). Ensure
you still preserve existing checks that the file is executable and an ELF binary
before attempting injection.
🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0db7898a-be8a-4d80-98ac-7caf2e12f6ab

📥 Commits

Reviewing files that changed from the base of the PR and between 1e5b736 and 183e4e8.

📒 Files selected for processing (2)
  • docs/RELEASE-MANUAL-SMOKE.md
  • scripts/release/strip-appimage-graphics-libs.sh

Comment thread scripts/release/strip-appimage-graphics-libs.sh
Comment thread scripts/release/strip-appimage-graphics-libs.sh Outdated
@aqilaziz aqilaziz force-pushed the codex/2297-appimage-sharun-loader branch from 183e4e8 to 4e71ea9 Compare May 20, 2026 09:56
@YOMXXX
Copy link
Copy Markdown
Contributor

YOMXXX commented May 20, 2026

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 20, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@YOMXXX
Copy link
Copy Markdown
Contributor

YOMXXX commented May 20, 2026

@senamakel #2307 当前 checks 22 success / 2 skipped / 0 pending / 0 failure,CodeRabbit 最新 review approved,review threads 0 unresolved。这个修 v0.54.0 AppImage Interpreter not found,麻烦再看一下。

@senamakel senamakel merged commit ff918f0 into tinyhumansai:main May 20, 2026
30 checks passed
@senamakel
Copy link
Copy Markdown
Member

huge thanks @aqilaziz for getting the sharun loader bundled into the appimage 🙌 super clean fix making sure the repack+resign kicks in when the loader is the only thing missing. really appreciate you keeping the mesa/libdrm stripping intact too, merged and shipped!

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.

AppImage 0.54.0 fails on Ubuntu 24.04 with "Interpreter not found!" — bundled ld-linux is missing from sharun lib/

3 participants