Construir o micro PHP nos seus próprios runners (o workflow `standalone`)

bin/jumphp export:standalone e app:export colam um jogo ou uma aplicação num micro: um PHP construído de forma estática (StaticPHP) com as extensões de que o JumPHP precisa. Os micros são construídos pelo workflow .github/workflows/standalone.yml e publicados como a release standalone-<chave> (a chave é uma impressão digital da versão do PHP, da lista de extensões, do commit do StaticPHP e do registo e dos patches do JumPHP: tools/standalone-key.sh). Um micro só é por isso reconstruído se um destes elementos mudar. Esta página explica como lançar este workflow nos seus runners (ci-runner.md para os instalar), e o que as máquinas do GitHub davam de graça e que as suas talvez não tenham.

Lançá-lo

Forja > o repositório > Actions > standalone > Run workflow, ou a partir de um terminal (gh é o da forja num projeto JumPHP):

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

Entrada	Valores
`extensions`	`tools/standalone-extensions.txt` (jogos: SDL, OpenGL, OpenAL), `tools/app-extensions.txt` (aplicações de ambiente de trabalho, o IDE), `tools/hybrid-extensions.txt`	o micro construído = a sua própria chave
`linux`	`true` / `false`	`false`: sem micro Linux (ver « Docker » mais abaixo); `export:standalone` constrói então o de Linux no computador do utilizador
`macos`	`true` / `false`	`false`: sem micro Mac (apenas aplicações de ambiente de trabalho); sem um runner macOS, os jobs esperariam indefinidamente

O job Windows demora cerca de 10 minutos com as transferências em cache, 30 a 60 da primeiríssima vez. O seu resultado: https://<forja>/<proprietário>/<repositório>/releases/download/standalone-<chave>/micro-windows-x86_64.sfx.

O que as máquinas do GitHub tinham e que as suas talvez não tenham

No GitHub, o mesmo workflow « funcionava sozinho » porque windows-latest e ubuntu-latest são imagens preparadas pelo GitHub. Um runner seu é uma máquina nua. Tudo o que se segue é tratado pelo workflow, ou é dito aqui:

A imagem do GitHub	Um runner seu	O que faz o workflow / o que faz você
PowerShell 7 (`pwsh`), PHP, Composer, Git	muitas vezes apenas Windows PowerShell 5.1 e Git	os passos correm no Windows PowerShell; PHP 8.4 e Composer são descarregados (php.net, getcomposer.org, impressão digital verificada) se faltarem; o `usr\bin` do Git entra no PATH
Windows em inglês	a língua do seu Windows (francês...)	`VSLANG=1033` faz as ferramentas do Visual Studio falar inglês: o `configure.js` do PHP lê a saída do linker e, caso contrário, pára com um erro JScript
Visual Studio 2022	a instalar por si: Build Tools 2022, carga de trabalho « Desenvolvimento para ambiente de trabalho com C++ »	a única coisa que um runner Windows tem de ter (com o Git para Windows). install-windows-runner.ps1 instala ambos
Acesso rápido a `api.github.com`, raramente limitado	a mesma API responde `504` ou « rate limit exceeded »	as transferências do StaticPHP são repetidas 4 vezes e guardadas em `%USERPROFILE%\.spc-downloads` entre duas execuções; o Composer instala a partir das fontes (`--prefer-source`)
`actions/upload-artifact@v4`, `download-artifact@v4`	o Forgejo não os suporta (« not currently supported on GHES »)	numa forja, o job Windows publica ele próprio o micro na release (o `github.token` do job, a API da forja); o job `release` só corre no GitHub
Docker no job Linux	o job corre num contentor sem Docker	ver abaixo
Fins de linha LF	o Git para Windows converte para CRLF	`git config --global core.autocrlf false` antes de clonar o StaticPHP (um patch dos seus ficheiros baseia-se no texto deles)

Docker: onde é preciso, onde não é

O job Windows compila em nativo com o Visual Studio. Não usa Docker e um runner Windows não saberia fazê-lo (os contentores Linux sob Windows passam pelo WSL2). Nada a instalar para isso.
O job Linux lança docker build docker/standalone e depois docker run do StaticPHP. Num contentor de job não há Docker, a menos que o runner forneça um: monte o socket Docker do anfitrião (ou do dind do runner) no job (container.options / valid_volumes no config.yml do runner), ou use o runner Linux WSL2 (ci-runner.md secção 4), um verdadeiro Linux com Docker. Sem isso, lance com linux=false: bin/jumphp export:standalone <id> --linux constrói o micro Linux no computador que exporta (cerca de 15 minutos, depois guardado em ~/.jumphp/standalone/).
Seja qual for o runner, nunca copie nem renomeie um micro para outra chave: seria um PHP sem as extensões certas e os executáveis dos seus utilizadores falhariam (Call to undefined function SDL_Init()). Se a chave mudou, o micro tem de ser reconstruído.

Resolução de problemas

Os registos dos jobs leem-se na página do run na forja (job > o passo a vermelho); a API da forja não os devolve.

Sintoma	Causa / correção
O job `key` falha em 30 s, logo a seguir a « Fetching the repository »	o contentor do job não resolve o nome da forja: o Docker-in-Docker do runner não tem DNS para o exterior. Dê-lhe um: `dns: [1.1.1.1, 9.9.9.9]` no serviço `dind` do ficheiro compose do runner. Teste: `docker run --network <uma nova rede> node:20-bookworm getent hosts <forja>`
`Cannot find: pwsh in PATH`	o workflow pede o Windows PowerShell (`shell: powershell`); uma cópia antiga pedia `pwsh`. Atualize-a
`configure.js ... Erreur d'exécution Microsoft JScript` depois de « Checking for link.exe »	as ferramentas do Visual Studio escrevem na língua do Windows. `VSLANG=1033` (no workflow desde esta página)
`ERROR: bison is required`	visto depois de uma construção a meio na mesma pasta: o StaticPHP guarda as ferramentas msys2 mas não as volta a pôr no PATH. Elimine `spc/pkgroot`, `spc/source`, `spc/buildroot` do espaço de trabalho e relance (um espaço limpo, como o de um novo job, funciona)
Um patch do StaticPHP « not patched (StaticPHP changed) » ou « Failed patch module »	fins de linha CRLF (`core.autocrlf false` e clonar de novo), ou uma pasta de fontes já corrigida por uma tentativa anterior (elimine `spc/source/php-src`)
`Failed to get GitHub release API info for madler/zlib` / `HTTP/2 504`	`api.github.com` limita ou falha para o seu endereço. O workflow repete; a primeira execução numa máquina nova pode precisar de uma segunda tentativa. As transferências ficam guardadas: cada tentativa vai mais longe
`GHESNotSupportedError: upload-artifact@v4 ... not currently supported`	está a usar o Forgejo: use o workflow deste repositório (publica sem artefactos)
Os jobs macOS ficam « waiting » e o run nunca termina	sem runner macOS: `-f macos=false`
`Cannot find path ...\buildroot\bin\micro.sfx`	a construção falhou antes: leia as linhas acima (são elas a causa)

Para os agentes de IA

Podem pedir-lhe para « fazer o workflow standalone funcionar no meu runner ». Leia o passo que falhou na página do run (peça ao utilizador que o cole se não lhe conseguir aceder), modifique o workflow (tem de continuar válido no GitHub: teste github.server_url), não a máquina do utilizador, a menos que o que falta seja um pré-requisito acima (Git, Visual Studio Build Tools, Docker para o job Linux): diga-o então ao utilizador e só o instale se ele disser que sim. Nunca registe um runner, nunca escreva um token num ficheiro, nunca publique um micro que não construiu a partir dos ficheiros atuais com os comandos deste workflow, nunca mova uma release para outra chave. Depois de uma execução bem-sucedida, verifique o ficheiro (gh release view standalone-<chave>, uma transferência que responda 200) e, para um micro Windows, execute um script com ele na máquina do runner (copy /b micro.sfx + test.php test.exe, depois test.exe: versão do PHP, extension_loaded('ffi')...).