Skip to content

Build AM as a portable, self-contained AppImage (quick-sharun + uruntime) - #2698

Closed
fiftydinar wants to merge 15 commits into
ivan-hc:mainfrom
fiftydinar:feat/appimage
Closed

fiftydinar wants to merge 15 commits into
ivan-hc:mainfrom
fiftydinar:feat/appimage

Conversation

@fiftydinar

@fiftydinar fiftydinar commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

What

Adds an optional GitHub Actions workflow that builds a portable AppMan AppImage of AM using quick-sharun (sharun runtime + uruntime).

This follows the suggestions from #2695: "build the AppImage on a distribution (Arch Linux for example) using a better runtime (like sharun) and for all architectures".

How it works

  • The AppImage runs APP-MANAGER directly as a local/portable appman — no installation needed, no root required:
    ./AM-10.5-anylinux-x86_64.AppImage -h
    ./AM-10.5-anylinux-x86_64.AppImage -i firefox
    
  • AM's dependencies that are missing on some distros (curl, wget, 7z, tar, unzip, xz, file, checksums, ...) are bundled together with their libraries and glibc, so the AppImage is self-contained and works offline.
  • The static appimageupdatetool (pkgforge-dev/AppImageUpdate) is bundled too, so the AppImage updates itself in place from the GitHub releases, and appman -s from inside the AppImage triggers that update.
  • No FUSE required (uruntime), works on old and musl-based distros.
  • Beginner friendly: double-clicking the AppImage — when "am"/"appman" is not installed yet — opens a terminal with the embedded installer, so you can install this very AppImage as "am" system-wide or as "appman" locally; if already installed it opens a terminal with its help screen. AM-*.AppImage setup always runs that installer.
  • The workflow is triggered when a new version-tagged GitHub release is published (e.g. 10.5), and attaches the freshly built AM-*.AppImage + .zsync to that very release — so the AppImage always ships all the bugfixes of the corresponding version. (Also runs on PRs that touch APP-MANAGER or appimage/** for testing, without releasing.)

Architectures

Currently built: x86_64 and aarch64, each inside its own Arch Linux container image (pkgforge-dev/docker-archlinux) on native GitHub Actions runners.

The build infrastructure also supports riscv64, loongarch64 and ppc64le (their Arch Linux ports are emulated with QEMU on an x86_64 runner — the architecture-specific build tools appimagetool/sharun/mkdwarfs, themselves zig-cross-built upstream, must run on the target arch). These are currently disabled in the matrix, because AM's database does not ship installation scripts for those architectures yet (see the programs/ directory). They are commented out in .github/workflows/appimage.yml and can be re-enabled once app repos for those architectures are introduced.

powerpc64 (big-endian) is not supported: tonistiigi/binfmt does not register a qemu-ppc64 handler, so it cannot be emulated.

Changes

  • APP-MANAGER: detects the AppImage runtime (IS_APPIMAGE) and derives the CLI name from the AppImage file itself — installed as APP-MANAGER it acts as am, installed as appman it acts as appman. _sync_amcli updates the AppImage in place via the bundled appimageupdatetool, and devmode is disabled in AppImage mode. Both are no-ops for classic script installs ($APPIMAGE is empty).
  • INSTALL + AM-INSTALLER: when run from inside the AppImage they install the AppImage file itself as am (moved to /opt/am/APP-MANAGER + symlink) or as appman (moved to ~/.local/bin/appman), instead of downloading the plain script.
  • appimage/ (new): make-appimage.sh, get-dependencies.sh (self-contained container setup: pacman keyring, packages, quick-sharun), APP-MANAGER.desktop, and two runtime hooks (self-updater env + terminal/installer interface).
  • .github/workflows/appimage.yml (new): x86_64 + aarch64 build, attached to the triggering release, with the QEMU matrix entries ready to enable.
  • README.md: documents the build.

Module handling is deliberately left as in the script-based install (unlike #2695): the AppImage updates its modules in the writable apps dir exactly like a normal AppMan.

Notes / open questions

  • The release job attaches the AppImages to the release that triggered the workflow (the existing version-tagged releases like 10.5). If you'd rather use a different tag scheme, that's easy to adjust.
  • The added files are contributed under the repository's GPL-3.0 license.

Demo AppImage built and tested from this branch (x86_64): version output, -l listing, the appman -s AppImage-update path and the devmode guard all work.

Adds an optional GitHub Actions workflow that builds a portable AppMan
AppImage of AM using quick-sharun (sharun runtime + uruntime) on an Arch
Linux container, for x86_64 and aarch64:

- the AppImage runs APP-MANAGER directly as a local/portable 'appman'
  (no installation needed, no root required)
- AM's optional dependencies (curl, wget, 7z, tar, unzip, xz, file,
  checksums, ...) are bundled together with their libraries and glibc,
  making the AppImage self-contained and usable offline
- it does not require FUSE and is self-updating from the GitHub releases
- double-clicking opens a terminal; 'AM-*.AppImage setup' runs the
  embedded installer to install AM/AppMan

The only change to the CLI itself is a small guard in _sync_amcli that,
when running as an AppImage, updates the AppImage in place via
appimageupdatetool instead of failing to overwrite the read-only image.
Modules and the classic script-based installs are untouched.
@fiftydinar

Copy link
Copy Markdown
Contributor Author

Whoops, didn't mean to open, well, I'll update it here

The AppImage now bundles dynamic ELF binaries (curl, wget, 7z, tar, ...)
that dlopen libraries at runtime (NSS modules, gconv, p11-kit, codecs).
Using quick-sharun's default strace mode discovers and bundles those
dlopened libraries, instead of shipping only ldd-collected ones.
The development branch of AM includes the CLI itself, which cannot be
updated inside a read-only AppImage (appman -s updates the AppImage
instead of the script). Enabling devmode would therefore leave a
half-broken state (release CLI + dev branch modules/database), so it is
disabled when running as an AppImage, like in ivan-hc#2695.
Build each AppImage inside its Arch Linux container image, so the
architecture-specific build tools (appimagetool, sharun, mkdwarfs) run on
the target architecture:

- x86_64 and aarch64: native GitHub Actions runners
- riscv64, loongarch64, ppc64le, powerpc64: built in their Arch Linux
  port containers, emulated with QEMU on an x86_64 runner

The container setup is now self-contained in appimage/get-dependencies.sh
(pacman keyring + packages + quick-sharun), so the workflow just runs the
build inside the per-architecture container image.
The matrix context is not available in a job-level if condition, only in
step-level ones, so skip the QEMU builds on pull requests from the build
and upload steps instead.
The per-architecture Arch Linux image tags are OCI indexes without an
amd64 entry, so docker on the x86_64 runner needs --platform to select
the right manifest (e.g. linux/riscv64, linux/loong64, linux/ppc64le,
linux/ppc64).
quick-sharun still defaults to sharun 2.3.0, which does not ship builds
for riscv64/loongarch64/ppc64/ppc64le - those were added in sharun 3.0.0.
Override SHARUN_LINK for now; remove once quick-sharun bumps its default.
tonistiigi/binfmt (used by docker/setup-qemu-action) does not register a
qemu-ppc64 handler, so a big-endian powerpc64 container cannot be
emulated. ppc64le covers modern PowerPC hardware.
quick-sharun's strace mode warns when xvfb-run is missing (it provides a
virtual display). Our CLI tools do not need one, so it is only a warning,
but keeping the package makes the container match the setup-action.
AM's database does not ship installation scripts for riscv64, loongarch64
and ppc64le yet, so those architectures are disabled in the matrix
(commented out). The QEMU-based build infrastructure stays in place so
they can be re-enabled once app repos for those architectures are
introduced.
Instead of only scanning a hardcoded list of terminals, look up the
user's terminal in order: $TERMINAL, x-terminal-emulator (Debian
alternatives), xdg-terminal-exec (freedesktop draft spec), then the
desktop environment's configured default (gsettings / kreadconfig /
xfconf-query), then a broader fallback list. GNOME 48+ reports the spec
name 'xdg-terminal-exec' from gsettings, which is not a binary, so it is
skipped and detection continues (e.g. to ptyxis). Uses the right launch
flag per terminal (-e, --, -x).
ptyxis (and similar terminals) parse their own options greedily, so
'ptyxis -x appman -h' shows ptyxis' help and exits without running appman
- nothing happens on double-click. Pass the whole command to the terminal
wrapped in sh -c so flags like -h reach the bundled appman, and keep the
window open until ENTER so the output stays visible.
@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

I would prefer to leave this to AM-GUI or AppGallery. This have more sense than double-clicking n a command line utility.

@vishnu350

Copy link
Copy Markdown
Contributor

I would prefer to leave this to AM-GUI or AppGallery. This have more sense than double-clicking n a command line utility.

That's why double-clicking should just trigger the install script if AM is not installed. Showing the help screen is secondary, just to show the user some response if AM/Appman is already installed. Clicking on something and seeing no response is the worst.

Then users can return to browsing https://portable-linux-apps.github.io and the pla-install feature will do the rest. They will eventually find AM-GUI or AppGallery there to manage their apps.

- Release the AppImage on manual GitHub release push (the existing
  version-tagged releases like 10.5), attaching the built AppImages to
  that very release, instead of a scheduled 'stable' release.
- Double-click now offers to install this very AppImage as 'am' or
  'appman' (INSTALL/AM-INSTALLER install the AppImage file itself into
  PATH), and shows help when already installed.
- Bundle the static appimageupdatetool binary so the AppImage can update
  itself in place from the terminal (appman -s).
- drop the defensive unset of inherited AppImage env vars
- use ARCH instead of APPIMAGE_ARCH
- use APP_DIR instead of APPDIR (quick-sharun defaults to $PWD/AppDir)
- remove the temporary SHARUN_LINK override (quick-sharun default is fine)
@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

That's why double-clicking should just trigger the install script if AM is not installed

Again, its tricky. The user should be ready to use AM or AppMan, without selecting between them. This is the purpose of running AM-INSTALLER once.

You could solve this with a configuration file that automatically opens one or the other. Or a dialog with a checkbox that could run one or the other by default.

This, a GUI. And AM is not a GUI. GUI are others (AM-GUI, AppGallery... and whatever will come in future): AM is an engine.

$APPIMAGE/$APPDIR are exported by any AppImage runtime, so when this
script is run from inside another AppImage (e.g. an 'am-gui' AppImage)
the bare '$APPIMAGE' check falsely triggered the AppImage code paths.
Now IS_APPIMAGE additionally requires $0 to be the 'appman' bundled in
$APPDIR/bin - the exact path AppRun executes - so only the AM AppImage
itself matches.
@fiftydinar

Copy link
Copy Markdown
Contributor Author

The more I work on this, the more I find it non-sensical and incompatible tbh. Too complex for little gains imo.

@vishnu350

vishnu350 commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Again, its tricky. The user should be ready to use AM or AppMan, without selecting between them. This is the purpose of running AM-INSTALLER once.

That wont happen, since of course it will and should only run once.

AppImage double-click behavior (from desktop):

  • If AM/Appman not installed — Opens a terminal and triggers install scripts.
  • Else (installed) — Opens a terminal and brings up am -h

AppImage shell execution behavior (inside a terminal):

  • Behaves as am if in put in /opt/am, else defaults to behaving as appman.

Here is the AppRun entrypoint:

#!/bin/sh
HERE=$(dirname "$(readlink -f "$0")")
if [ -z "$1" ] && [ ! -t 1 ]; then
    if command -v am >/dev/null 2>&1 && [ -e /opt/am/APP-MANAGER ]; then
        AM_EXEC_CMD="am -h"
    elif command -v appman >/dev/null 2>&1; then
        AM_EXEC_CMD="appman -h"
    else
        AM_EXEC_CMD="$HERE/AM-INSTALLER"
    fi
    for TERM_CMD in x-terminal-emulator\ -e gnome-terminal\ -- konsole\ -e xfce4-terminal\ -e mate-terminal\ -e lxterminal\ -e terminator\ -e urxvt\ -e xterm\ -e; do
        if command -v "$(echo "$TERM_CMD" | cut -d' ' -f1)" >/dev/null 2>&1; then
            exec $TERM_CMD sh -c "$AM_EXEC_CMD; printf '\nPress CTRL+C to close this window...\n'; sleep 1h"
        fi
    done
else
    if [ "$1" = "setup" ] && ! command -v am >/dev/null 2>&1 && ! command -v appman >/dev/null 2>&1 && [ ! -e /opt/am/APP-MANAGER ]; then
        exec "$HERE/AM-INSTALLER"
    else
        exec "$HERE/APP-MANAGER" "$@"
    fi
fi

@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

@fiftydinar @vishnu350 a lot of AppImages are already done for CLI-only usage (appimageupdatetool, appimagetool...) and doing double click on them already have no sense.

For AM-utils I wanted to do the same: a complete suite of CLI AppImages... but I ended to distributed the hundreds of utilities as static binaries.

I understand the goal... but this is not the best practice in my opinion.

@vishnu350

Copy link
Copy Markdown
Contributor

The more I work on this, the more I find it non-sensical and incompatible tbh. Too complex for little gains imo.

Of course it is wont make sense to us. We are not the targeted end-users for this feature.

@fiftydinar @vishnu350 a lot of AppImages are already done for CLI-only usage (appimageupdatetool, appimagetool...) and doing double click on them already have no sense.

Those are standalone tools targeting devs/advanced users.

AM is not the same. It is a package manager tool that can be used by everyone, but beginners are staying away from installing it because a giant CLI-only install command:
wget -q https://raw.githubusercontent.com/ivan-hc/AM/main/AM-INSTALLER && chmod a+x ./AM-INSTALLER && ./AM-INSTALLER && rm ./AM-INSTALLER

Cmon. They wont do it.

Here is a rough statistic (AI prompted):

Non-developer command-line usage is extremely rare. A realistic rough estimate would be that less than 2% of the global computer-using population has ever used a command line intentionally. For the subset of people who regularly use it without being a developer, it's probably under 1%.

@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Here is a rough statistic (AI prompted):

Non-developer command-line usage is extremely rare. A realistic rough estimate would be that less than 2% of the global computer-using population has ever used a command line intentionally. For the subset of people who regularly use it without being a developer, it's probably under 1%.

Being a Linux user will lead you to interface with the command line sooner or later.

Many users already blindly follow guides online, copying and pasting commands without understanding their meaning. Fortunately, mine is just one line long (download the installer + made it executable + run + remove installer = 4 steps in 1).

@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Here is a rough statistic (AI prompted):

Non-developer command-line usage is extremely rare. A realistic rough estimate would be that less than 2% of the global computer-using population has ever used a command line intentionally. For the subset of people who regularly use it without being a developer, it's probably under 1%.

Being a Linux user will lead you to interface with the command line sooner or later.

Many users already blindly follow guides online, copying and pasting commands without understanding their meaning.

This is why many are against the use of AI.

@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Non-developer command-line usage is extremely rare

Arch Linux is still one of the most popular GNU/Linux distributions, according to the Steam hwsurvey

Istantanea_2026-09-08_15-00-47

@vishnu350

Copy link
Copy Markdown
Contributor

0.34% is well under the 2% estimate from the prompt. I don't trust its responses either, but that is just worse.

@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

0.34% is well under the 2% estimate from the prompt. I don't trust its responses either, but that is just worse.

Better than Distrowatch, of course.

@ivan-hc

ivan-hc commented Sep 8, 2026

Copy link
Copy Markdown
Owner

0.34% is well under the 2%

Maybe this would help more

Istantanea_2026-09-08_15-39-38

@ivan-hc

ivan-hc commented Sep 13, 2026 •

Copy link
Copy Markdown
Owner

@fiftydinar @vishnu350 You should come to an agreement and try to resolve this situation together.

Personally, I’m not interested in exporting AM as an AppImage, because—however you look at it—I think the disadvantages outweigh the advantages. But if you two join forces, you might just manage to change my mind.

For now, I am limiting myself to observing.

@fiftydinar

Copy link
Copy Markdown
Contributor Author

@fiftydinar @vishnu350 You should come to an agreement and try to resolve this situation together.

Personally, I’m not interested in exporting AM as an AppImage, because—however you look at it—I think the disadvantages outweigh the advantages. But if you two join forces, you might just manage to change my mind.

For now, I am limiting myself to observing.

@vishnu350 can continue his work in his PR and take inspiration from this PR.

I will close this PR, because quote:

The more I work on this, the more I find it non-sensical and incompatible tbh. Too complex for little gains imo.

@fiftydinar fiftydinar closed this Sep 13, 2026
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.

3 participants