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
• LICENSE: project GPLv3 license bundled with AppImage releases
• THIRD_PARTY_NOTICES: bundled dependency notice file for AppImage releases
• 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

The Docker build image pins a specific appimage-builder version so release builds use a stable packaging toolchain.

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
• Copies LICENSE and THIRD_PARTY_NOTICES into usr/share/doc/scanslicer/

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/.

Release Checklist

Before publishing an AppImage:

1. Build from a committed state that has a matching source tag or commit you will publish.
2. Verify uv.lock is committed so the bundled Python dependency set is reproducible from source.
3. Confirm the AppImage contains usr/share/doc/scanslicer/LICENSE and usr/share/doc/scanslicer/THIRD_PARTY_NOTICES.
4. Publish the AppImage together with the corresponding source code for that exact release.
5. Review THIRD_PARTY_NOTICES whenever dependency versions change, especially the PySide6 / Qt runtime stack.
6. If you change the pinned appimage-builder version, rerun a full AppImage smoke test before publishing.