rinkplanner/docs/builds.md

259 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Builds: Desktop und Android
Rinkplanner wird als **Desktop-Anwendung** (Linux/Windows/macOS) und als
**Android-App** gebaut. Einen Web-Build gibt es nicht mehr: Die App braucht
lokalen Dateizugriff, ein eigenes Fenster und später einen Kontosync, der
nicht von Browser-Speicherlimits abhängt.
## Übersicht
| Ziel | Preset | Ausgabe | Größe (ca.) |
| :--- | :--- | :--- | :--- |
| Linux x86_64 | `Linux` | `build/linux/rinkplanner.x86_64` | 80 MB |
| Windows x86_64 | `Windows` | `build/windows/rinkplanner.exe` | 116 MB |
| Windows-Installer | `Windows` | `build/windows/rinkplanner-setup.exe` | 35 MB |
| macOS universal | `macOS` | `build/macos/rinkplanner.zip` | 67 MB |
| macOS-Installer | `macOS` | `build/macos/rinkplanner-setup.dmg` | 68 MB |
| Android arm64 | `Android` | `build/android/rinkplanner-debug.apk` | 31 MB |
Die PCK ist bei Linux und Windows **eingebettet** (eine Datei zum
Weitergeben). `build/` ist nicht versioniert. Seit die Skater-GLB samt
Texturen in den Exporten liegt (`docs/assets.md`), sind die Builds etwa
6 MB größer; die Werte sind Richtwerte.
## Voraussetzungen
- Godot **4.7.2** (oder `GODOT=/pfad/zu/godot` setzen)
- Für die 3D-Vorschau im Build: `tools/sync_assets.sh --sync` (GLB plus
Texturen unter `assets/external/characters/`); ohne diese Dateien baut der
Export den Platzhalter.
- Export-Templates derselben Version unter
`~/.local/share/godot/export_templates/4.7.2.stable/`
- Für den Cloud-Sync: `rinkplanner/sync_apps.cfg` mit den OAuth-App-Zugängen.
Die Datei wird aus `docs/credentials.txt` erzeugt:
`./tools/sync_apps_config.sh`; Einrichtung in `docs/cloud-setup.md`.
Ohne die Datei baut die App, zeigt beim Verbinden aber einen
Konfigurationshinweis.
- Für Android zusätzlich JDK 17 + Android SDK (siehe unten)
## Desktop bauen
```bash
./tools/export_linux.sh
./tools/export_windows.sh
./tools/export_macos.sh
./tools/export_macos_installer.sh # macOS-DMG (nur auf macOS)
```
**Windows:** Die .exe enthält Icon, Produktname, Beschreibung und Version.
Godot bettet sie mit `rcedit` ein; auf Linux läuft `rcedit` über ein
portables Wine. Einmalig einrichten (kein Root nötig):
```bash
./tools/setup_windows_export.sh
```
Das Skript lädt Wine (Kron4ek-Build) und `rcedit` nach
`~/.local/share/rinkplanner-toolchain`, legt einen Wrapper an und trägt ihn
als `export/windows/rcedit` in die Godot-Editor-Settings ein. Die Werte
selbst stehen im Preset unter `application/*` (Icon `app_icon.png`,
Version `0.1.0.0`).
### Windows-Installer
Der portable EXE bleibt der Standard. Zusätzlich gibt es einen
per-user-Installer, der ohne Administratorrechte auskommt:
```bash
./tools/setup_windows_installer.sh # einmalig: NSIS lokal, ohne sudo
./tools/export_windows_installer.sh # EXE neu bauen + Installer
./tools/export_windows_installer.sh --no-export # nur Installer aus vorhandener EXE
```
Ausgabe: `build/windows/rinkplanner-setup.exe` (ca. 35 MB).
- Installation nach `%LOCALAPPDATA%\Programs\Rinkplanner`
- Startmenü- und optionale Desktop-Verknüpfung
- Uninstaller in „Apps & Features“ (pro Benutzer, kein Admin)
- Kürdateien unter `%APPDATA%\Godot\app_userdata\Rinkplanner` bleiben bei
der Deinstallation erhalten
- `setup_windows_installer.sh` lädt die NSIS-Pakete per `apt-get download`
und entpackt sie nach `~/.local/share/rinkplanner-toolchain/nsis`; auf
Nicht-Debian-Systemen muss `makensis` manuell bereitstehen
Ohne Authenticode-Signatur zeigt Windows weiterhin die SmartScreen-Warnung
(„Windows hat den PC geschützt“). Der Installer ist bequemer, aber nicht
signiert; das ist ein separater Schritt.
**macOS:** Der Installer ist ein DMG mit `Rinkplanner.app`, einer
Verknüpfung auf `/Applications` („Programme“) und einer kurzen Anleitung zum
ersten Start:
```bash
./tools/export_macos_installer.sh # App neu bauen + DMG
./tools/export_macos_installer.sh --no-export # nur DMG aus vorhandener ZIP
```
Ausgabe: `build/macos/rinkplanner-setup.dmg` (ca. 68 MB). Das Skript läuft
nur auf macOS (`hdiutil`); die App wird aus `build/macos/rinkplanner.zip`
entpackt. Die ZIP-Variante plus `start_rinkplanner.command` bleibt als
Alternative erhalten.
Das Bundle ist ad-hoc signiert, aber **nicht notarisiert**. Beim ersten Start
auf einem Mac:
```bash
xattr -cr /Applications/Rinkplanner.app
open /Applications/Rinkplanner.app # ggf. Rechtsklick → Öffnen
```
Für eine verteilbare App ist eine Signierung mit Developer ID und
Notarisierung auf einem Mac nötig (Preset: `codesign/codesign=3`).
## Android
### Einmalig: Toolchain einrichten
```bash
./tools/setup_android.sh
```
Das Skript (idempotent, ca. 1,6 GB Download):
1. Temurin **JDK 17** → `~/.jdks/temurin-17`
2. Android **command-line tools** → `~/Android/Sdk`
3. `platform-tools`, `build-tools;36.0.0`, `build-tools;35.0.0`,
`platforms;android-36`
4. Godot-**4.7.2-Export-Templates**
5. **Debug-Keystore** → `~/.local/share/godot/keystores/debug.keystore`
6. Trägt `java_sdk_path`, `android_sdk_path` und `debug_keystore` in
`~/.config/godot/editor_settings-4.7.tres` ein (Backup als `.bak`)
### APK bauen
```bash
./tools/export_android.sh # Debug-APK
./tools/export_android.sh debug --install # bauen + per adb installieren
```
Ausgabe: `build/android/rinkplanner-debug.apk`
Prüfen (Paketname, Version, SDK-Stufen, ABI, Landscape, Signatur):
```bash
./tools/verify_apk.sh
```
`aapt2` warnt beim Debug-APK über ein ungenutztes `mipmap/themed_icon` aus
dem Godot-Template. Das Manifest referenziert nur `@mipmap/icon`; die Warnung
ist folgenlos.
- Paket: `de.rinkplanner.app`, Label „Rinkplanner“, Version 0.1.0
- App-Icon aus der Silhouetten-Vorlage, erzeugt mit
`tools/make_app_icons.py` (Launcher-Icons unter
`rinkplanner/assets/icons/android/`); aktuell die **invertierte**
Variante (weiße Kachel, schwarze Figur)
- `minSdk 24`, `targetSdk 36`, ABI **arm64-v8a** (Galaxy Tab S9+)
- Landscape, Immersive Mode, `resizeableActivity=true`
- Berechtigung `INTERNET` (für den späteren Sync)
- Template-Export ohne Gradle-Projekt (`gradle_build/use_gradle_build=false`)
### Auf dem Zielgerät verifiziert
Galaxy Tab S9+ (SM-X810), 2800 × 1752, 340 dpi (Skalierung 2,125), Landscape:
- Installation per `adb install -r` (Incremental Install, ca. 2 s)
- Start, Zeichnen, Tippen, Labels und Zurück-Geste (beendet und speichert)
- UI-Skalierung: 56-Pixel-Ziele entsprechen echten 56 CSS-Pixeln
- App-Daten einsehbar über `adb shell run-as de.rinkplanner.app ls files/`
### Auf dem Tablet installieren
1. Auf dem Tablet: Einstellungen → Info zu Tablet → 7× „Buildnummer“ →
Entwickleroptionen → **USB-Debugging** an
2. Tablet per USB anschließen, „Dateizugriff zulassen“ bestätigen
3. **Linux:** einmalig die udev-Regel installieren, sonst meldet `adb`
„no permissions“ (auf einem frisch eingerichteten Rechner fehlt sie):
```bash
sudo install -m 644 tools/51-android.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
```
Danach das Tablet neu anstecken.
4. `adb devices` prüfen, dann
```bash
~/Android/Sdk/platform-tools/adb install -r build/android/rinkplanner-debug.apk
```
Alternativ die APK direkt aufs Tablet kopieren und dort öffnen
(„Unbekannte Quellen“ erlauben).
### Wo liegen die Daten?
Godot schreibt `user://` pro Plattform getrennt:
| Plattform | Pfad |
| :--- | :--- |
| Linux | `~/.local/share/godot/app_userdata/Rinkplanner/` |
| Windows | `%APPDATA%\Godot\app_userdata\Rinkplanner\` |
| macOS | `~/Library/Application Support/Godot/app_userdata/Rinkplanner/` |
| Android | App-interner Speicher (`/data/data/de.rinkplanner.app/files/`) |
Dort liegen `routines/`, `autosave.json` und `exports/`. Die Android-Daten
sind ohne Root nicht direkt sichtbar – der Export-Dialog der App schreibt
nach `user://exports/`, von dort kann man Dateien über einen Dateimanager
mit App-Zugriff oder `adb pull` holen:
```bash
adb shell run-as de.rinkplanner.app ls files/
adb exec-out run-as de.rinkplanner.app cat files/routines/kuer.json > kuer.json
```
## Export-Smoke-Test
`tools/check_export.sh` baut den Linux-Release in ein temporäres Verzeichnis,
startet ihn headless und bricht bei Start-/Autoload-Fehlern ab. Zusätzlich
prüft es, dass keine Testskripte im Build landen und die Skater-Szene samt
Texturen enthalten ist, sofern die GLB lokal unter
`assets/external/characters/` liegt.
```bash
./tools/check_export.sh
# oder zusammen mit den Headless-Tests:
./tools/test.sh --export
```
Fehlt die GLB auf einem frischen Checkout, bricht der Test mit einem Hinweis
auf `tools/sync_assets.sh --sync` ab. Für einen reinen Starttest ohne
3D-Asset: `./tools/check_export.sh --allow-placeholder`.
## Bekannte Grenzen
- Die obere Werkzeugleiste hat eine Mindestbreite von ca. 1024 logischen
Pixeln (kompakte Beschriftungen). Hochformat, geteilter Bildschirm und
kleine DeX-Fenster beschneiden sie; Vollbild-Landscape ist korrekt.
- Die Android-APK enthält nur `arm64-v8a`.
- Die Windows-Ressourcen (Icon/Version) werden nur eingebettet, wenn
`tools/setup_windows_export.sh` gelaufen ist.
- Der Windows-Installer ist nicht signiert (SmartScreen-Warnung).
- macOS ist ad-hoc signiert, nicht notarisiert.
## Release-Builds
- **Android Release:** eigener Keystore nötig; im Preset
`keystore/release*` setzen und `./tools/export_android.sh release` bauen.
Der Debug-Keystore ist nur zum Testen.
- **Windows:** portable EXE oder `rinkplanner-setup.exe`; für eine
warnungsfreie Installation ist eine Authenticode-Signatur nötig.
- **macOS:** siehe Hinweise oben (Codesign/Notarization).
## Kontosync
Der manuelle Sync über Dropbox lädt die neuesten
`.json`-Dateien (Legacy-`.tres` weiterhin) je Kür hoch bzw. herunter,
Konflikte bleiben als Kopien mit Zeitstempel erhalten. Jedes Gerät verbindet
das eigene Dropbox-Konto; Refresh-Tokens liegen in den App-Einstellungen
(`user://`), nicht im Repository. Details in `docs/sync.md` und
`docs/cloud-setup.md`.