SPB Git

Repository Public License

setup.md 14.4 KB 189 lines markdown

1<!--2ORIX Monitor3File: docs/development/setup.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Development setup910## Requirements1112| Requirement | Detail |13|---|---|14| Mac | Apple Silicon. The release build ships an `arm64` slice only; the app has never been run on an Intel Mac. |15| macOS | Deployment target 15.0 (`project.yml`, `Package.swift`). |16| Xcode | A version providing the Swift 6 language mode. The project was built and audited with Xcode 27.2 / Swift 6.4.2 on macOS 27.0 (26A5425a), MacBook Pro `Mac17,6`, Apple M5 Max. |17| XcodeGen | `xcodegen` on the `PATH`. The Xcode project is generated, not committed (`*.xcodeproj/` is in `.gitignore`). |18| `create-dmg` | Only for `Scripts/package.sh dmg`. |19| Python 3 | For `Scripts/localize.py`, and for the JSON post-processing in `Scripts/bench.sh` and `Scripts/notarize.sh`. |20| Signing | Debug builds use automatic signing. Release builds are configured for manual signing with a "Developer ID Application" identity and team `3YM54G49SN` (`project.yml`); building a release therefore needs that certificate, and notarisation needs an existing `notarytool` keychain profile. |2122No third-party Swift packages are used. The only package dependency is the local `Packages/ORIXMonitorCore`.2324## First build2526```bash27Scripts/build.sh generate     # xcodegen generate → ORIXMonitor.xcodeproj28Scripts/build.sh debug        # generate + Debug build into build/dd29open ORIXMonitor.xcodeproj    # or work in Xcode directly30```3132The core can be built and exercised without Xcode's project at all:3334```bash35cd Packages/ORIXMonitorCore36swift build37swift run orix-probe                 # one real reading of every collector38swift run orix-probe --capabilities  # plus the capability rows39```4041## Project layout4243```44ORIXMonitor/45├── project.yml                      XcodeGen definition (app target, UI-test target, scheme)46├── App/47│   ├── Sources/48│   │   ├── App/                     ORIXMonitorApp (scenes), MonitorModel (view model, LaunchOptions), AppSettings49│   │   ├── DesignSystem/            Tokens.swift, Components.swift50│   │   ├── Features/                One file per group of screens (Dashboard, Compute, System, Processes,51│   │   │                            History, Analysis, Reports, Settings, MenuBar)52│   │   └── Reporting/               PDFReportRenderer.swift53│   └── Resources/54│       ├── Assets.xcassets          AppIcon, AccentColor55│       └── Localizable.xcstrings    String catalogue (en source, fr-CA)56├── Packages/ORIXMonitorCore/57│   ├── Package.swift                Library ORIXMonitorCore, executable orix-probe, test target58│   ├── Sources/ORIXMonitorCore/59│   │   ├── Metrics/                 Metric.swift (MetricID, MetricCatalog, CounterMath, MonotonicClock)60│   │   ├── Collectors/              CPU, Memory, Disk, Network, Process, PowerThermalGPU61│   │   ├── Scheduler/               TelemetryEngine.swift62│   │   ├── Storage/                 TimeSeriesStore.swift63│   │   ├── Analysis/                AlertEngine.swift, IntelligenceEngine.swift64│   │   └── Reporting/               ReportGenerator.swift65│   ├── Sources/orix-probe/          main.swift66│   └── Tests/ORIXMonitorCoreTests/  MetricMathTests, StoreTests, AnalysisTests, LiveCollectorTests67├── UITests/                         ORIXMonitorUITests.swift (XCTest UI tests)68├── Scripts/                         Build, signing, packaging, benchmark, localisation, screenshots69│   └── tools/                       make-icon.swift, dmg-background.swift, winid.swift70├── design/icon/                     Icon concepts and the chosen 1024 px render71└── docs/                            This documentation72```7374Generated, ignored directories: `build/` (derived data in `build/dd` and `build/rel`, tools, notary logs, benchmark output), `dist/` (release app, DMG, ZIP, checksums), `.build/`, `ORIXMonitor.xcodeproj/`.7576### Build settings worth knowing (`project.yml`)7778| Setting | Value |79|---|---|80| Bundle identifier | `ai.spboucher.orix.monitor` (UI tests: `ai.spboucher.orix.monitor.uitests`) |81| `SWIFT_VERSION` / strict concurrency | `6.0` / `complete` |82| `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` | `1.0.0` / `1` |83| Hardened Runtime | enabled |84| `GENERATE_INFOPLIST_FILE` | yes — there is no hand-written Info.plist |85| Localisation | `SWIFT_EMIT_LOC_STRINGS`, `LOCALIZATION_PREFERS_STRING_CATALOGS`, development language `en` |86| Release | whole-module compilation, manual signing, `--timestamp`, no injected base entitlements |8788`project.yml` references no entitlements file.8990## Scripts9192All scripts `cd` to the repository root, so they can be run from anywhere.9394| Script | What it does |95|---|---|96| `Scripts/build.sh generate` | Runs `xcodegen generate`. |97| `Scripts/build.sh debug` | Generates the project and builds the Debug configuration through `Scripts/xb.sh`. Default when no argument is given. |98| `Scripts/build.sh test` | Runs `swift test` in `Packages/ORIXMonitorCore`, printing only errors, recorded issues and the summary line. |99| `Scripts/build.sh uitest` | Generates the project and runs `xcodebuild … test` for the `ORIXMonitor` scheme (the UI-test bundle), printing one line per test case and the result. |100| `Scripts/build.sh release` | Release build with `ARCHS=arm64 ONLY_ACTIVE_ARCH=NO` into `build/rel`, then copies the app to `dist/ORIX Monitor.app` and prints its version, build and architectures. |101| `Scripts/build.sh all` | `test`, then `debug`, then `uitest`. |102| `Scripts/xb.sh [Config] [xcodebuild actions…]` | Runs `xcodebuild` for the app scheme with derived data in `build/dd` and prints only errors, warnings and the result line. |103| `Scripts/sign.sh` | **Verifies** (does not perform) the signature of `dist/ORIX Monitor.app`: Developer ID Application authority, Hardened Runtime flag, secure timestamp, bundle identifier, `codesign --verify --deep --strict`, and absence of the `get-task-allow` entitlement. Signing itself is done by Xcode during the Release build. |104| `Scripts/notarize.sh <artifact> <name>` | Submits an `.app` (zipped first), `.dmg` or `.zip` to Apple's notary service with an **existing** keychain profile (`NOTARY_PROFILE`, default `MacLustr-Notarize`), waits, saves the JSON result and the log under `build/notary/`, and staples and validates on acceptance. It never creates, prints or changes credentials, and prints "notarized" only when the service answered `Accepted`. |105| `Scripts/package.sh zip\|dmg\|checksums\|all` | From `dist/ORIX Monitor.app`: builds `dist/ORIX-Monitor-<version>.zip`; builds a drag-to-install `dist/ORIX-Monitor-<version>.dmg` with `create-dmg` and a background drawn by `Scripts/tools/dmg-background.swift`, then signs and verifies the DMG with the app's own Developer ID identity; writes `dist/SHA256SUMS.txt`. Refuses to run if the app is not Developer ID-signed. |106| `Scripts/release.sh` | The full local sequence: core tests → release build → signature verification → notarise and staple the app → ZIP → DMG → notarise and staple the DMG → checksums → Gatekeeper assessment with `spctl`. **Publishes nothing.** |107| `Scripts/bench.sh [seconds=120] [section=overview] [interval=2]` | Runs an isolated instance of the release app and measures its CPU, memory and storage overhead. See [performance](performance.md). |108| `Scripts/check.sh` | Repository hygiene: every first-party `.swift`, `.sh`, `.py`, `.yml` file and `.gitignore` must carry the author header; scans tracked and untracked-unignored files for secret-like patterns; rejects certificate, key, provisioning, `.sqlite` and `.env` files. Exits non-zero on any finding. |109| `Scripts/localize.py [--missing] [--unused]` | Rebuilds the string catalogue. See below. |110| `Scripts/shot.sh <out.png> <section> [dark\|light] [seconds] [extra args…]` | Launches an isolated instance on one section with the privacy mask on, waits for real samples, captures its window by window ID with `screencapture -l`, then quits it. Uses `ORIX_APP` (default: the Debug build), `ORIX_DATA` and `ORIX_FRAME`. |111| `Scripts/tools/make-icon.swift` | Draws the five icon concepts and exports the chosen one at every size. See [icon design](../design/icon-design.md). |112| `Scripts/tools/dmg-background.swift` | Draws the 660 × 440 pt disk-image background at 2×. |113| `Scripts/tools/winid.swift` | Prints the on-screen window IDs (largest first) of a process, for `screencapture -l`. |114115Scripts that launch the app (`bench.sh`, `shot.sh`) start it by executable path and end it **by PID**, never by bundle identifier, so a copy the developer is actually using is not touched.116117## Launch arguments118119`LaunchOptions` (in `MonitorModel.swift`) reads these from the argument domain of `UserDefaults`, so each is passed as `-Name value`.120121| Argument | Value | Effect |122|---|---|---|123| `-ORIXUITest` | `YES` | Test mode. Preferences are read from a separate defaults suite, `ai.spboucher.orix.monitor.uitest`, which is **wiped at launch**, so the instance starts from factory settings and never touches real preferences. Adds an invisible `page.<section>` accessibility marker to the detail pane. The Processes page opens on the short "Apps" list instead of "My processes". |124| `-ORIXDataDir` | directory path | The history database is `<dir>/telemetry.sqlite` instead of `~/Library/Application Support/ORIX Monitor/telemetry.sqlite`. |125| `-ORIXSection` | an `AppSection` raw value: `overview`, `cpu`, `gpu`, `memory`, `disk`, `network`, `processes`, `power`, `thermal`, `history`, `insights`, `alerts`, `reports` | The page shown at launch. |126| `-ORIXAppearance` | `system`, `light`, `dark` | Sets the appearance preference. |127| `-ORIXInterval` | seconds (minimum 0.5) | Fixed sampling: sets `interval` and `backgroundInterval` to the value, `processInterval` to twice the value, and turns the battery saver off, so charts fill quickly whatever the power source. |128| `-ORIXPrivacy` | `YES` | Turns the privacy mask on (addresses, host and user names shown as "•••"). |129| `-ORIXPreset` | a dashboard layout name, case-insensitive (`Overview`, `Performance`, `Compact`, or a saved layout) | Selects that dashboard. |130| `-AppleLanguages "(fr-CA)" -AppleLocale fr_CA` | standard macOS arguments | Run the app in another language for one launch, without changing any preference. |131| `-ORIXResizeTo` | `WIDTHxHEIGHT`, e.g. `900x600` | Three seconds after launch, resizes the main window to that size (keeping its top edge), so tests can check that the layout reflows. |132133Cautions:134135- `-ORIXInterval`, `-ORIXAppearance`, `-ORIXPrivacy` and `-ORIXPreset` change settings, so `LaunchOptions` honours them **only together with `-ORIXUITest YES`**. Test instances keep their settings in a separate defaults suite (`ai.spboucher.orix.monitor.uitest`) that is reset at each launch; these arguments can never alter real preferences. Also available to test instances: `-ORIXResizeTo WxH`, `-ORIXOpenSettings YES`, `-ORIXShowMenuPanel YES`, `-ORIXExportMenuBar <dir>`.136- The scripts and tests also pass `-ApplePersistenceIgnoreState YES` so macOS does not restore windows from a previous run.137138Example — an isolated dark instance on the Memory page sampling every second:139140```bash141"build/dd/Build/Products/Debug/ORIX Monitor.app/Contents/MacOS/ORIX Monitor" \142  -ORIXUITest YES -ORIXDataDir /tmp/orix-dev -ORIXSection memory \143  -ORIXAppearance dark -ORIXInterval 1 -ApplePersistenceIgnoreState YES144```145146## Localisation workflow147148English is the source language; Canadian French (`fr-CA`) is the translation.149150| File | Role |151|---|---|152| `App/Resources/Localizable.xcstrings` | The string catalogue shipped in the app. **Generated** by `Scripts/localize.py`; do not edit by hand. |153| `Scripts/translations-fr-CA.json` | The source of truth for French: a flat JSON object mapping each English key to its French value. |154155Strings reach the catalogue from three places:1561571. **Compiler-extracted keys** — `Text("…")`, `Label("…")`, `LocalizedStringKey` literals. Xcode writes them to `.stringsdata` files during a build (`SWIFT_EMIT_LOC_STRINGS`).1582. **Run-time keys in the app** — English strings passed to `L("…")` (a `String(localized:)` lookup defined in `Tokens.swift`), found by a regular expression over `App/Sources/**/*.swift` and `ORIXMonitorCore/Reporting/*.swift`.1593. **Strings produced by the core** — metric names and methods, capability names, categories and notes, report titles, and enum raw values used as labels. `orix-probe --strings` prints them as JSON, and the script adds them. A few literal keys (dashboard preset names, battery-health words) are added explicitly.160161Steps after adding or changing user-visible text:162163```bash164Scripts/xb.sh                         # build, so the compiler emits .stringsdata165Scripts/localize.py --missing         # rebuild the catalogue; write build/missing-fr.json166# add the missing keys to Scripts/translations-fr-CA.json167Scripts/localize.py                   # rebuild again; the summary line should report 0 missing168Scripts/localize.py --unused          # optional: list translations whose key no longer exists169```170171What the script does: creates an empty catalogue, runs `xcrun xcstringstool sync` with the `.stringsdata` files, adds the run-time keys, marks keys containing no two consecutive letters (pure symbols or format specifiers) as `shouldTranslate: false`, attaches the French value to every key found in the JSON file, and prints a summary (`N keys, N with French, N missing, N unused translations`).172173The core stays free of app resources: `ReportGenerator` takes a `Localizer` closure, and the app passes `L`.174175To run the app in French without changing the system language, pass the standard macOS arguments `-AppleLanguages "(fr-CA)" -AppleLocale fr_CA` (`Scripts/shot.sh` does it through `ORIX_LANG` / `ORIX_LOCALE`).176177## Conventions178179- Every first-party source file starts with the ORIX Monitor header (file path, description, author, contact). `Scripts/check.sh` enforces it.180- Pure arithmetic lives in caseless enums (`…Math`) separate from I/O so it can be unit-tested.181- No credentials, certificates, databases or machine reports in the repository; `.gitignore` and `Scripts/check.sh` both guard this.182183## Not provided184185- No continuous-integration configuration is present in the repository.186- No Swift Package Manager manifest for the app itself: the app builds only through the generated Xcode project.187- No linter or formatter configuration.188- No script publishes a release; `Scripts/release.sh` stops at locally verified artifacts.189
Files main
Menu

Theme