Den PHP-Micro auf eigenen Runnern bauen (der Workflow `standalone`)

bin/jumphp export:standalone und app:export kleben ein Spiel oder eine Anwendung an einen Micro: statisch gebautes PHP (StaticPHP) mit den Erweiterungen, die JumPHP braucht. Die Micros baut der Workflow .github/workflows/standalone.yml; sie werden als Release standalone-<Schlüssel> veröffentlicht (der Schlüssel ist ein Hash aus der PHP-Version, der Erweiterungsliste, dem Commit von StaticPHP sowie der Registry und den Patches von JumPHP: tools/standalone-key.sh). Ein Micro wird also nur dann neu gebaut, wenn sich eines davon ändert. Diese Seite zeigt, wie man diesen Workflow auf eigenen Runnern ausführt (siehe ci-runner.md zur Installation) und was die Maschinen von GitHub kostenlos mitbrachten, was Ihre vielleicht nicht haben.

Ausführen

Forge > das Repository > Actions > standalone > Run workflow, oder in einem Terminal (gh ist in einem JumPHP-Projekt das der Forge):

gh workflow run standalone.yml -f extensions=tools/app-extensions.txt -f macos=false -f linux=false

Eingabe	Werte
`extensions`	`tools/standalone-extensions.txt` (Spiele: SDL, OpenGL, OpenAL), `tools/app-extensions.txt` (Desktop-Anwendungen, die IDE), `tools/hybrid-extensions.txt`	der gebaute Micro = sein eigener Schlüssel
`linux`	`true` / `false`	`false`: kein Linux-Micro (siehe „Docker“ unten); `export:standalone` baut dann den Linux-Micro auf dem Rechner des Benutzers
`macos`	`true` / `false`	`false`: kein Mac-Micro (nur Desktop-Anwendungen); ohne macOS-Runner würden die Jobs ewig warten

Der Windows-Job braucht etwa 10 Minuten mit zwischengespeicherten Downloads, beim allerersten Mal 30-60. Sein Ergebnis: https://<Forge>/<Besitzer>/<Repo>/releases/download/standalone-<Schlüssel>/micro-windows-x86_64.sfx.

Was die Maschinen von GitHub hatten und Ihre vielleicht nicht

Auf GitHub „lief“ derselbe Workflow einfach, weil windows-latest und ubuntu-latest von GitHub vorbereitete Images sind. Ein eigener Runner ist eine nackte Maschine. Alles Folgende erledigt der Workflow oder wird hier erklärt:

Image von GitHub	Ein eigener Runner	Was der Workflow / Sie tun
PowerShell 7 (`pwsh`), PHP, Composer, Git	oft nur Windows PowerShell 5.1 und Git	die Schritte laufen in Windows PowerShell; PHP 8.4 und Composer werden heruntergeladen (php.net, getcomposer.org, Hash geprüft), wenn sie fehlen; das `usr\bin` von Git kommt in den PATH
Windows auf Englisch	die Sprache Ihres Windows (Französisch, ...)	`VSLANG=1033` lässt die Visual-Studio-Werkzeuge Englisch sprechen: das `configure.js` von PHP liest die Ausgabe des Linkers und bricht sonst mit einem JScript-Fehler ab
Visual Studio 2022	Sie installieren es: Build Tools 2022, Workload „Desktopentwicklung mit C++“	das Einzige, was ein Windows-Runner haben muss (neben Git for Windows). install-windows-runner.ps1 installiert beides
Schneller, selten ratenbegrenzter Zugriff auf `api.github.com`	dieselbe API antwortet `504` oder „rate limit exceeded“	Downloads von StaticPHP werden 4-mal wiederholt und zwischen den Läufen in `%USERPROFILE%\.spc-downloads` aufbewahrt; Composer installiert aus den Quellen (`--prefer-source`)
`actions/upload-artifact@v4`, `download-artifact@v4`	Forgejo unterstützt sie nicht („not currently supported on GHES“)	auf einer Forge veröffentlicht der Windows-Job den Micro selbst im Release (das `github.token` des Jobs, die API der Forge); der Job `release` läuft nur auf GitHub
Docker im Linux-Job	der Job läuft in einem Container ohne Docker	siehe unten
LF-Zeilenenden	Git for Windows konvertiert zu CRLF	`git config --global core.autocrlf false` vor dem Klonen von StaticPHP (ein Patch seiner Dateien passt auf deren Text)

Docker: wo er nötig ist, wo nicht

Der Windows-Job baut nativ mit Visual Studio. Er benutzt kein Docker, und ein Windows-Runner kann ihn nicht für Sie ausführen (Linux-Container unter Windows brauchen WSL2). Dafür ist nichts zu installieren.
Der Linux-Job führt docker build docker/standalone und dann docker run von StaticPHP aus. In einem Job-Container gibt es kein Docker, es sei denn, der Runner stellt eines bereit: den Docker-Socket des Hosts (oder des dind des Runners) in den Job einbinden (container.options / valid_volumes in der config.yml des Runners), oder den WSL2-Linux-Runner verwenden (ci-runner.md Abschnitt 4), der ein echtes Linux mit Docker ist. Ohne das mit linux=false ausführen: bin/jumphp export:standalone <id> --linux baut den Linux-Micro auf dem exportierenden Rechner (etwa 15 Minuten, danach in ~/.jumphp/standalone/ aufbewahrt).
Gleich welcher Runner: Kopieren oder benennen Sie nie einen Micro unter einem anderen Schlüssel um: Es wäre ein PHP ohne die richtigen Erweiterungen, und die ausführbaren Dateien Ihrer Benutzer würden abstürzen (Call to undefined function SDL_Init()). Hat sich der Schlüssel geändert, muss der Micro neu gebaut werden.

Fehlerbehebung

Die Job-Logs liest man auf der Seite des Laufs in der Forge (Job > der rote Schritt); die API der Forge liefert sie nicht.

Symptom	Ursache / Lösung
Der Job `key` scheitert nach 30 s, direkt nach „Fetching the repository“	der Container des Jobs kann die Forge nicht auflösen: das Docker-in-Docker des Runners hat kein externes DNS. Geben Sie ihm eines: `dns: [1.1.1.1, 9.9.9.9]` beim Dienst `dind` in der Compose-Datei des Runners. Test: `docker run --network <ein neues Netzwerk> node:20-bookworm getent hosts <Forge>`
`Cannot find: pwsh in PATH`	der Workflow verlangt Windows PowerShell (`shell: powershell`); eine alte Kopie des Workflows verlangte `pwsh`. Aktualisieren
`configure.js ... Microsoft JScript runtime error` nach „Checking for link.exe“	die Werkzeuge von Visual Studio geben in der Sprache von Windows aus. `VSLANG=1033` (seit dieser Seite im Workflow)
`ERROR: bison is required`	tritt nach einem halb fertigen früheren Build im selben Ordner auf: StaticPHP behält die msys2-Werkzeuge, setzt sie aber nicht erneut in den PATH. `spc/pkgroot`, `spc/source`, `spc/buildroot` des Arbeitsbereichs löschen und erneut ausführen (ein sauberer Arbeitsbereich, wie ihn ein neuer Job hat, funktioniert)
Ein Patch von StaticPHP „not patched (StaticPHP changed)“ oder „Failed patch module“	CRLF-Zeilenenden (`core.autocrlf false` und neu klonen), oder ein von einem früheren Versuch gepatchter Quellordner (`spc/source/php-src` löschen)
`Failed to get GitHub release API info for madler/zlib` / `HTTP/2 504`	`api.github.com` drosselt oder fällt für Ihre Adresse aus. Der Workflow wiederholt; der erste Lauf auf einer neuen Maschine braucht eventuell einen zweiten Versuch. Downloads bleiben erhalten, jeder neue Versuch kommt also weiter
`GHESNotSupportedError: upload-artifact@v4 ... not currently supported`	Sie nutzen Forgejo: verwenden Sie den Workflow dieses Repositorys (er veröffentlicht ohne Artifacts)
Die macOS-Jobs bleiben „waiting“ und der Lauf endet nie	kein macOS-Runner: `-f macos=false`
`Cannot find path ...\buildroot\bin\micro.sfx`	der Build ist vorher gescheitert: lesen Sie die Zeilen darüber (sie sind die Ursache)

Für KI-Agenten

Man kann Sie bitten, „den Workflow standalone auf meinem Runner zum Laufen zu bringen“. Lesen Sie den fehlschlagenden Schritt auf der Seite des Laufs (bitten Sie den Benutzer, ihn einzufügen, wenn Sie ihn nicht erreichen), ändern Sie den Workflow (er muss auch auf GitHub gültig bleiben: github.server_url testen), nicht die Maschine des Benutzers, es sei denn, es fehlt eine der obigen Voraussetzungen (Git, Visual Studio Build Tools, Docker für den Linux-Job): dann sagen Sie es dem Benutzer und installieren es nur, wenn er zustimmt. Registrieren Sie nie einen Runner, schreiben Sie nie ein Token in eine Datei, veröffentlichen Sie nie einen Micro, den Sie nicht aus den aktuellen Dateien mit den eigenen Befehlen dieses Workflows gebaut haben, verschieben Sie nie ein Release unter einen anderen Schlüssel. Prüfen Sie nach einem erfolgreichen Lauf das Asset (gh release view standalone-<Schlüssel>, ein Download mit Antwort 200) und führen Sie bei einem Windows-Micro damit ein Skript auf der Maschine des Runners aus (copy /b micro.sfx + test.php test.exe, dann test.exe: PHP-Version, extension_loaded('ffi')...).