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
bash packaging/appimage/build-appimage.sh
```

What the script does:

1. Exports runtime requirements (with hashes) from `uv.lock` to `appimage/build/requirements.txt`
2. Builds wheel into `appimage/build/`
3. Sets:
  - `SCANSLICER_ROOT`
  - `SCANSLICER_APPDIR`
  - `SCANSLICER_REQUIREMENTS`
  - `SCANSLICER_WHEEL`
4. Runs `appimage-builder` with `AppImageBuilder.yml`
5. 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
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 (hash-verified) 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.