# Docker Aseprite Flatpak Builder

This repository provides a Docker-based environment to compile Aseprite into a portable Flatpak bundle. It uses `flatpak-builder` inside a containerized environment for consistency and leverages a robust host-side script to prepare sources reliably.

## Requirements

* Docker (BuildKit backend enabled, which is default in modern versions)
* Make
* Git
* Curl
* Host kernel with `fuse` module loaded (common on most desktop Linux systems).
* Sufficient disk space and RAM for source code and compilation.
* **CPU with AVX support:** The compiled binary requires a CPU supporting the AVX instruction set (generally CPUs from 2011/Sandy Bridge/Bulldozer onwards).

> [!IMPORTANT]
> The Docker build process requires elevated privileges (`--privileged`) to allow `flatpak-builder`'s sandboxing (bubblewrap) to function correctly. The `Makefile` handles adding this flag automatically. Ensure your environment allows privileged Docker builds.

## Quick Start

1. **Clone:**

    ```bash
    git clone <repository-url>
    cd docker-aseprite-linux
    ```

2. **Build:**

    ```bash
    make build
    ```

3. **Run:** Find the compiled Flatpak bundle in `./output/aseprite.flatpak`. You can install it using:

    ```bash
    flatpak install ./output/aseprite.flatpak
    ```

## Build Process Explained

The `make build` command performs the following steps:

1. **Prepare Sources (via `./prepare_sources.sh`):**
    * This script runs on your **host machine** first to reliably acquire and prepare the source code.
    * Clones `depot_tools`, Skia, and Aseprite source code into the `./src` directory if they don't exist. See the script for specific versions.
    * Runs Skia's `git-sync-deps` command locally with **automatic retries** (default: 3 attempts, configurable via `PREPARE_RETRIES`) to download Skia's internal build dependencies (like the `gn` tool) and mitigate failures from network issues or rate limiting.
    * Includes an **`--check-integrity`** flag for advanced validation and resetting of source repositories (see Advanced Usage).
    * This step isolates the often failure-prone network operations and source state management before the main build begins.
2. **Build Docker Image (using `Dockerfile`):**
    * Builds a single Docker image (`aseprite-flatpak-builder`) based on Debian Slim.
    * Installs `flatpak`, `flatpak-builder`, and the required Freedesktop Platform/SDK (e.g., 23.08).
    * **Copies** the prepared sources from `./src` on the host into `/sources` inside the container. This leverages Docker's layer caching for the source code.
    * Copies the Flatpak manifest `com.aseprite.Aseprite.yaml`.
    * Runs `flatpak-builder` inside the container using the manifest and the copied sources. This compiles Skia and Aseprite within the consistent Flatpak SDK environment.
    * Bundles the result into an `aseprite.flatpak` file inside the container.
    * **Note:** This step runs with `--privileged` to allow `flatpak-builder`'s sandboxing mechanisms to work.
3. **Extract Flatpak Bundle:** Copies the final `aseprite.flatpak` file from the container's `/output` directory to `./output` on your host machine.

## Troubleshooting

### Build Failures

* **Resource Exhaustion:** Compiling Skia and Aseprite requires significant RAM and disk space. Ensure your system (and Docker) has adequate resources allocated.
* **Network Issues / Rate Limiting (during `prepare_sources.sh`):**
  * Ensure you have a stable internet connection. Check for proxy issues if applicable.
  * The Skia sync step (`git-sync-deps`) might hit rate limits (HTTP 429 errors) from Google's servers. The script automatically retries (default: 3 total attempts). If it consistently fails, wait a while before trying again, or increase the number of retries via the `PREPARE_RETRIES` environment variable (e.g., `PREPARE_RETRIES=5 make build`).
* **`flatpak-builder` Errors (during Docker build):**
  * **Manifest Errors:** Check `com.aseprite.Aseprite.yaml` for syntax errors or incorrect paths/commands.
  * **SDK Issues:** Ensure the SDK version specified in the manifest and Dockerfile is available and installs correctly.
  * **Sandbox/Bubblewrap Errors (e.g., FUSE issues):**
    * Verify the `docker build` command is running with `--privileged` (handled by the Makefile).
    * Ensure the `fuse` kernel module is loaded on your **host system** (`lsmod | grep fuse`). If not, try `sudo modprobe fuse`.
    * Check Docker/BuildKit logs for specific bubblewrap (`bwrap`) errors.
  * **Compilation Errors:** Check the detailed build log output from Docker (during the `flatpak-builder` step) for C++/CMake/Ninja errors. These could indicate issues with the source code versions, compiler compatibility, or missing dependencies within the Flatpak SDK.

### Runtime Errors (After Installing `.flatpak`)

* **`Illegal instruction`**: This typically means the compiled binary is trying to use CPU instructions not supported by your processor. This build requires a CPU with **AVX** support.
* **Missing Portals / File Dialog Issues:** Ensure you have the necessary Flatpak portals installed on your host system (e.g., `xdg-desktop-portal`, `xdg-desktop-portal-gtk` or `-kde`, etc.) for features like file choosers to work correctly.
* **Permission Issues:** If Aseprite cannot save files or access expected locations, review the `finish-args` in `com.aseprite.Aseprite.yaml`. The current `--filesystem=home` is broad; more restrictive permissions might require specific portal interactions.

## Advanced Usage

The `make build` command automatically runs `./prepare_sources.sh` without any special flags. If you need to control the source preparation step (e.g., force a check integrity and reset), you can run the script manually *before* running `make build`.

### Running `prepare_sources.sh` Manually

* **Check Source Integrity & Reset:** Runs `git fsck`, fetches updates, checks out the exact target commit/tag, and resets submodules. **Warning:** This performs potentially network-intensive operations and modifies local source directories to match the expected state.

    ```bash
    ./prepare_sources.sh --check-integrity
    # If successful, proceed with make build
    make build
    ```

* **Set Sync Retries:** Control the number of retries for the Skia `git-sync-deps` step (default is 2 retries, total 3 attempts).

    ```bash
    PREPARE_RETRIES=5 ./prepare_sources.sh
    make build
    ```

### Passing Options via `make`

* **Set Sync Retries via `make`:**

    ```bash
    PREPARE_RETRIES=5 make build
    ```

* **Force Source Reset via `make`:** The recommended way to ensure sources are reset and prepared fresh is to run `make clean` followed by `make build`.

    ```bash
    make clean && make build # Clean output, then build (includes fresh source prep)
    ```

### Clean Up

To remove the build output (`./output`):

```bash
make clean
```
Note: This does *not* remove the downloaded sources in `./src`. To remove those as well, manually delete the `./src` directory or run `rm -rf ./src`.

## Architecture Notes

This project uses a hybrid approach combining a robust host-side source preparation script with a containerized Flatpak build process:

1. **Host-Side Source Prep (`prepare_sources.sh`):** Handles the potentially fragile steps of cloning, syncing dependencies (with retries), and ensuring the correct state of source code repositories locally in `./src`.
2. **Docker Build (`Dockerfile`):**
    * Creates a consistent build environment using Debian and the standard Flatpak SDK.
    * Copies the locally prepared sources into the container, leveraging Docker's layer caching.
    * Runs `flatpak-builder` using `com.aseprite.Aseprite.yaml` to compile Aseprite against the SDK libraries and the copied sources. Requires `--privileged` for sandboxing.
3. **Flatpak Manifest (`com.aseprite.Aseprite.yaml`):** Defines the application metadata, permissions, and the sequence of build steps (depot\_tools setup, Skia compile, Aseprite compile, metadata installation) executed by `flatpak-builder`.
4. **Makefile:** Orchestrates the process: `prepare_sources.sh` -> `docker build --privileged` -> extract `.flatpak`.

This architecture aims for:
* **Reliability:** By handling source fetching/syncing with retries outside the main build.
* **Consistency:** By using the standard Flatpak SDK inside Docker.
* **Portability:** By producing a `.flatpak` bundle that should run across different Linux distributions.
* **Maintainability:** By consolidating the build logic into a single Dockerfile and Flatpak manifest.

## License

[MIT License](LICENSE)