ScanSlicer/docs/appimage.md

AppImage Build Guide

ScanSlicer includes a full AppImage packaging workflow under packaging/appimage/.

Files

• packaging/appimage/AppImageBuilder.yml: AppDir recipe and AppImage config
• packaging/appimage/build-appimage.sh: local build script
• packaging/appimage/build-appimage-docker.sh: containerized build wrapper
• packaging/appimage/Dockerfile: AppImage build environment
• desktop entry file in packaging/appimage/
• application icon file in packaging/appimage/

Local Build

Prerequisites:

• uv
• appimage-builder (or custom binary via APPIMAGE_BUILDER_BIN)

Command:

bash packaging/appimage/build-appimage.sh

What the script does:

1. Exports runtime requirements from uv.lock to appimage/build/requirements.txt
2. Builds wheel into appimage/build/
3. Appends wheel path to requirements list
4. Sets:

• SCANSLICER_ROOT
• SCANSLICER_APPDIR
• SCANSLICER_REQUIREMENTS

5. Runs appimage-builder with AppImageBuilder.yml
6. Moves .AppImage and .zsync artifacts to appimage/dist/

Dockerized Build

Prerequisite:

• Docker

Command:

bash packaging/appimage/build-appimage-docker.sh

What it does:

1. Builds an image from packaging/appimage/Dockerfile
2. Runs the local AppImage build script inside the container
3. Applies host UID/GID ownership to generated appimage/ outputs

Optional environment variables:

• APPIMAGE_DOCKER_IMAGE (default: scanslicer-appimage-builder)
• HOST_UID and HOST_GID

Recipe Notes

AppImageBuilder.yml currently:

• Uses Ubuntu Noble apt sources
• Bundles Python and runtime shared libs
• Removes bundled Qt system libs to prefer PySide wheel Qt runtime
• Installs Python dependencies and project wheel into AppDir /usr
• Injects desktop entry and icon assets during after_bundle

Runtime environment variables set in AppDir include:

• PYTHONHOME
• PYTHONNOUSERSITE
• QT_PLUGIN_PATH
• LD_LIBRARY_PATH
• PATH

Output

Expected output artifact location:

• appimage/dist/ScanSlicer-<version>-x86_64.AppImage

Intermediate build files are kept under appimage/build/.