winzik/docs/apple.md

107 lines
7.3 KiB
Markdown

# The game as native Apple apps (macOS, iPhone / iPad)
`bin/jumphp apple <game>` makes **real Apple apps** of a game: no browser, no WebView. PHP 8.5, SDL2, OpenGL (ES on
iOS) and OpenAL run inside the app, as on the desktop and in the native Android app ([android-native.md](android-native.md)).
- **macOS**: one `.app` for Apple silicon and Intel Macs (macOS 11 or newer), as a `.dmg` and a `.zip`;
- **iPhone / iPad**: an `.ipa` (iOS 14 or newer), the on-screen controls (d-pad or joystick, A / B / START) drawn
by the engine, the game's orientation; and the same app for **Xcode's iOS simulator**.
**A desktop app** (`ui: webview`, [tauri.md](tauri.md)): `bin/jumphp ios <app>` makes an iPhone / iPad app of its
browser build (made first on GitHub's Linux machines, `bin/jumphp build`) shown by a `WKWebView` from a scheme of its own
(`jumphp://app/`, inside the app), with a bridge for "save to Files", notifications, links, sharing and the clipboard
(`tools/apple/webview/main.m`); no PHP to build, so a few minutes. Its Mac app is Tauri's (`bin/jumphp app:export
<app> --macos`). **Not tried yet** on a Mac: the first run may need fixes.
Building them needs Xcode, so a Mac: the command has **GitHub build them on one of its Macs** (free for a public
repository), from any computer.
## One command
```
bin/jumphp apple pong # macOS + iOS
bin/jumphp macos pong # only the Mac app
bin/jumphp ios pong # only the iPhone / iPad app (and the simulator's)
```
1. the first time it asks the apps' **bundle identifier** (`io.github.<you>.<game>`: it never changes on the App
Store; letters, digits, hyphens and dots);
2. it writes the version in `games/<game>/apple/app.json` (in git: bundle identifier, build + 1, version), puts the
workflow `.github/workflows/apple.yml` in the project, commits them and, **after your yes**, pushes;
3. GitHub builds the apps on a Mac (first time ~40 min, then ~10: PHP and the libraries are kept in the Actions
cache), **tries them there** (the Mac app runs the game headless and saves its picture; the iPhone app is
installed in an iPhone simulator, launched, photographed), and publishes the release
`apple-<game>-<version>-<build>` with the apps and the two screenshots; the command downloads them into
`games/<game>/dist/apple/` (the screenshots in `check/`).
**Files that are not in git** (the data of an original game, kept out of a public repository): the command finds
the game's git-ignored files (not `vendor/`, `var/`, `dist/`...) and, after your yes (`JUMPHP_PRIVATE_FILES=1` without a
terminal), sends them as `private.tar.gz` in the **draft release** `apple-private-<game>`: a draft is only seen by the
repository's writers, never published; the workflow puts the files back into the game before the build. Delete it
with `gh release delete apple-private-<game>` when you no longer build there. The apps contain these files, so their
release is then made as a **draft** too: you decide whether to publish it (don't publish apps of a game whose data you
may not distribute).
Options: `--bundle-id`, `--version 1.1` (the build number goes up by one at each build), `--macos` / `--ios`,
`--local` (on a Mac with Xcode, cmake, autoconf and PHP with GD: built and tried there).
| File | What |
|---|---|
| `<game>-<v>-macos.dmg`, `-macos.zip` | the Mac app |
| `<game>-<v>-ios.ipa` | the iPhone / iPad app, to sign for a device (below) |
| `<game>-<v>-ios-simulator.zip` | the app for Xcode's simulator: unzip, drag the `.app` onto a simulator |
| `check/macos.png`, `check/ios.png` | the game running on GitHub's Mac (headless) and in the iPhone simulator |
## Without an Apple developer account (now)
The apps are signed **ad hoc** (no identity):
- **Mac**: the app opens after **right click > Open** the first time (macOS asks once), or
`xattr -dr com.apple.quarantine "/Applications/<Game>.app"`. Fine for friends and testers, not for everyone.
- **iPhone / iPad**: an iPhone only installs an app signed for it. The `.ipa` waits for an account (below). In the
meantime: the simulator's app (on a Mac with Xcode), and the web version installs from Safari (Share > Add to
Home Screen).
## With an Apple developer account (later)
Each developer uses **their own** account of the [Apple Developer Program](https://developer.apple.com/programs/)
(99 $ a year): the apps are published under their name, with their certificates, in their repository's secrets;
JumPHP never holds an account for anyone. It is needed to:
- put a Mac app online without the right click: **Developer ID** signing + **notarization** by Apple;
- install the iPhone app on a device (more than 7 days) and send it to **TestFlight** / the **App Store**.
What it will take (the next step of this work): a signing certificate and, for iOS, a provisioning profile in the
repository's secrets, and an App Store Connect API key; the workflow then signs (`codesign`), notarizes the Mac app
(`notarytool`) and uploads the iPhone app to TestFlight (`altool` / App Store Connect API). The App Store accepts a
PHP game: the code runs inside the app and ships with it (guideline 2.5.2); nothing is downloaded later.
## What is in the apps
| Part | Where |
|---|---|
| PHP 8.5 (embed SAPI, static, no JIT: Apple forbids it on iOS) with php-sdl, sdl_image, sdl_mixer, sdl_ttf, PHP-OpenGL, PHP-OpenAL, gd (PNG), bcmath, openssl, mbstring, phar, sockets, zlib | built with Xcode's clang per target (macOS arm64 / x86_64, iPhone arm64, simulator arm64): `tools/apple/build.sh`, the extensions' `tools/android/ext/*.m4` (the same as Android's) |
| SDL2 (UIKit on iOS, Cocoa on macOS), SDL2_image / _mixer / _ttf, OpenAL Soft (CoreAudio) | static, `tools/apple/project/CMakeLists.txt` |
| the launcher: finds the game in the bundle, runs it | `tools/apple/project/main.c` |
| the game, as the desktop runs it (`tools/stage-game.sh`) | `<Game>.app/Contents/Resources/game` (macOS), `<Game>.app/game` (iOS) |
| name, icon (`assets/icon.png`, else the title's initial), orientation (the game's shape), version | project.yaml, `games/<game>/apple/app.json` |
The saves and options are in the app's Application Support folder (`JUMPHP_VAR`), kept across updates. PHP's output
and errors go to stdout / stderr: Xcode's console, `xcrun simctl launch --console booted <bundle id>`, or the terminal
(`"/Applications/<Game>.app/Contents/MacOS/<game>"`).
The engine knows where it runs: `JUMPHP_IOS` (Platform::isPhoneApp(): full screen, the game's orientation),
`JUMPHP_MOBILE` and the on-screen controls (`JUMPHP_TOUCH_CONTROLS`, project.yaml `touch:` as in the browser) on iOS;
`JUMPHP_MACOS` on the Mac. SDL draws with OpenGL ES 2 on iOS (as on Android) and OpenGL on macOS (as on Linux), so a
game's own GL (`gl()`, `opengl()`) shares SDL's context; macOS' OpenGL takes GLSL 1.20, not GLSL ES 1.00: the engine
turns the games' shaders into it (OpenGl::versioned()).
HTTPS (`$engine->http()`, online play over `wss://`): PHP's openssl with the game's CA certificates (`cacert.pem`,
from the build Mac's `/etc/ssl/cert.pem`).
## Build it elsewhere
The workflow is plain GitHub Actions (`macos-15`): Actions > apple > Run workflow (game, bundle identifier, version,
build, platforms) works without the command. On any Mac: `GAME=pong BUNDLE_ID=io.github.me.pong bash tools/apple/build.sh`
then `bash tools/apple/check.sh pong` (needs Xcode, `brew install cmake autoconf`, PHP 8.2+ with GD and composer, and
the game's `vendor/`).