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