jumphp2installer: 내 소프트웨어를 위한 설치 프로그램

jumphp2installer는 게임, JumPHP 앱 또는 어떤 소프트웨어든 Windows, macOS, Linux용 진짜 네이티브 설치 프로그램을 만듭니다. 짧고 읽기 쉬운 YAML 스크립트만 쓰면 사용자는 파일 하나만 내려받습니다. 마법사(환영, 라이선스, 폴더, 옵션)를 보여 주고, 항상 최신 버전을 설치하며, 제거 프로그램도 추가합니다. 자유 오픈 소스입니다: github.com/davidnurdin/jumphp2installer.

스튜디오에서 설치 프로그램 만들기 jumphp2installer 내려받기

하는 일

시스템마다 파일 하나: My-App-setup.exe(Windows 10, 11), My-App-setup-macos.zip(Apple 실리콘과 Intel Mac), My-App-setup-linux-x86_64. 미리 설치할 것이 없습니다.
항상 최신 버전: 설치 프로그램은 시작할 때 스크립트를 읽습니다. 그래서 1년 전에 내려받은 설치 프로그램도 오늘의 버전을 설치합니다.
내 색깔의 마법사: 이름, 아이콘, 옆 이미지, 색상, 라이선스, 문구. 컴퓨터 언어에 따라 영어 또는 프랑스어로 표시됩니다.
흔히 쓰는 단계: 다운로드(SHA-256 확인 포함), 압축 해제(.zip, .tar.gz), 복사, 파일 쓰기, 실행 권한 부여, 명령 실행, 바로 가기 만들기(바탕 화면, 메뉴).
진짜 제거 프로그램: Windows의 "앱" 목록과 Linux 메뉴에 나타납니다. 설치가 만든 것만 정확히 지우고, 다른 것은 건드리지 않습니다.
관리자 권한 불필요: 모든 것이 사용자 자신의 프로그램 폴더에 설치됩니다.
명령줄에서도: --silent는 창 없이 설치합니다(배포, 스크립트, CI).

설치 스크립트

install.yaml 파일은 설치 프로그램이 보여 주는 것(pages)과 하는 일(steps)을 적습니다. 같은 스크립트가 세 시스템에서 모두 동작합니다. 차이는 변수({folder}, {platform}, {exe}…)와 os: 키가 처리합니다.

app:
  name: My App
  publisher: Me
  website: https://example.kr
  icon: icon.png
  banner: banner.png          # 마법사 왼쪽 이미지 (172 x 420)
  accent: "#2f6fed"

version:
  github: me/my-app           # GitHub 최신 릴리스가 {version}이 됨

pages:
  - welcome
  - license: LICENSE.txt
  - folder: "{programs}/{app}"
  - options:
      desktop: 바탕 화면 바로 가기
  - install
  - finish: {run: "{folder}/my-app{exe}"}

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

페이지

페이지	보여 주는 것
`welcome`	환영 문구(기본값: "{app} {version} 설치를 시작합니다")
`license`	패키지의 파일. 동의해야 계속할 수 있습니다
`folder`	폴더, "찾아보기…", 필요한 공간과 남은 공간. 이미 쓰이는 폴더면 알려 줍니다
`options`	체크 상자. 단계에서 다시 씁니다(`if: desktop`)
`install`	진행 막대와 세부 내용
`finish`	끝 화면. "{app} 실행" 체크 상자 포함(`run`, 시스템마다 다르게 지정 가능)

단계

단계
`download`	주소 또는 패키지의 파일. 파일이 맞지 않으면 `sha256`이 모든 것을 멈춥니다
`extract`	`{folder}`에 압축 해제. `strip: 1`은 압축 파일의 최상위 폴더를 뺍니다
`copy`, `mkdir`, `write`, `delete`	파일과 폴더(`delete`는 설치 폴더, 사용자 폴더, 임시 폴더 안에서만)
`executable`	파일에 실행 권한을 줍니다(Linux, macOS)
`shortcut`	`desktop`, `menu`, `both`: Windows는 `.lnk`, Linux는 `.desktop`, macOS는 링크
`run`	폴더에서 명령을 실행합니다
`uninstaller`	제거 프로그램을 두고 시스템에 등록합니다

모든 단계는 if:(체크된 옵션 또는 "!option"), os:(windows, macos, linux), label:을 받습니다.

버전

표기	`{version}`
`version: 1.4.0`	고정
`version: {github: me/my-app}`	저장소의 최신 릴리스(태그에서 `v`를 뺀 값)
`version: {latest: https://…/latest.json}`	주소의 응답: `{"version": "1.4.0"}` 또는 텍스트

변수

변수	Windows	Linux	macOS
`{programs}`	`%LOCALAPPDATA%\Programs`	`~/.local/opt`	`~/Applications`
`{desktop}`, `{menu}`	바탕 화면, 시작 메뉴	바탕 화면, `~/.local/share/applications`	`~/Desktop`
`{platform}`	`windows-x86_64`	`linux-x86_64`	`macos-arm64` / `macos-x86_64`
`{exe}`	`.exe`	(비어 있음)	(비어 있음)
`{folder}`, `{app}`, `{version}`, `{home}`, `{temp}`, `{os}`, `{arch}`, `{download}`

전체 참조는 docs/installer/script.md에 있습니다.

배포하는 세 가지 방법

1. jumphp.net에서, 아무것도 설치하지 않고

스튜디오에서 "새 설치 프로그램"을 누르면 편집기가 열립니다:

YAML 스크립트는 입력하는 동안 검사됩니다(오류마다 줄 번호 표시);
옆에서 마법사 미리 보기가 바뀝니다;
이미지, 라이선스, 패키지의 작은 파일을 끌어다 놓습니다.

게시하면 설치 프로그램에 다운로드 페이지와 시스템별 링크 3개가 생깁니다. 게시하기 전에는 본인만 시험할 수 있습니다.

2. GitHub 릴리스에서, 서버 없이

패키지(install.yaml과 그 파일)와 설치 프로그램을 저장소의 각 릴리스에 첨부합니다. 설치 프로그램은 최신 릴리스를 읽으므로 버전마다 바꿀 것이 없습니다. 워크플로가 릴리스마다 처리합니다:

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

jumphp2installer 클론에서 직접 할 수도 있습니다: tools/github-release.sh me/my-app installer. 링크는 https://github.com/me/my-app/releases/latest/download/My-App-setup.exe입니다.

저장소가 여러 제품을 릴리스한다면(한 제품은 v*, 다른 제품은 ide-v* 태그) "최신 릴리스"가 다른 제품의 것일 수 있습니다. 이때는 저장소의 파일에서 패키지를 제공하고(https://raw.githubusercontent.com/…/installer/), 옆에 version.json을 둡니다. JumPHP IDE가 이렇게 합니다.

3. 자신의 서버에서

jumphp2installer의 서버는 Docker에서 돌아가는 Symfony + MariaDB 앱입니다(저장소의 server/): 계정, 편집기, 미리 보기, 다운로드 페이지, 통계. docker compose up -d 한 번이면 시작됩니다. 단순한 정적 웹 페이지도 서버가 될 수 있습니다(install.yaml과 그 파일이 든 폴더):

php tools/package-release.php my-package/ https://my-site.kr/installer/ bases/ out/

JumPHP 게임이나 앱의 경우

bin/jumphp app:export my-app --windows --macos(게임은 export:standalone)는 시스템마다 실행 파일을 하나씩 만듭니다. 이를 릴리스에 첨부한 뒤 jumphp-app.yaml 예제를 쓰세요. Claude도 할 줄 압니다: "내 게임의 설치 프로그램을 만들어 줘"라고 부탁하세요(저장소에 jumphp2installer skill이 있습니다).

명령줄

My-App-setup-linux-x86_64 --silent --folder=/opt/my-app --no-option=desktop
My-App-setup.exe --silent
"C:\…\My App\uninstall.exe" --uninstall --silent
jumphp2installer-linux-x86_64 --check --script=install.yaml      # 스크립트 검사
jumphp2installer-linux-x86_64 --script=install.yaml              # 로컬 스크립트로 마법사 시험
jumphp2installer-linux-x86_64 --make=My-App-setup.exe --server=github:me/my-app --from=jumphp2installer-windows-x86_64.exe

작동 방식

설치 프로그램 자체가 JumPHP 앱입니다: 마법사는 HTML 페이지, 작업은 PHP, 그리고 StaticPHP의 독립 실행형 PHP. 패키지 주소는 실행 파일의 내장 php.ini에 크기를 바꾸지 않고 기록됩니다. 그래서 서버는 아무것도 컴파일하지 않고 패키지마다 설치 프로그램을 순식간에 만듭니다. 다운로드와 압축 해제는 프레임마다 조금씩 진행되어 창이 멈추지 않습니다. 버전마다 GitHub Actions가 Linux, Windows, Mac 두 대(Apple 실리콘과 Intel)에서 실제로 시험합니다: 설치, 바로 가기, 제거 항목, 그리고 제거.

제한 사항

설치 프로그램은 서명되지 않았습니다: Windows SmartScreen과 macOS Gatekeeper가 처음에 경고합니다(Mac: 오른쪽 클릭 › 열기).
사용자 단위 설치만 지원합니다(Program Files, 서비스, 파일 연결 없음).
Linux ARM과 휴대폰은 지원하지 않습니다.
Windows에서는 긴 경로로 실행하세요. 8.3 짧은 이름(C:\Users\RUNNER~1\…)으로는 안 됩니다.