jumphp2installer: instalator dla Twojego oprogramowania

jumphp2installer tworzy prawdziwe natywne instalatory dla Windows, macOS i Linuksa — dla Twojej gry, aplikacji JumPHP lub dowolnego programu. Piszesz krótki, czytelny skrypt YAML, a użytkownicy pobierają jeden plik. Pokazuje on kreator (powitanie, licencja, folder, opcje), zawsze instaluje najnowszą wersję i dodaje deinstalator. To wolne i otwarte oprogramowanie: github.com/davidnurdin/jumphp2installer.

Utwórz instalator w studiu Pobierz jumphp2installer

Strona powitalna kreatora instalacji — Powitanie

Co robi

Jeden plik na system: Moja-Aplikacja-setup.exe (Windows 10 i 11), Moja-Aplikacja-setup-macos.zip (Maki z Apple silicon i Intel), Moja-Aplikacja-setup-linux-x86_64. Nic nie trzeba wcześniej instalować.
Zawsze najnowsza wersja: instalator czyta Twój skrypt przy uruchomieniu. Instalator pobrany rok temu instaluje więc dzisiejszą wersję.
Kreator w Twoich kolorach: Twoja nazwa, ikona, obraz z boku, kolor, licencja i teksty. Po angielsku lub po francusku, zależnie od języka komputera.
Typowe kroki: pobieranie (ze sprawdzeniem SHA-256), rozpakowywanie (.zip, .tar.gz), kopiowanie, zapis pliku, nadanie praw wykonywania, uruchomienie polecenia, tworzenie skrótów (pulpit, menu).
Prawdziwy deinstalator: widoczny w „Aplikacjach” Windows i w menu Linuksa. Usuwa dokładnie to, co utworzyła instalacja, i nic więcej.
Bez uprawnień administratora: wszystko instaluje się dla użytkownika, w jego własnym folderze programów.
Także z wiersza poleceń: --silent instaluje bez okna (wdrożenia, skrypty, CI).

Skrypt instalacji

Plik install.yaml mówi, co instalator pokazuje (pages) i co robi (steps). Ten sam skrypt działa na trzech systemach: zmienne ({folder}, {platform}, {exe}…) i klucz os: obsługują różnice.

app:
  name: Moja Aplikacja
  publisher: Ja
  website: https://przyklad.pl
  icon: icon.png
  banner: banner.png          # obraz po lewej stronie kreatora (172 x 420)
  accent: "#2f6fed"

version:
  github: ja/moja-aplikacja   # najnowsze wydanie na GitHubie daje {version}

pages:
  - welcome
  - license: LICENSE.txt
  - folder: "{programs}/{app}"
  - options:
      desktop: Skrót na pulpicie
  - install
  - finish: {run: "{folder}/moja-aplikacja{exe}"}

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

Strony

Strona	Co pokazuje
`welcome`	tekst powitalny (domyślnie: „Witamy w instalacji {app} {version}”)
`license`	plik z pakietu, który trzeba zaakceptować, aby przejść dalej
`folder`	folder, z przyciskiem „Przeglądaj…”, potrzebnym i wolnym miejscem; ostrzega, gdy folder jest już używany
`options`	pola wyboru, używane ponownie przez kroki (`if: desktop`)
`install`	pasek postępu i szczegóły
`finish`	koniec, z polem „Uruchom {app}” (`run`, które może zależeć od systemu)

Kroki

Krok
`download`	adres lub plik z pakietu; `sha256` zatrzymuje wszystko, jeśli plik jest niewłaściwy
`extract`	rozpakowuje do `{folder}`; `strip: 1` pomija główny folder archiwum
`copy`, `mkdir`, `write`, `delete`	pliki i foldery (`delete` dotyka tylko folderu instalacji, folderu użytkownika i folderu tymczasowego)
`executable`	nadaje plikowi prawo wykonywania (Linux, macOS)
`shortcut`	`desktop`, `menu` lub `both`: `.lnk` w Windows, `.desktop` w Linuksie, dowiązanie w macOS
`run`	uruchamia polecenie w folderze
`uninstaller`	instaluje deinstalator i rejestruje go w systemie

Każdy krok przyjmuje if: (zaznaczona opcja lub "!opcja"), os: (windows, macos, linux) i label:.

Wersja

Zapis	`{version}`
`version: 1.4.0`	stała
`version: {github: ja/moja-aplikacja}`	najnowsze wydanie repozytorium (jego tag, bez `v`)
`version: {latest: https://…/latest.json}`	to, co odpowiada adres: `{"version": "1.4.0"}` lub tekst

Zmienne

Zmienna	Windows	Linux	macOS
`{programs}`	`%LOCALAPPDATA%\Programs`	`~/.local/opt`	`~/Applications`
`{desktop}`, `{menu}`	pulpit, menu Start	pulpit, `~/.local/share/applications`	`~/Desktop`
`{platform}`	`windows-x86_64`	`linux-x86_64`	`macos-arm64` / `macos-x86_64`
`{exe}`	`.exe`	(puste)	(puste)
`{folder}`, `{app}`, `{version}`, `{home}`, `{temp}`, `{os}`, `{arch}`, `{download}`

Pełna dokumentacja jest w docs/installer/script.md.

Trzy sposoby publikacji

1. Na jumphp.net, bez instalowania czegokolwiek

W studiu przycisk „Nowy instalator” otwiera edytor:

skrypt YAML jest sprawdzany podczas pisania (każdy błąd z numerem linii);
podgląd kreatora odświeża się obok;
wrzucasz obrazy, licencję i małe pliki pakietu.

Po publikacji instalator dostaje stronę pobierania i trzy linki, po jednym na system. Dopóki nie jest opublikowany, tylko Ty możesz go wypróbować.

2. W wydaniach GitHuba, bez serwera

Pakiet (install.yaml i jego pliki) oraz instalatory są dołączane do każdego wydania Twojego repozytorium. Instalatory czytają najnowsze wydanie, więc między wersjami nie trzeba nic zmieniać. Workflow robi to przy każdym wydaniu:

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

Możesz to też zrobić ręcznie, z klonu jumphp2installer: tools/github-release.sh ja/moja-aplikacja installer. Twoje linki: https://github.com/ja/moja-aplikacja/releases/latest/download/Moja-Aplikacja-setup.exe.

Jeśli Twoje repozytorium wydaje kilka produktów (tagi v* dla jednego, ide-v* dla drugiego), „najnowsze wydanie” może należeć do innego produktu. Wtedy udostępniaj pakiet z plików repozytorium (https://raw.githubusercontent.com/…/installer/), z plikiem version.json obok. Tak robi JumPHP IDE.

3. Na własnym serwerze

Serwer jumphp2installer to aplikacja Symfony + MariaDB w Dockerze (server/ w repozytorium): konta, edytor, podgląd, strony pobierania i statystyki. Uruchamia go jedno docker compose up -d. Zwykła statyczna strona WWW również może służyć za serwer (folder z install.yaml i jego plikami):

php tools/package-release.php moj-pakiet/ https://moja-strona.pl/instalator/ bases/ out/

Dla gry lub aplikacji JumPHP

bin/jumphp app:export moja-aplikacja --windows --macos (lub export:standalone dla gry) tworzy jeden plik wykonywalny na system. Dołącz je do wydania, a potem użyj przykładu jumphp-app.yaml. Twój Claude to potrafi: poproś go „zrób instalator mojej gry” (repozytorium zawiera skill jumphp2installer).

Z wiersza poleceń

Moja-Aplikacja-setup-linux-x86_64 --silent --folder=/opt/moja-aplikacja --no-option=desktop
Moja-Aplikacja-setup.exe --silent
"C:\…\Moja Aplikacja\uninstall.exe" --uninstall --silent
jumphp2installer-linux-x86_64 --check --script=install.yaml      # sprawdzić skrypt
jumphp2installer-linux-x86_64 --script=install.yaml              # wypróbować kreator z lokalnym skryptem
jumphp2installer-linux-x86_64 --make=Moja-Aplikacja-setup.exe --server=github:ja/moja-aplikacja --from=jumphp2installer-windows-x86_64.exe

Jak to działa

Instalator sam jest aplikacją JumPHP: strona HTML dla kreatora, PHP do pracy i samodzielny PHP ze StaticPHP. Adres pakietu jest zapisany we wbudowanym php.ini pliku wykonywalnego, przy stałym rozmiarze. Serwer może więc w ułamku sekundy zrobić instalator dla każdego pakietu, niczego nie kompilując. Pobieranie i rozpakowywanie posuwają się trochę w każdej klatce: okno nigdy się nie zawiesza. Przed każdą wersją GitHub Actions naprawdę testuje instalator na Linuksie, Windows i dwóch Makach (Apple silicon i Intel): instalacja, skróty, wpis deinstalacji, potem deinstalacja.

Ograniczenia

Instalatory nie są podpisane: Windows SmartScreen i macOS Gatekeeper ostrzegają za pierwszym razem (na Macu: prawy przycisk › Otwórz).
Instalacja tylko dla użytkownika (bez Program Files, usług i skojarzeń plików).
Brak Linuksa ARM i telefonów.
W Windows uruchamiaj go po długiej ścieżce, nigdy po krótkiej nazwie 8.3 (C:\Users\RUNNER~1\…).