Files
__mahjong/docs/hello-platform.md
T
kornerr 45ca185094 Create hello-platform for Android (#12)
Co-authored-by: Михаил Капелько <kornerr@gmail.com>
2026-11-01 15:52:24 +01:00

9.4 KiB

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

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:

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

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):

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:

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.