Files
__mahjong/docs/hello-platform.md
T
2026-11-03 22:43:16 +03:00

244 lines
12 KiB
Markdown

# hello-platform
Minimal macOS, iOS and Android app that validates the platform foundation: a
"Hello, platform!" title, a count label and an Increment button. All state lives
in Dialect; SwiftUI and Compose only render the view model and send one input
event.
## Layout
```text
hello/hello-platform/
├── dialect.yml Dialect v4 source: fields, oneliners, shoulds
├── util/
│ ├── build-mac generate → build → package
│ ├── run-mac run the packaged .app
│ ├── prepare-ios generate → xcodegen project
│ ├── prepare-android generate Kotlin dialect.kt
│ └── step/
│ ├── generateDialect sibling ../dialect generator on dialect.yml
│ ├── buildMac swift build in ver-mac/
│ ├── packageMac ver-mac/.build/hello-platform.app
│ ├── runMac launch Contents/MacOS/hello-platform
│ └── prepareIOS xcodegen in ver-ios/
├── ver-mac/
│ ├── Package.swift one executable target, path "src", macOS 13
│ ├── Info.plist org.opengamestudio.hello-platform, AppIcon
│ ├── res/AppIcon.icns copied into the bundle's Resources
│ ├── .build/ SPM output + packaged .app (git-ignored)
│ └── src/
│ ├── HPApp.swift @main WindowGroup → HPView
│ ├── HPAppDelegate.swift builds HPComponent + HPVM, logs, calls setup()
│ ├── dialect.swift generated by Dialect, never hand-edited
│ ├── hp/ relative symlinks into components/hp
│ │ ├── hp.swift
│ │ ├── hpVM.swift
│ │ └── view/HPView.swift → components/hp/mac/view/HPView.swift
│ └── other/other.swift relative symlink into components/other
└── ver-ios/
├── project.yml xcodegen: target hello-platform, iOS 15
├── Info.plist org.opengamestudio.hello-platform
├── Assets.xcassets/ AppIcon.appiconset/AppIcon.png → res/AppIcon.png
├── hello-platform.xcodeproj generated, git-ignored
├── .build/ xcodebuild DerivedData (git-ignored)
└── src/
├── HPApp.swift @main WindowGroup → HPView
├── HPAppDelegate.swift same HPComponent + HPVM + logging as macOS
├── dialect.swift symlink → ../../ver-mac/src/dialect.swift
├── hp/ same links as ver-mac, except view/HPView.swift
│ → components/hp/ios/view/HPView.swift
└── other/other.swift same symlink as the macOS tree
```
The Android target mirrors the same layout:
```text
hello/hello-platform/ver-android/
├── settings.gradle.kts rootProject "hello-platform", includes app
├── app/build.gradle.kts org.opengamestudio.helloplatform, Compose
├── gradle/ AGP 8.7.3, Kotlin 2.1.0, wrapper 9.3.1
├── local.properties sdk.dir, git-ignored
├── build/ Gradle output and APK (git-ignored)
└── app/src/main/
├── AndroidManifest.xml label hello-platform, Theme.MyApplication
├── res/ strings, theme, adaptive launcher icon
└── kotlin/org/opengamestudio/
├── MainActivity.kt Compose Box → HPView, edge-to-edge
├── HPActivityDelegate.kt HPComponent + logging, calls setup()
├── dialect.kt generated Kotlin, never hand-edited
├── hp/ relative symlinks into components/hp/android
│ ├── hp.kt
│ ├── hpVM.kt
│ └── view/HPView.kt → components/hp/android/view/HPView.kt
└── other/other.kt relative symlink into components/other
```
`components/` is the source of truth. The `src/hp` and `src/other` entries are
symlinks, so edit the real files under `components/` and keep the links intact.
macOS and iOS share one `dialect.swift` (the iOS one is a symlink to `ver-mac`),
one `HPView` body (the iOS `components/hp/ios/view/HPView.swift` links back to
the macOS view) and one `res/AppIcon.png`. Android has its own generated
`dialect.kt` and Compose view, with the same state and layout.
## Shared components
- `components/hp/hp.swift` — `HPComponent` owns `DialectController(HPContext)`,
registers the generated effects and shoulds, publishes `singleton` and exposes
`setup()` (`hpSet(F.didSetup, true)`).
- `components/hp/hpVM.swift` — `HPVM` is an `ObservableObject` with
`@Published countText` and a weak `shared` instance.
- `components/hp/mac/view/HPView.swift` — SwiftUI view observing `HPVM`; the
button dispatches `hpSet(F.didClickIncrement, true)`. It is platform-neutral,
so `components/hp/ios/view/HPView.swift` is a symlink back to it and both
`src/hp/view/HPView.swift` links resolve to the same file.
- `components/hp/android/` — the Android mirror: `hp.kt` (same `HPComponent`),
`hpVM.kt` (`HPVM` with a Compose `mutableStateOf`) and `view/HPView.kt`
(Compose `Column`, headline, monospaced label, Increment button).
- `components/other/other.swift` / `other.kt` — helpers, including
`otherSetupConsoleLogging(ctrl, "HP")`, which prints every processed field to
stderr as `ИГР HP k/v: '<field>'/'<value>'`.
## Startup flow
1. `HPAppDelegate` creates `HPComponent` (which sets `HPComponent.singleton`)
and then `HPVM` (which sets `HPVM.shared`).
2. The launch callback (`applicationDidFinishLaunching` on macOS,
`application(_:didFinishLaunchingWithOptions:)` on iOS,
`HPActivityDelegate.setup()` in `MainActivity.onCreate` on Android) registers
console logging and calls `hp.setup()`; the macOS one also activates the app.
3. `setup()` queues `didSetup` in the controller.
4. The controller applies the changed field, runs every registered should in
order, and queues each new `recentField` a should returns. Finally it reports
the context to callbacks: logging plus the `countText` oneliner, which copies
`c.countText` into `HPVM.shared`.
5. `HPView` re-renders from the published view model.
## Dialect rules (`dialect.yml`)
Fields: `count`, `countText`, `didClickIncrement`, `didLaunch`, `didSetup`.
Shoulds exist for `count`, `countText` and `didLaunch`; `didClickIncrement` and
`didSetup` are pure inputs.
- `count`:
- on `didClickIncrement` when `count == 7` → `count += 10`;
- on every `didClickIncrement` → `count += 1`.
The first matching rule returns, so the click made while the count is 7 adds
10 and jumps to 17.
- `countText`:
- on `count` → `"Count: '<count>'"`;
- on `didLaunch` → `"Press the button to count"`.
- `didLaunch`: on `didSetup` while `didLaunch == false` → `true`, once.
Oneliners: `countText` → `HPVM.shared!.countText = c.countText`.
## Build and run
```sh
cd hello/hello-platform
util/build-mac
util/run-mac
```
`generateDialect` expects the sibling `../dialect` checkout (so
`/Volumes/MOE/p/dialect` for this workspace). `build-mac` runs the steps in
order: regenerate `ver-mac/src/dialect.swift` and the Android `dialect.kt`,
`swift build`, then package `ver-mac/.build/debug/hello-platform`, `Info.plist`
and `res/` into `ver-mac/.build/hello-platform.app`.
iOS needs `xcodegen` (see README prerequisites):
```sh
cd hello/hello-platform
util/prepare-ios
xcodebuild -project ver-ios/hello-platform.xcodeproj \
-scheme hello-platform -sdk iphonesimulator \
-destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NO build
```
`prepare-ios` regenerates `dialect.swift` and then runs `xcodegen` in
`ver-ios/`. The generated `.xcodeproj` and `.build/` are git-ignored, so
re-run it after changing `project.yml` or `Info.plist`.
Android needs the SDK and a JDK; `prepare-android` writes the Kotlin dialect,
then Gradle builds the app:
```sh
cd hello/hello-platform
util/prepare-android
cd ver-android
JAVA_HOME="$HOME/.gradle/jdks/eclipse_adoptium-21-aarch64-os_x.2/jdk-21.0.7+6/Contents/Home" \
./gradlew assembleDebug
```
`ver-android/local.properties` points at `~/Library/Android/sdk` and is
git-ignored, so each checkout needs it once. Install the APK with
`adb install -r app/build/outputs/apk/debug/app-debug.apk` and start
`org.opengamestudio.helloplatform/org.opengamestudio.MainActivity`. Use JDK 21:
AGP 8.7.3 does not accept every newer JDK.
## Pitfalls
- Change `dialect.yml`, not the generated `dialect.swift` / `dialect.kt`;
retyping or reformatting them is pointless because every build overwrites
them.
- The Kotlin output is transpiled through the local LLM, so `ollama serve` must
be running (with `qwen2.5-coder:3b` pulled) before `prepare-android` or
`build-mac`; otherwise generation aborts and `dialect.kt` is left stale.
- Every should label (`1. Upon ...`) must end with a colon: the sibling generator
drops its last character (`../dialect/components/yml/ymlFun.swift`).
- A should function may change only one field; its returned `recentField` drives
the next queue entry.
- The generated oneliner and `hpSet` force-unwrap `HPVM.shared` /
`HPComponent.singleton`; both must exist before dispatch.
- Only one `dialect.swift` exists: `ver-ios/src/dialect.swift` is a symlink to
the macOS file, so `prepare-ios` regenerates the same source. The Kotlin
`dialect.kt` lives in `ver-android` and is generated from the same
`dialect.yml`.
## Linux launcher icon
`ver-linux` uses GtkBackend with application ID
`org.opengamestudio.hello-platform`. On Linux run
`hello/hello-platform/util/build-linux` from the repository root to build and install
the executable under `~/.local/bin`, the desktop entry under
`${XDG_DATA_HOME:-~/.local/share}/applications`, and the shared 1024px
`res/AppIcon.png` under the matching hicolor icon name. The launcher uses an
absolute executable path. Launch from the desktop application menu after
installation; GTK's application ID matches the desktop and icon names.
Desktop-entry installation uses `cp` and GNU `sed -i`; Python is not required.
The replacement supports spaces but assumes paths contain no sed replacement
metacharacters (`&`, `|`, backslashes) or desktop-entry quoting characters.
Requires the normal Swift/GTK build dependencies. Installation is per-user and
requires no root privileges.
The Linux build runs `step/buildLinux` followed by `step/packageLinux`.
The shared launcher template is `res/linux-app.desktop`; packaging copies it
and substitutes `%APP_NAME%`, `%APP_EXEC%` and `%APP_ID%`.
`util/run-linux` uses `gtk-launch org.opengamestudio.hello-platform` to launch
the installed desktop entry with its icon association. Run `util/build-linux`
first to install/update that entry and executable; `gtk-launch` must be available.
`packageLinux` is sourced with the target and display name, like `packageMac`;
it installs the executable, launcher and icon for the current user and refreshes
the desktop/icon caches. It requires GNU sed, gtk-update-icon-cache and
update-desktop-database. The standalone `install-linux` script has been replaced
by this packaging step.
## Windows (WinUI)
`ver-windows/` mirrors the Linux SwiftCrossUI target with `WinUIBackend`.
It shares the counter component and generated Swift dialect via
relative symlinks. It reuses the SwiftCrossUI model and view in `components/hp/linux`. Check out the repository with Git symlinks enabled on Windows
(Developer Mode or appropriate symlink permissions are needed).
With the Windows Swift toolchain, Windows SDK, and the Windows App SDK runtime
required by SwiftCrossUI's WinUI backend installed, run in Git Bash from `hello/hello-platform`:
```bash
util/build-windows
util/run-windows
```
The build uses the existing generated Swift dialect, like the Linux build.
The run script locates the existing debug executable without rebuilding it.