12 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.
Windows (WinUI)
ver-windows/ mirrors the Linux SwiftCrossUI target with WinUIBackend.
It shares the counter component, model, view, and generated Swift dialect via
relative symlinks. 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.