De PHP-micro bouwen op uw eigen runners (de workflow `standalone`)

bin/jumphp export:standalone en app:export plakken een game of app op een micro: een statisch gebouwde PHP (StaticPHP) met de extensies die JumPHP nodig heeft. De micro's worden gebouwd door de workflow .github/workflows/standalone.yml en gepubliceerd als de release standalone-<sleutel> (de sleutel is een vingerafdruk van de PHP-versie, de lijst met extensies, de commit van StaticPHP en het register en de patches van JumPHP: tools/standalone-key.sh). Een micro wordt dus alleen opnieuw gebouwd als een van deze elementen verandert. Deze pagina legt uit hoe u deze workflow op uw eigen runners start (ci-runner.md om ze te installeren), en wat de machines van GitHub gratis gaven en uw machines misschien niet hebben.

Starten

Forge > de repository > Actions > standalone > Run workflow, of vanuit een terminal (gh is die van de forge in een JumPHP-project):

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

Invoer	Waarden
`extensions`	`tools/standalone-extensions.txt` (games: SDL, OpenGL, OpenAL), `tools/app-extensions.txt` (desktopapps, de IDE), `tools/hybrid-extensions.txt`	de gebouwde micro = zijn eigen sleutel
`linux`	`true` / `false`	`false`: geen Linux-micro (zie « Docker » hieronder); `export:standalone` bouwt dan die van Linux op de computer van de gebruiker
`macos`	`true` / `false`	`false`: geen Mac-micro (alleen desktopapps); zonder macOS-runner zouden de jobs eindeloos wachten

De Windows-job duurt ongeveer 10 minuten met gecachete downloads, 30 tot 60 de allereerste keer. Het resultaat: https://<forge>/<eigenaar>/<repository>/releases/download/standalone-<sleutel>/micro-windows-x86_64.sfx.

Wat de machines van GitHub hadden en de uwe misschien niet

Op GitHub « werkte » dezelfde workflow « vanzelf » omdat windows-latest en ubuntu-latest door GitHub voorbereide images zijn. Een eigen runner is een kale machine. Alles hieronder wordt door de workflow afgehandeld, of staat hier vermeld:

De image van GitHub	Een eigen runner	Wat de workflow doet / wat u doet
PowerShell 7 (`pwsh`), PHP, Composer, Git	vaak alleen Windows PowerShell 5.1 en Git	de stappen draaien in Windows PowerShell; PHP 8.4 en Composer worden gedownload (php.net, getcomposer.org, vingerafdruk gecontroleerd) als ze ontbreken; de `usr\bin` van Git komt in het PATH
Windows in het Engels	de taal van uw Windows (Frans...)	`VSLANG=1033` laat de hulpmiddelen van Visual Studio Engels praten: de `configure.js` van PHP leest de uitvoer van de linker en stopt anders met een JScript-fout
Visual Studio 2022	door uzelf te installeren: Build Tools 2022, workload « Desktopontwikkeling met C++ »	het enige wat een Windows-runner moet hebben (samen met Git voor Windows). install-windows-runner.ps1 installeert beide
Snelle toegang tot `api.github.com`, zelden beperkt	dezelfde API antwoordt `504` of « rate limit exceeded »	de downloads van StaticPHP worden 4 keer opnieuw geprobeerd en tussen twee runs bewaard in `%USERPROFILE%\.spc-downloads`; Composer installeert vanuit de bronnen (`--prefer-source`)
`actions/upload-artifact@v4`, `download-artifact@v4`	Forgejo ondersteunt ze niet (« not currently supported on GHES »)	op een forge publiceert de Windows-job zelf de micro in de release (het `github.token` van de job, de API van de forge); de job `release` draait alleen op GitHub
Docker in de Linux-job	de job draait in een container zonder Docker	zie hieronder
LF-regeleinden	Git voor Windows converteert naar CRLF	`git config --global core.autocrlf false` vóór het klonen van StaticPHP (een patch van zijn bestanden steunt op hun tekst)

Docker: waar het nodig is, waar niet

De Windows-job compileert native met Visual Studio. Hij gebruikt geen Docker en een Windows-runner zou dat ook niet kunnen (Linux- containers onder Windows lopen via WSL2). Hiervoor hoeft niets geïnstalleerd te worden.
De Linux-job start docker build docker/standalone en daarna docker run van StaticPHP. In een jobcontainer is er geen Docker, tenzij de runner er een geeft: mount de Docker-socket van de host (of van de dind van de runner) in de job (container.options / valid_volumes in de config.yml van de runner), of gebruik de WSL2-Linux-runner (ci-runner.md sectie 4), een echte Linux met Docker. Zonder dat start u met linux=false: bin/jumphp export:standalone <id> --linux bouwt de Linux-micro op de computer die exporteert (ongeveer 15 minuten, daarna bewaard in ~/.jumphp/standalone/).
Welke runner ook, kopieer of hernoem nooit een micro naar een andere sleutel: het zou een PHP zonder de juiste extensies zijn en de uitvoerbare bestanden van uw gebruikers zouden crashen (Call to undefined function SDL_Init()). Als de sleutel is veranderd, moet de micro opnieuw worden gebouwd.

Probleemoplossing

De logs van de jobs leest u op de pagina van de run in de forge (job > de rode stap); de API van de forge geeft ze niet terug.

Symptoom	Oorzaak / oplossing
De job `key` mislukt in 30 s, vlak na « Fetching the repository »	de jobcontainer kan de naam van de forge niet omzetten: de Docker-in-Docker van de runner heeft geen DNS naar buiten. Geef hem er een: `dns: [1.1.1.1, 9.9.9.9]` op de service `dind` van het compose-bestand van de runner. Test: `docker run --network <een nieuw netwerk> node:20-bookworm getent hosts <forge>`
`Cannot find: pwsh in PATH`	de workflow vraagt Windows PowerShell (`shell: powershell`); een oude kopie vroeg `pwsh`. Werk haar bij
`configure.js ... Erreur d'exécution Microsoft JScript` na « Checking for link.exe »	de hulpmiddelen van Visual Studio schrijven in de taal van Windows. `VSLANG=1033` (in de workflow sinds deze pagina)
`ERROR: bison is required`	gezien na een half voltooide build in dezelfde map: StaticPHP bewaart de msys2-hulpmiddelen maar zet ze niet terug in het PATH. Verwijder `spc/pkgroot`, `spc/source`, `spc/buildroot` uit de werkruimte en start opnieuw (een schone werkruimte, zoals die van een nieuwe job, werkt)
Een patch van StaticPHP « not patched (StaticPHP changed) » of « Failed patch module »	CRLF-regeleinden (`core.autocrlf false` en opnieuw klonen), of een bronmap die al door een eerdere poging is gepatcht (verwijder `spc/source/php-src`)
`Failed to get GitHub release API info for madler/zlib` / `HTTP/2 504`	`api.github.com` beperkt of faalt voor uw adres. De workflow probeert opnieuw; de eerste run op een nieuwe machine kan een tweede poging nodig hebben. De downloads worden bewaard: elke poging komt verder
`GHESNotSupportedError: upload-artifact@v4 ... not currently supported`	u gebruikt Forgejo: neem de workflow van deze repository (publiceert zonder artefacten)
De macOS-jobs blijven « waiting » en de run eindigt nooit	geen macOS-runner: `-f macos=false`
`Cannot find path ...\buildroot\bin\micro.sfx`	de build is eerder mislukt: lees de regels erboven (die zijn de oorzaak)

Voor AI-agenten

Men kan u vragen om « de standalone-workflow op mijn runner te laten werken ». Lees de mislukte stap op de pagina van de run (vraag de gebruiker hem te plakken als u er niet bij kunt), pas de workflow aan (hij moet geldig blijven op GitHub: test github.server_url), niet de machine van de gebruiker, tenzij wat ontbreekt een voorwaarde hierboven is (Git, Visual Studio Build Tools, Docker voor de Linux-job): zeg dat dan tegen de gebruiker en installeer het alleen als hij ja zegt. Registreer nooit een runner, schrijf nooit een token in een bestand, publiceer nooit een micro die u niet hebt gebouwd uit de huidige bestanden met de commando's van deze workflow, verplaats nooit een release naar een andere sleutel. Controleer na een geslaagde run het bestand (gh release view standalone-<sleutel>, een download die 200 antwoordt) en voer voor een Windows-micro een script ermee uit op de machine van de runner (copy /b micro.sfx + test.php test.exe, daarna test.exe: PHP-versie, extension_loaded('ffi')...).