145 lines
6.8 KiB
Markdown
145 lines
6.8 KiB
Markdown
# hello-platform
|
|
|
|
Minimal macOS and iOS app that validates the platform foundation: a "Hello,
|
|
platform!" title, a count label and an Increment button. All state lives in
|
|
Dialect; SwiftUI only renders the view model and sends 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
|
|
│ └── 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
|
|
```
|
|
|
|
`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.
|
|
Both platforms 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`.
|
|
|
|
## 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/other/other.swift` — 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) 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`, `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`.
|
|
|
|
## Pitfalls
|
|
|
|
- Change `dialect.yml`, not `dialect.swift`; retyping or reformatting the
|
|
generated file is pointless because every build overwrites it.
|
|
- 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.
|