259 lines
13 KiB
Markdown
259 lines
13 KiB
Markdown
# 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: '<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
|
||
|
||
```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.
|