Skip to content

Bundle the X11 window libraries in the AppImage - #155

Merged
nilres merged 1 commit into
masterfrom
claude/appimage-compatibility-7a1827
Nov 11, 2026
Merged

nilres merged 1 commit into
masterfrom
claude/appimage-compatibility-7a1827

Conversation

@nilres

@nilres nilres commented Nov 11, 2026

Copy link
Copy Markdown
Owner

Why

The AppImage catalog test of OpenECraft-0.1.1-x86_64.AppImage (AppImage/appimage.github.io#11522) fails on Ubuntu 22.04: the editor panics at start with

thread 'main' panicked at …/xkbcommon-dl-0.4.2/src/x11.rs:59:28:
Library libxkbcommon-x11.so could not be loaded.

winit loads its window libraries with dlopen at run time, and the AppImage carried no libraries at all, so it relied on libxkbcommon-x11-0 (and libXcursor, libXi) being installed.

What changed

  • installer/linux/build.sh, new bundle_libs step of build_appimage:
    • copies libxkbcommon, libxkbcommon-x11, libxcb-xkb, libXcursor, libXi and their dependencies (libXrender, libXfixes, libXext) to usr/lib; libraries of the AppImage excludelist (libX11, libxcb, libwayland-client, libGL, libEGL) and the Wayland libraries tied to libwayland-client stay with the host
    • sets RUNPATH $ORIGIN/../lib on the editor and parts manager (and $ORIGIN on the libraries) with patchelf, so no LD_LIBRARY_PATH leaks into processes the app starts (plugins, …)
    • copies the Debian copyright files of the bundled packages to usr/share/doc/<package>/ (MIT/X11 licences)
    • fails the build when a program or bundled library needs a library that is neither bundled nor on every system, or when the bundled libraries need a newer glibc than the programs
    • ships the AppStream file as ….appdata.xml in the AppImage, the name the catalog's lint looks for (it passes appstreamcli validate-tree)
  • .github/workflows/ci.yml: installs patchelf, libxkbcommon-x11-0, libxcursor1, libxi6 in the Debian 12 container
  • docs/installation.md, CHANGELOG.md

Testing

  • Ran build.sh appimage in WSL (Ubuntu 26.04) on the binaries of the v0.1.1 release (OPENECRAFT_BIN_DIR): the AppImage started on X11 (WSLg) and kept running; LD_DEBUG=libs shows all bundled libraries loaded from the AppImage's usr/lib
  • The glibc check refuses the Ubuntu 26.04 libraries (GLIBC_2.38 > GLIBC_2.35 of the programs); the Debian 12 packages CI bundles need at most GLIBC_2.33
  • Not run: the CI build on Debian 12 itself (this PR's CI); cargo test (no Rust changes)

Notes for review

🤖 Generated with Claude Code

The AppImage catalog test (Ubuntu 22.04) quit at start with "Library
libxkbcommon-x11.so could not be loaded": winit loads its window
libraries at run time and the AppImage carried none.

- build.sh: copy libxkbcommon, libxkbcommon-x11, libxcb-xkb, libXcursor,
  libXi and their dependencies to usr/lib, point the editor and the
  parts manager there with patchelf, ship the packages' copyright files
- build.sh: refuse a library that is neither bundled nor on every
  system, and bundled libraries needing a newer glibc than the programs
- build.sh: ship the AppStream data as appdata.xml in the AppImage
- ci.yml: install patchelf and the libraries in the Debian 12 container
- installation.md, CHANGELOG.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nilres
nilres merged commit fa98247 into master Nov 11, 2026
@nilres
nilres deleted the claude/appimage-compatibility-7a1827 branch November 12, 2026 07:49
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