# 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. ## 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. ### 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.