Skip to content

Development Setup zh HK

Jump to bottom
ChiFungHillmanChan edited this page Sep 16, 2026 · 7 revisions

開發環境（Development Setup）

English version: Development-Setup

準備

  • macOS 14 (Sonoma) 或以上
  • Xcode 16+（Mac App Store 免費）——自帶 Swift 5.9 toolchain 同 Command Line Tools
  • Git 2.30+
  • 可選：gh CLI 用嚟出 release

唔需要 Apple Developer account。Ad-hoc signing 足夠做 local build 同分發 DMG。

Clone 同 build

git clone https://github.com/ChiFungHillmanChan/setpiece.git
cd setpiece

跑 core test suite（唔使 Xcode）

swift test

應該見到 Executed 157 tests, with 0 failures。V0.1 → V0.4 進度：26（V0.1）→ 92（V0.2）→ 116（V0.3）→ 157（V0.4）。

  • V0.1（26）： Slot、Layout、LayoutEngine.plan/apply、Geometry.rectsApproxEqual、nearestSlot、Plan、WindowRef（用 MockWindow）、AXPermission smoke。
  • V0.2（+66）： LayoutTemplate（slot math + sanitize）、CustomLayout/PresetSeeds/LayoutStore（Codable + persistence + seed semantics + block-save hotkey conflict）、HotkeyBinding（Carbon bridge + display string）、AnimationConfig/SettingsStore（default + clamp + observation）、FrameInterpolator（curve + endpoint 精確）、AnimationRunner（mock-clock interrupt / cancel / rapid retrigger）。
  • V0.3（+24）： DragSwapController 狀態機（pickup / preview / swap / cancel）、DragSwapConfig（threshold clamp + persistence）、drag-detection 用嘅 nearest-slot 數學。
  • V0.4（+41）： Workspace / WorkspaceTrigger / FocusModeReference Codable round-trip、WorkspaceSeeds（4 個 seed、stable UUID、⌘⌥1–4 default）、WorkspaceStore（CRUD + persistence + observation + 跨 store hotkey 衝突）、縱向 seed 透過 applyFutureSeeds migration、WeekdayMask OptionSet 編碼。

用 Xcode 開 app

open SceneApp/SceneApp.xcodeproj

揀 SceneApp scheme，⌘R。App 以 menu bar extra 身份行（冇 Dock icon）。

Command-line build

xcodebuild -project SceneApp/SceneApp.xcodeproj \
           -scheme SceneApp \
           -configuration Debug \
           CODE_SIGNING_REQUIRED=NO \
           build

CODE_SIGNING_REQUIRED=NO 避開 local keychain 偶爾出 errSecInternalComponent。唔影響行為。

Build 分發 DMG

./scripts/build-dmg.sh 0.4.0              # dist/Scene-0.4.0.dmg

出 Apple Silicon（arm64）ad-hoc signed app，打包埋 /Applications drop shortcut。macOS 14+ 嘅機絕大部分都係 Apple Silicon；要兼容 Intel，喺 build script 加返 ARCHS="arm64 x86_64"。完整版本升級 workflow 見 Release-Process-zh-HK。

開發期間嘅 Accessibility permission

Setpiece 要 AX access 先郁到其他 app 嘅窗口。macOS 將呢個權限綁住 app 嘅 code signature 同路徑：

  • 喺 Xcode 下跑嗰陣，app 每次 rebuild 都入 ~/Library/Developer/Xcode/DerivedData/...。macOS 將佢哋當同一身份處理，所以授權一次就 persist。
  • Debug / Release build 之間 switch 嗰陣，macOS 可能當佢哋係唔同 app，要再授權。
  • V0.4 TCC cdhash trap：ad-hoc signed 嘅 build，AX 授權綁住個 binary 嘅 cdhash。每次 rebuild 出新 cdhash，系統 toggle 睇落仲係 ON，但 AX API 其實 denied。症狀：rebuild 後 hotkey 靜靜噉唔 work。Fix：喺 System Settings → Privacy & Security → Accessibility 將 Setpiece entry OFF 完再 ON，或者跑 tccutil reset Accessibility com.hillman.SceneApp force 個 prompt 由頭嚟。
  • Rebuild 後 Setpiece 仲係唔識 permission，開 System Settings → Privacy & Security → Accessibility，將所有 SceneApp entry 移除，再重新授權。

Repo 結構

Package.swift                 SceneCore library manifest
Sources/SceneCore/            純 library（V0.4：AX/Animation/Display/Interaction/Layout/Settings/Workspace）
Tests/SceneCoreTests/         XCTest，157 個 case
SceneApp/SceneApp.xcodeproj   Xcode project
SceneApp/SceneApp/            app-shell code（V0.4：Settings/、Stores/、Animation/、Interaction/、Workspace/Triggers/、Resources/）
scripts/build-dmg.sh          DMG packager
docs/                         INSTALL.md、TESTING.md（V0.1–V0.4 smoke section）
.gitignore                    ignore 晒 build/、dist/、xcuserdata、AI tool 檔

.gitignore 排除 local AI-session 檔（CLAUDE.md、.claude/ 等），唔會 commit 入 repo。

常用 dev command

任務 Command
跑 core test swift test
跑一個 test swift test --filter LayoutEnginePlanTests
淨 compile 唔 run swift build
Xcode debug build xcodebuild … CODE_SIGNING_REQUIRED=NO build
Universal DMG ./scripts/build-dmg.sh <version>
清洗全部 rm -rf .build build dist SceneApp/build

Language English · 繁體中文

English

繁體中文（香港）

Clone this wiki locally