Files
__mahjong/docs/hello-platform.md
T
2026-11-05 16:45:09 +03:00

13 KiB
Raw Blame History

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.

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:

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.

Windows executable icon

res/AppIcon.res is a ready-made Windows resource containing six icon sizes (16–256px) from the shared res/AppIcon.png, with icon group ID 101. ver-windows/res/AppIcon.res links to it. No ICO or RC file is required by the Windows target, and the build does not compile resources.

step/buildWindows exports APP_RES_DIR as the absolute Git Bash ver-windows/res path derived from $SDIR/../ver-windows/res. The entry script obtains SDIR with pwd -P; no resource copy is needed. The manifest appends /AppIcon.res and passes it to the linker. Manual SwiftPM commands that evaluate the manifest also need APP_RES_DIR. Windows compilation and the live window/taskbar icon require verification on Windows; no Windows build was performed when this wiring was added.