mesa-repo/README.md

# mesa-repo

Dieses Repo baut per Gitea Actions ein eigenständiges `mesa-git`-Paket als `.deb`.
Das Paket installiert Mesa separat unter `/opt/mesa-git`, damit es parallel zur
System-Mesa genutzt werden kann.

Ziel ist ein Paket, das auf `Debian 13+` sowie `Ubuntu 24.04` bis `26.x`
installierbar bleibt.

## Was gebaut wird

- Paketname: `mesa-git`
- Installationspfad: `/opt/mesa-git`
- Wrapper: `/usr/bin/mesa-git-env`
- Ausgabe: `mesa-git_<version>_amd64.deb`
- Versionsschema: `<mesa-version>+r<mesa-commit-count>.<mesa-sha>-<debian-revision>`

## Build-Profil

Standardmäßig baut das Repo Mesa für:

- `x11`
- `wayland`

Und mit diesem Treiberprofil:

- AMD: `radeonsi`, `r300`, `r600`
- Intel: `iris`, `crocus`
- NVIDIA nouveau: `nouveau`
- Fallback: `zink`, `llvmpipe`, `softpipe`
- Vulkan: `amd`, `intel`, `intel_hasvk`, `nouveau`, `swrast`

Das Profil ist damit besser für Steam, Proton und Xwayland geeignet als ein
hartes Wayland-only-Build.

Zusammen mit einem aktuellen `libdrm`-Snapshot, damit neue Mesa-Stände nicht an
zu alten Distributionspaketen scheitern.

Gebaut wird absichtlich gegen `Ubuntu 24.04` als älteste unterstützte
Ubuntu-Basis. Zusätzlich bündelt das Paket ausgewählte Laufzeitbibliotheken
unterhalb von `/opt/mesa-git`, damit neuere Mesa-Builds auch auf leicht
abweichenden Debian-/Ubuntu-Systemständen starten können.

## Ablauf

1. Gitea Actions startet auf dem `act_runner`.
2. `scripts/build-mesa-opt.sh` klont `libdrm` und Mesa direkt von Upstream.
3. `libdrm` wird zuerst gebaut und in das spätere Prefix vorbereitet.
4. Mesa wird danach mit Meson/Ninja gebaut.
5. Das Ergebnis wird als `.deb` paketiert.
6. Ein Gitea Release wird erstellt oder aktualisiert.
7. Das `.deb` wird als Release-Asset hochgeladen.
8. Die Release-Notes werden automatisch aus der Mesa-Upstream-History erzeugt.
9. Ein apt-kompatibler Repo-Baum wird auf den Branch `apt` veröffentlicht.

## Release-Notes

Die Release-Notes werden automatisch erzeugt und enthalten:

- eigene Repo-Commits für dieses Release
- den verwendeten Mesa-Upstream-Commit
- das gebaute Paket
- die Mesa-Commits seit dem vorherigen `mesa-git`-Release

Die beiden Bereiche werden getrennt dargestellt:

- `Repo Changes`
- `Mesa Upstream`

Wenn kein vorheriger passender Release-Vergleich gefunden wird, nutzt der Workflow
als Fallback die jüngsten Upstream-Commits.

## Trigger

Der Workflow läuft bei:

- manuellem Start per `workflow_dispatch`
- automatischem Zeitplan alle 3 Tage

Releases werden als normale Releases angelegt, nicht als Pre-Releases.

## APT-Einbindung

Der Workflow veröffentlicht zusätzlich einen einfachen Debian-Repo-Baum auf
dem Branch `apt`.

Wichtig: APT braucht anonym erreichbare HTTP-Dateien wie `dists/stable/Release`
und `pool/...deb`. Ein funktionierendes `git ls-remote` reicht dafür nicht aus.

Auf dieser Gitea-Instanz war die bisher dokumentierte Raw-URL für anonyme
HTTP-Clients nicht erreichbar und lieferte `404`. Genau daran scheitert dann
`apt update` auf Ubuntu, obwohl der `apt`-Branch in Git existiert.

Deshalb gilt:

- nutze für Clients nur eine wirklich öffentlich erreichbare statische HTTP-URL
- setze diese Basis-URL in `config/mesa-opt.conf` als `APT_PUBLIC_BASE_URL`
- der Workflow prüft dann nach dem Publish, ob `Release`, `Packages` und das
  referenzierte `.deb` anonym abrufbar sind

Beispiel für die Konfiguration:

```bash
APT_SUITE="stable"
APT_COMPONENT="main"
APT_PUBLIC_BASE_URL="https://packages.example.tld/mesa-repo"
```

Die Einbindung auf dem Client sieht dann so aus:

```text
deb [trusted=yes] https://packages.example.tld/mesa-repo stable main
```

Danach:

```bash
sudo apt update
sudo apt install mesa-git
```

Hinweis:

- das Repo ist aktuell unsigniert
- für APT wird deshalb hier `trusted=yes` verwendet
- `scripts/verify-apt-repo.sh --remote` prüft, ob die öffentliche URL wirklich
  APT-tauglich ist
- wenn du willst, kann ich als nächsten Schritt auch noch Release-Signierung mit GPG einbauen

## Wichtige Dateien

- `config/mesa-opt.conf`: Paketname, Prefix, Plattformen und Treiberprofil
- `scripts/build-mesa-opt.sh`: Build und Paketierung
- `scripts/generate-release-notes.sh`: automatische Release-Notes aus Mesa-Commits
- `scripts/generate-apt-repo.sh`: erzeugt den APT-Repo-Baum
- `scripts/verify-apt-repo.sh`: prüft Repo-Struktur und optional den öffentlichen APT-Endpunkt
- `.gitea/workflows/build.yml`: Gitea-Workflow

## Benutzung

Nach der Installation kann das Paket über den Wrapper genutzt werden:

```bash
mesa-git-env glxinfo
mesa-git-env vkcube
```

Der Wrapper setzt die nötigen Mesa-Pfade für `LD_LIBRARY_PATH`,
`LIBGL_DRIVERS_PATH`, `VK_LAYER_PATH` und `VK_ICD_FILENAMES`.
Vorhandene Vulkan-ICDs aus dem Paket werden dabei automatisch eingesammelt.

Wichtig: Prüfungen für die isolierte Installation sollten ebenfalls über
`mesa-git-env` laufen. Ein rohes `ldd` direkt auf Bibliotheken unter
`/opt/mesa-git` kann sonst fälschlich fehlende Abhängigkeiten zeigen, obwohl
der Wrapper die Laufzeitpfade korrekt setzt.

## Lokaler Test

Mit installierten Build-Abhängigkeiten:

```bash
./scripts/build-mesa-opt.sh
```

Für einen sauberen Kompatibilitätstest lohnt sich ein isolierter Container oder
eine `distrobox` mit eigenem temporären `HOME`, damit Build-Artefakte,
Paketquellen und Caches danach vollständig wieder entfernt werden können.

## Anpassen

Die wichtigsten Schalter liegen in `config/mesa-opt.conf`:

- `UPSTREAM_GIT_REF`
- `INSTALL_PREFIX`
- `PLATFORMS`
- `GALLIUM_DRIVERS`
- `VULKAN_DRIVERS`
- `VULKAN_LAYERS`