Costruire il micro PHP sui propri runner (il workflow `standalone`)

bin/jumphp export:standalone e app:export incollano un gioco o un'app su un micro: un PHP costruito in modo statico (StaticPHP) con le estensioni di cui JumPHP ha bisogno. I micro sono costruiti dal workflow .github/workflows/standalone.yml e pubblicati come release standalone-<chiave> (la chiave è un'impronta della versione di PHP, dell'elenco delle estensioni, del commit di StaticPHP e del registro e delle patch di JumPHP: tools/standalone-key.sh). Un micro viene quindi ricostruito solo se uno di questi elementi cambia. Questa pagina spiega come lanciare questo workflow sui propri runner (ci-runner.md per installarli), e ciò che le macchine di GitHub davano gratuitamente e che le vostre forse non hanno.

Lanciarlo

Forge > il repository > Actions > standalone > Run workflow, oppure da un terminale (gh è quello della forge in un progetto JumPHP):

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

Input	Valori
`extensions`	`tools/standalone-extensions.txt` (giochi: SDL, OpenGL, OpenAL), `tools/app-extensions.txt` (app desktop, l'IDE), `tools/hybrid-extensions.txt`	il micro costruito = la sua chiave
`linux`	`true` / `false`	`false`: nessun micro Linux (vedere « Docker » più sotto); `export:standalone` costruisce allora quello Linux sul computer dell'utente
`macos`	`true` / `false`	`false`: nessun micro Mac (solo app desktop); senza un runner macOS, i job aspetterebbero all'infinito

Il job Windows richiede circa 10 minuti con i download in cache, da 30 a 60 la primissima volta. Il suo risultato: https://<forge>/<proprietario>/<repository>/releases/download/standalone-<chiave>/micro-windows-x86_64.sfx.

Ciò che le macchine di GitHub avevano e che le vostre forse non hanno

Su GitHub, lo stesso workflow « funzionava da solo » perché windows-latest e ubuntu-latest sono immagini preparate da GitHub. Un runner vostro è una macchina nuda. Tutto quanto segue è gestito dal workflow, oppure è detto qui:

L'immagine di GitHub	Un runner vostro	Cosa fa il workflow / cosa fate voi
PowerShell 7 (`pwsh`), PHP, Composer, Git	spesso solo Windows PowerShell 5.1 e Git	i passaggi girano in Windows PowerShell; PHP 8.4 e Composer vengono scaricati (php.net, getcomposer.org, impronta verificata) se mancano; il `usr\bin` di Git entra nel PATH
Windows in inglese	la lingua del vostro Windows (francese...)	`VSLANG=1033` fa parlare inglese gli strumenti di Visual Studio: il `configure.js` di PHP legge l'output del linker e altrimenti si ferma con un errore JScript
Visual Studio 2022	da installare voi: Build Tools 2022, carico di lavoro « Sviluppo di applicazioni desktop con C++ »	l'unica cosa che un runner Windows deve avere (insieme a Git per Windows). install-windows-runner.ps1 installa entrambi
Accesso rapido a `api.github.com`, raramente limitato	la stessa API risponde `504` o « rate limit exceeded »	i download di StaticPHP vengono ritentati 4 volte e conservati in `%USERPROFILE%\.spc-downloads` tra un'esecuzione e l'altra; Composer installa dai sorgenti (`--prefer-source`)
`actions/upload-artifact@v4`, `download-artifact@v4`	Forgejo non li supporta (« not currently supported on GHES »)	su una forge, il job Windows pubblica da solo il micro nella release (il `github.token` del job, l'API della forge); il job `release` gira solo su GitHub
Docker nel job Linux	il job gira in un container senza Docker	vedere sotto
Fine riga LF	Git per Windows converte in CRLF	`git config --global core.autocrlf false` prima di clonare StaticPHP (una patch ai suoi file si basa sul loro testo)

Docker: dove serve, dove non serve

Il job Windows compila in nativo con Visual Studio. Non usa Docker e un runner Windows non saprebbe farlo (i container Linux sotto Windows passano da WSL2). Niente da installare per questo.
Il job Linux lancia docker build docker/standalone poi docker run di StaticPHP. In un container di job non c'è Docker, a meno che il runner non ne fornisca uno: montate il socket Docker dell'host (o del dind del runner) nel job (container.options / valid_volumes nel config.yml del runner), oppure usate il runner Linux WSL2 (ci-runner.md sezione 4), un vero Linux con Docker. Senza questo, lanciate con linux=false: bin/jumphp export:standalone <id> --linux costruisce il micro Linux sul computer che esporta (circa 15 minuti, poi conservato in ~/.jumphp/standalone/).
Qualunque sia il runner, non copiate e non rinominate mai un micro sotto un'altra chiave: sarebbe un PHP senza le estensioni giuste e gli eseguibili dei vostri utenti andrebbero in crash (Call to undefined function SDL_Init()). Se la chiave è cambiata, il micro deve essere ricostruito.

Risoluzione dei problemi

I log dei job si leggono sulla pagina del run nella forge (job > il passaggio in rosso); l'API della forge non li restituisce.

Sintomo	Causa / correzione
Il job `key` fallisce in 30 s, subito dopo « Fetching the repository »	il container del job non risolve il nome della forge: il Docker-in-Docker del runner non ha DNS verso l'esterno. Datene uno: `dns: [1.1.1.1, 9.9.9.9]` sul servizio `dind` del file compose del runner. Test: `docker run --network <una nuova rete> node:20-bookworm getent hosts <forge>`
`Cannot find: pwsh in PATH`	il workflow richiede Windows PowerShell (`shell: powershell`); una vecchia copia richiedeva `pwsh`. Aggiornatela
`configure.js ... Erreur d'exécution Microsoft JScript` dopo « Checking for link.exe »	gli strumenti di Visual Studio scrivono nella lingua di Windows. `VSLANG=1033` (nel workflow da questa pagina)
`ERROR: bison is required`	visto dopo una build fatta a metà nella stessa cartella: StaticPHP conserva gli strumenti msys2 ma non li rimette nel PATH. Eliminate `spc/pkgroot`, `spc/source`, `spc/buildroot` dall'area di lavoro e rilanciate (un'area pulita, come quella di un nuovo job, funziona)
Una patch di StaticPHP « not patched (StaticPHP changed) » o « Failed patch module »	fine riga CRLF (`core.autocrlf false` e clonare di nuovo), oppure una cartella sorgente già corretta da un tentativo precedente (eliminate `spc/source/php-src`)
`Failed to get GitHub release API info for madler/zlib` / `HTTP/2 504`	`api.github.com` limita o fallisce per il vostro indirizzo. Il workflow ritenta; la prima esecuzione su una nuova macchina può richiedere un secondo tentativo. I download vengono conservati: ogni tentativo va più lontano
`GHESNotSupportedError: upload-artifact@v4 ... not currently supported`	usate Forgejo: prendete il workflow di questo repository (pubblica senza artefatti)
I job macOS restano « waiting » e il run non finisce mai	nessun runner macOS: `-f macos=false`
`Cannot find path ...\buildroot\bin\micro.sfx`	la costruzione è fallita prima: leggete le righe sopra (sono loro la causa)

Per gli agenti IA

Può esservi chiesto di « far funzionare il workflow standalone sul mio runner ». Leggete il passaggio fallito sulla pagina del run (chiedete all'utente di incollarlo se non potete accedervi), modificate il workflow (deve restare valido su GitHub: testate github.server_url), non la macchina dell'utente, a meno che ciò che manca sia un prerequisito qui sopra (Git, Visual Studio Build Tools, Docker per il job Linux): ditelo allora all'utente e installatelo solo se dice di sì. Non registrate mai un runner, non scrivete mai un token in un file, non pubblicate mai un micro che non avete costruito dai file attuali con i comandi di questo workflow, non spostate mai una release sotto un'altra chiave. Dopo un'esecuzione riuscita, verificate il file (gh release view standalone-<chiave>, un download che risponde 200) e, per un micro Windows, lanciate uno script con esso sulla macchina del runner (copy /b micro.sfx + test.php test.exe, poi test.exe: versione di PHP, extension_loaded('ffi')...).