11 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—HPComponentownsDialectController(HPContext), registers the generated effects and shoulds, publishessingletonand exposessetup()(hpSet(F.didSetup, true)).components/hp/hpVM.swift—HPVMis anObservableObjectwith@Published countTextand a weaksharedinstance.components/hp/mac/view/HPView.swift— SwiftUI view observingHPVM; the button dispatcheshpSet(F.didClickIncrement, true). It is platform-neutral, socomponents/hp/ios/view/HPView.swiftis a symlink back to it and bothsrc/hp/view/HPView.swiftlinks resolve to the same file.components/hp/android/— the Android mirror:hp.kt(sameHPComponent),hpVM.kt(HPVMwith a ComposemutableStateOf) andview/HPView.kt(ComposeColumn, headline, monospaced label, Increment button).components/other/other.swift/other.kt— helpers, includingotherSetupConsoleLogging(ctrl, "HP"), which prints every processed field to stderr asИГР HP k/v: '<field>'/'<value>'.
Startup flow
HPAppDelegatecreatesHPComponent(which setsHPComponent.singleton) and thenHPVM(which setsHPVM.shared).- The launch callback (
applicationDidFinishLaunchingon macOS,application(_:didFinishLaunchingWithOptions:)on iOS,HPActivityDelegate.setup()inMainActivity.onCreateon Android) registers console logging and callshp.setup(); the macOS one also activates the app. setup()queuesdidSetupin the controller.- The controller applies the changed field, runs every registered should in
order, and queues each new
recentFielda should returns. Finally it reports the context to callbacks: logging plus thecountTextoneliner, which copiesc.countTextintoHPVM.shared. HPViewre-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
didClickIncrementwhencount == 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.
- on
countText:- on
count→"Count: '<count>'"; - on
didLaunch→"Press the button to count".
- on
didLaunch: ondidSetupwhiledidLaunch == 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 generateddialect.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 servemust be running (withqwen2.5-coder:3bpulled) beforeprepare-androidorbuild-mac; otherwise generation aborts anddialect.ktis 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
recentFielddrives the next queue entry. - The generated oneliner and
hpSetforce-unwrapHPVM.shared/HPComponent.singleton; both must exist before dispatch. - Only one
dialect.swiftexists:ver-ios/src/dialect.swiftis a symlink to the macOS file, soprepare-iosregenerates the same source. The Kotlindialect.ktlives inver-androidand is generated from the samedialect.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.