Skip to content

fix(installer): drop the libfuse2 dependency from the AppImage#13

Merged
LordVicky merged 1 commit into
devfrom
fix/appimage-static-fuse3-runtime
Jul 12, 2026
Merged

fix(installer): drop the libfuse2 dependency from the AppImage#13
LordVicky merged 1 commit into
devfrom
fix/appimage-static-fuse3-runtime

Conversation

@LordVicky

Copy link
Copy Markdown
Owner

Problem

The AppImage fails to launch on distros that ship only fuse3 (Arch/CachyOS among them) until the user manually installs a fuse2 compat package.

Root cause: electron-builder defaults toolsets.appimage to "0.0.0", which selects its legacy AppImage runtime — the branch is literally named buildFuse2AppImage in AppImageTarget.js. That 2019 runtime dlopens libfuse.so.2 at startup.

Fix

"toolsets": { "appimage": "1.0.2" }

Toolset 1.0.2 is AppImage type2-runtime 20251108, which statically links libfuse3 and talks to /dev/fuse directly — so it needs no FUSE library on the host at all. This isn't vendoring anything new; electron-builder already ships this runtime, we were just opted out by default.

Before → after

old new
runtime 2019, 188,392 B 20251108, 944,632 B
NEEDED deps libdl, libpthread, libz, libc none (static)
libfuse.so.2 refs 6 0

Verification

  • Built AppImage --appimage-offset944632 (was 188392), confirming the new runtime is embedded.
  • readelf -d on the runtime → no NEEDED entries; zero libfuse.so.2 strings.
  • Mounted it with --appimage-mount: mounts cleanly, and resources/vds-bin/{vdsd,vdsctl,udev rules,wireplumber conf} are all present at the expected paths — installer staging logic unaffected.
  • npm run test:installer passes.
  • Blockmap is regenerated in-build, so auto-update stays correct.

Notes

  • Upstream marks toolset 1.0.2 as beta (configuration.d.ts). The runtime itself is the mature AppImage type2-runtime; flagging it for visibility.
  • Existing AppImage auto-update users get a near-full download on their next delta (runtime change + resquashed payload). Bandwidth, not correctness.
  • No launcher-script APPIMAGE_EXTRACT_AND_RUN fallback is needed — the runtime is self-contained now.

🤖 Generated with Claude Code

electron-builder defaults `toolsets.appimage` to "0.0.0", which selects
its legacy AppImage runtime (see buildFuse2AppImage in AppImageTarget).
That 2019 runtime dlopens libfuse.so.2 at startup, so the AppImage fails
to launch on distros that ship only fuse3 -- Arch/CachyOS among them --
until the user manually installs a fuse2 compat package.

Selecting toolset 1.0.2 uses AppImage type2-runtime 20251108, which
statically links libfuse3 and talks to /dev/fuse directly, so it needs
no FUSE library on the host at all.

Runtime goes from 188KB (NEEDED: libdl, libpthread, libz, libc) to 944KB
with zero NEEDED entries and no libfuse.so.2 references. Verified by
mounting the built AppImage: it mounts and the staged resources/vds-bin
payload is intact.

Note: upstream marks toolset 1.0.2 as beta.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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