GRMrGecko/midi-harbor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
midi-harbor/specs/017-appimage/spec.md
James Coleman d11a525008 feat(release): publish an AppImage for each Linux architecture 
- Releases now include Midi-Harbor-<version>-<x86_64|aarch64>.AppImage, built from the same binary as the packages and listed in checksums.txt, for distributions without a .deb or .rpm. Opened with no arguments it shows the window, and the daemon it registers runs under the systemd user unit like a package install.
- service install run from an AppImage registers the .AppImage file instead of the executable inside the runtime's temporary mount, which is gone once the process exits. The file is used only when the running executable is inside APPDIR, so a program started from another AppImage, whose APPIMAGE it inherits, still registers itself.
- The AppImage carries only the Avahi client libraries from the Debian 12 sysroot, with their LGPL-2.1 license, found through the binary's RUNPATH rather than LD_LIBRARY_PATH; glibc 2.35 or newer, ALSA, D-Bus and libxkbcommon come from the host, as for the packages.
- Its AppRun starts the binary as midi-harbor, so on X11 the window's class matches the desktop entry instead of the AppImage's file name.
- Building it needs the cross image's new patchelf, file, appimagetool 1.9.1 and type2 runtime 20251108, pinned by checksum, and a sysroot rebuilt to carry Avahi's license; the script stops and names make build-sysroot when that license is missing.
2026-09-29 14:35:51 -05:00

3.9 KiB
Raw Blame History

Feature Specification: AppImage

Created: 2026-09-29

Status: Implemented; built for x86_64 and arm64 and checked on 2026-09-29 on Arch Linux and Ubuntu 22.04

Input: User request: "I'd like to see what it'll take to make an app image of this project. I don't know if its something that'll allow a daemon process, so please research and see.", then "If you think its feasible, do it."

The .deb and .rpm packages cover Debian, Ubuntu, Fedora and RHEL. Every other distribution had only the .tar.gz of the bare binary, with no desktop entry and no libraries. A release now carries an AppImage for each Linux architecture as well, which runs the graphical interface and the daemon it registers with systemd.

User Scenarios & Testing (mandatory)

User Story 1 - Running Midi Harbor from an AppImage (Priority: P1)

A user on a distribution without a package downloads the AppImage, makes it executable and opens it. The window offers to start the daemon at login, and from then on the daemon starts at every login and after every crash, as it does when installed from a package.

Why this priority: it is the whole request.

Independent Test: On a Linux machine with a systemd user session, run service install --start from the AppImage, then check the unit, the running daemon, a restart after the daemon is killed, and an advertised network port.

Acceptance Scenarios:

  1. Given the AppImage, When service install runs from it, Then the unit starts the AppImage file, not the executable inside its mount.
  2. Given the service installed from the AppImage, When the daemon is killed, Then systemd starts it again from the AppImage.
  3. Given the daemon running from the AppImage, When the service is stopped or the user logs out, Then the daemon shuts down as it does from a package, releasing its notes, and leaves no mount behind.
  4. Given a distribution without the Avahi client libraries, When a network port is created, Then it is advertised, the AppImage carrying the libraries.
  5. Given a newer AppImage moved over the registered one, When the daemon next starts, Then it runs the newer one.
  6. Given a newer AppImage saved under another name and the old one deleted, When service status runs, Then it reports the registration stale, and service install from the new file repairs it.

User Story 2 - Building the AppImages (Priority: P1)

make snapshot and make release build an AppImage for x86_64 and arm64 beside the other artifacts, and the release publishes them.

Independent Test: Run the build and check both AppImages exist and start.

Requirements (mandatory)

Functional Requirements

  • FR-I01: service install run from an AppImage MUST register the AppImage file, and run from anything else MUST register the running executable, whatever AppImage variables it inherited.
  • FR-I04: Stopping the service MUST let the daemon finish its shutdown before anything else in the unit is stopped.
  • FR-I02: The release MUST build an AppImage for each Linux architecture it builds, from the same binary as the packages.
  • FR-I03: The AppImage MUST run on the distributions the packages do, needing from the host only glibc, FUSE and what a desktop already has.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-I01: From a downloaded AppImage, the daemon runs at login after one setup step, the same step as from a package.

Assumptions

  • The AppImage is for desktops. A server takes the headless archive or package, so there is no headless AppImage.
  • Updates are by hand. AppImageUpdate's update information and .zsync file can be added later without changing the daemon.
  • AppImage's portable mode, a .home or .config directory beside the file, is not supported: it moves where the unit is written, where systemd does not look.