# 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: ''/''`. ## 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: ''"`; - 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.