appimage/README.md

What is AppImage?

AppImage is a universal Linux package format that allows you to distribute applications as a single executable file that works on most Linux distributions without installation.

Features

• Package any .NET MAUI Linux app as an AppImage
• Auto-detection of executable and icon from your project
• Automatic .desktop file generation with proper StartupWMClass for taskbar integration
• Built-in installer dialog on first run
• Install/Reinstall/Uninstall support
• No root access required

Prerequisites

1. .NET 9 SDK or later
2. appimagetool - Download from AppImageKit releases

Installing appimagetool

# Download
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage

# Make executable
chmod +x appimagetool-x86_64.AppImage

# Move to PATH
sudo mv appimagetool-x86_64.AppImage /usr/local/bin/appimagetool

Installation

As a .NET tool (recommended)

dotnet tool install --global OpenMaui.AppImage

From source

git clone https://github.com/AuroraNetworks/openmaui-appimage.git
cd openmaui-appimage
dotnet build

Usage

1. Publish your MAUI app

cd YourMauiApp
dotnet publish -c Release -r linux-x64 --self-contained

2. Create the AppImage

openmaui-appimage \
    --input bin/Release/net9.0/linux-x64/publish \
    --output YourApp.AppImage \
    --name "Your App"

That's it! The tool automatically detects:

• Executable: Finds the main executable (ELF binary or .runtimeconfig.json)
• Icon: Reads MauiIcon from your .csproj and composites background + foreground

Options

Option	Short	Required	Description
--input	-i	Yes	Path to published .NET app directory
--output	-o	Yes	Output AppImage file path
--name	-n	Yes	Application name
--executable	-e	No	Main executable name (auto-detected if not specified)
--icon		No	Path to icon (auto-detected from MauiIcon if not specified)
--category	-c	No	Desktop category (default: Utility)
--app-version		No	App version (default: 1.0.0)
--comment		No	App description

Desktop Categories

Common categories: Utility, Development, Game, Graphics, Network, Office, AudioVideo, System

Running the AppImage

First Run - Installer Dialog

When you run an AppImage for the first time, a dialog appears:

• Install: Copies to ~/.local/bin, creates menu entry and icon
• Run Only: Runs the app without installing

Already Installed

If you run the AppImage again from a different location (e.g., Desktop), you'll see options:

• Run the application: Just runs it
• Reinstall (update): Updates the installed version
• Uninstall: Removes the app from your system

From the Launcher

Once installed, clicking the app in your application menu runs it directly (no dialog).

Command Line Flags

# Run normally (shows dialog if not installed)
./YourApp.AppImage

# Force install dialog
./YourApp.AppImage --install

# Uninstall
./YourApp.AppImage --uninstall

# Show help
./YourApp.AppImage --help

Example: Packaging ShellDemo

# Build and publish
cd maui-linux-samples/ShellDemo
dotnet publish -c Release -r linux-x64 --self-contained

# Create AppImage (icon auto-detected from MauiIcon in csproj)
openmaui-appimage \
    -i bin/Release/net9.0/linux-x64/publish \
    -o ShellDemo.AppImage \
    -n "Shell Demo"

How It Works

1. AppDir Structure: Creates the standard AppImage directory structure:

   YourApp.AppDir/
   ├── AppRun              # Entry point script
   ├── YourApp.desktop     # Desktop integration
   ├── YourApp.svg         # Application icon
   └── usr/
       ├── bin/            # Your published .NET app
       │   └── appicon.svg # Runtime icon for window
       └── share/icons/    # XDG icon directories
   

2. AppRun Script: A bash script that:

   • Sets up the environment (PATH, LD_LIBRARY_PATH)
   • Shows installer dialog on first run
   • Handles --install, --uninstall, and --help flags
   • Launches the .NET application

3. Desktop Integration:

   • Creates .desktop file with StartupWMClass for proper taskbar icon matching
   • Installs icon to XDG icon directories
   • Updates icon cache automatically

4. appimagetool: Packages everything into a single executable AppImage file

Self-Contained vs Framework-Dependent

Self-Contained (recommended for distribution)

dotnet publish -c Release -r linux-x64 --self-contained

• Works on any Linux system without .NET installed
• Larger AppImage size

Framework-Dependent (smaller size)

dotnet publish -c Release -r linux-x64 --self-contained false

• Smaller AppImage (~50-100MB smaller)
• Requires .NET runtime on target system

Troubleshooting

"appimagetool not found"

Install appimagetool as described in Prerequisites.

"Could not find executable"

The auto-detection looks for:

1. ELF binaries (self-contained apps)
2. .runtimeconfig.json files (framework-dependent apps)

If it fails, use --executable to specify the correct name (without extension).

AppImage won't run

1. Ensure it's executable: chmod +x YourApp.AppImage
2. Check for missing dependencies: ./YourApp.AppImage (errors will be shown)

Taskbar icon not showing

The app sets WM_CLASS and the .desktop file includes StartupWMClass for proper matching. If issues persist:

1. Reinstall the app to update the .desktop file
2. Log out and back in to refresh the desktop environment

FUSE errors

Some systems require FUSE to mount AppImages. Install with:

sudo apt install fuse libfuse2  # Debian/Ubuntu
sudo dnf install fuse fuse-libs  # Fedora

Or extract and run:

./YourApp.AppImage --appimage-extract
./squashfs-root/AppRun

License

MIT License - see LICENSE