Files
__mahjong/docs/hello-platform.md
T
kornerr cf79e89dc4 Create hello-platform for iOS (#11)
Co-authored-by: Михаил Капелько <kornerr@gmail.com>
2026-11-01 07:19:54 +01:00

6.8 KiB

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

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

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):

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.