jumphp2installer: um instalador para o seu software

O jumphp2installer cria instaladores nativos de verdade para Windows, macOS e Linux, para o seu jogo, a sua app JumPHP ou qualquer software. Você escreve um pequeno script YAML legível, e os seus utilizadores descarregam um único ficheiro. Ele mostra um assistente (boas-vindas, licença, pasta, opções), instala sempre a versão mais recente e acrescenta um desinstalador. É livre e de código aberto: github.com/davidnurdin/jumphp2installer.

O que faz

• Um ficheiro por sistema: Minha-App-setup.exe (Windows 10 e 11), Minha-App-setup-macos.zip (Mac Apple silicon e Intel), Minha-App-setup-linux-x86_64. Nada a instalar antes.
• Sempre a versão mais recente: o instalador lê o seu script ao arrancar. Um instalador descarregado há um ano instala, portanto, a versão de hoje.
• Um assistente com as suas cores: o seu nome, o seu ícone, a sua imagem lateral, a sua cor, a sua licença e os seus textos. Em inglês ou em francês, conforme o idioma do computador.
• Os passos habituais: descarregar (com verificação SHA-256), descompactar (.zip, .tar.gz), copiar, escrever um ficheiro, tornar executável, executar um comando, criar atalhos (ambiente de trabalho, menu).
• Um desinstalador a sério: aparece em «Aplicações» do Windows e no menu do Linux. Remove exatamente o que a instalação criou, e nada mais.
• Sem direitos de administrador: tudo se instala para o utilizador, na sua própria pasta de programas.
• Também na linha de comandos: --silent instala sem janela (implementações, scripts, CI).

O script de instalação

Um ficheiro install.yaml diz o que o instalador mostra (pages) e o que faz (steps). O mesmo script funciona nos três sistemas: as variáveis ({folder}, {platform}, {exe}…) e a chave os: tratam das diferenças.

app:
  name: Minha App
  publisher: Eu
  website: https://exemplo.pt
  icon: icon.png
  banner: banner.png          # a imagem à esquerda do assistente (172 x 420)
  accent: "#2f6fed"

version:
  github: eu/minha-app        # a release mais recente do GitHub dá {version}

pages:
  - welcome
  - license: LICENSE.txt
  - folder: "{programs}/{app}"
  - options:
      desktop: Um atalho no ambiente de trabalho
  - install
  - finish: {run: "{folder}/minha-app{exe}"}

steps:
  - download: https://github.com/eu/minha-app/releases/download/v{version}/minha-app-{platform}.zip
  - extract: {strip: 1}
  - executable: "{folder}/minha-app"
    os: [linux, macos]
  - shortcut: {target: "{folder}/minha-app{exe}", where: desktop}
    if: desktop
  - uninstaller

As páginas

Os passos

Cada passo aceita if: (uma opção marcada, ou "!opção"), os: (windows, macos, linux) e label:.

A versão

As variáveis

A referência completa está em docs/installer/script.md.

Três formas de o publicar

1. No jumphp.net, sem instalar nada

No estúdio, «Novo instalador» abre um editor:

• o script YAML é verificado enquanto escreve (cada erro com a sua linha);
• uma pré-visualização do assistente atualiza-se ao lado;
• carrega as imagens, a licença e os pequenos ficheiros do pacote.

Ao publicar, o instalador recebe a sua página de download e as suas três ligações, uma por sistema. Enquanto não estiver publicado, só você o pode experimentar.

2. Nas releases do GitHub, sem servidor

O pacote (install.yaml e os seus ficheiros) e os seus instaladores são anexados a cada release do seu repositório. Os instaladores leem a release mais recente, por isso não há nada a mudar de uma versão para a outra. Um workflow fá-lo a cada release:

# .github/workflows/installer.yml
on:
  release:
    types: [published]
jobs:
  installer:
    uses: davidnurdin/jumphp2installer/.github/workflows/package.yml@main
    with:
      folder: installer        # install.yaml e os seus ficheiros
    permissions:
      contents: write

Também o pode fazer à mão, a partir de um clone do jumphp2installer: tools/github-release.sh eu/minha-app installer. As suas ligações: https://github.com/eu/minha-app/releases/latest/download/Minha-App-setup.exe.

Se o seu repositório publica vários produtos (tags v* para um, ide-v* para outro), a «release mais recente» pode pertencer ao outro produto. Nesse caso, sirva o pacote a partir dos ficheiros do repositório (https://raw.githubusercontent.com/…/installer/), com um version.json ao lado. É o que faz o JumPHP IDE.

3. No seu próprio servidor

O servidor do jumphp2installer é uma app Symfony + MariaDB, em Docker (server/ do repositório): contas, editor, pré-visualização, páginas de download e estatísticas. Basta um docker compose up -d para o arrancar. Uma simples página web estática também pode servir de servidor (uma pasta com install.yaml e os seus ficheiros):

php tools/package-release.php meu-pacote/ https://meu-site.pt/instalador/ bases/ saida/

Para um jogo ou uma app JumPHP

bin/jumphp app:export minha-app --windows --macos (ou export:standalone para um jogo) produz um executável por sistema. Anexe-os a uma release e use o exemplo jumphp-app.yaml. O seu Claude sabe fazê-lo: peça-lhe «faz um instalador do meu jogo» (o repositório inclui um skill jumphp2installer).

Na linha de comandos

Minha-App-setup-linux-x86_64 --silent --folder=/opt/minha-app --no-option=desktop
Minha-App-setup.exe --silent
"C:\…\Minha App\uninstall.exe" --uninstall --silent
jumphp2installer-linux-x86_64 --check --script=install.yaml      # verificar um script
jumphp2installer-linux-x86_64 --script=install.yaml              # experimentar o assistente com um script local
jumphp2installer-linux-x86_64 --make=Minha-App-setup.exe --server=github:eu/minha-app --from=jumphp2installer-windows-x86_64.exe

Como funciona

O instalador é ele próprio uma app JumPHP: uma página HTML para o assistente, PHP para o trabalho e o PHP autónomo do StaticPHP. O endereço do pacote é escrito no php.ini incorporado do executável, com um tamanho constante. Assim, um servidor cria um instalador por pacote numa fração de segundo, sem compilar nada. Os downloads e a extração avançam um pouco a cada fotograma: a janela nunca congela. Antes de cada versão, o GitHub Actions experimenta o instalador a sério em Linux, Windows e dois Mac (Apple silicon e Intel): instalação, atalhos, entrada de desinstalação e depois desinstalação.

Limites

• Os instaladores não estão assinados: o Windows SmartScreen e o macOS Gatekeeper avisam na primeira vez (no Mac: clique direito › Abrir).
• Instalação apenas para o utilizador (sem Program Files, serviços nem associações de ficheiros).
• Sem Linux ARM nem telemóveis.
• No Windows, inicie-o pelo caminho longo, nunca por um nome curto 8.3 (C:\Users\RUNNER~1\…).