Development setup
Requirements
| Requirement | Detail |
|---|---|
| Mac | Apple Silicon. The release build ships an arm64 slice only; the app has never been run on an Intel Mac. |
| macOS | Deployment target 15.0 (project.yml, Package.swift). |
| 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. |
| XcodeGen | xcodegen on the PATH. The Xcode project is generated, not committed (*.xcodeproj/ is in .gitignore). |
create-dmg |
Only for Scripts/package.sh dmg. |
| Python 3 | For Scripts/localize.py, and for the JSON post-processing in Scripts/bench.sh and Scripts/notarize.sh. |
| 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. |
No third-party Swift packages are used. The only package dependency is the local Packages/ORIXMonitorCore.
First build
Scripts/build.sh generate # xcodegen generate → ORIXMonitor.xcodeproj
Scripts/build.sh debug # generate + Debug build into build/dd
open ORIXMonitor.xcodeproj # or work in Xcode directlyThe core can be built and exercised without Xcode's project at all:
cd Packages/ORIXMonitorCore
swift build
swift run orix-probe # one real reading of every collector
swift run orix-probe --capabilities # plus the capability rowsProject layout
ORIXMonitor/
├── project.yml XcodeGen definition (app target, UI-test target, scheme)
├── App/
│ ├── Sources/
│ │ ├── App/ ORIXMonitorApp (scenes), MonitorModel (view model, LaunchOptions), AppSettings
│ │ ├── DesignSystem/ Tokens.swift, Components.swift
│ │ ├── Features/ One file per group of screens (Dashboard, Compute, System, Processes,
│ │ │ History, Analysis, Reports, Settings, MenuBar)
│ │ └── Reporting/ PDFReportRenderer.swift
│ └── Resources/
│ ├── Assets.xcassets AppIcon, AccentColor
│ └── Localizable.xcstrings String catalogue (en source, fr-CA)
├── Packages/ORIXMonitorCore/
│ ├── Package.swift Library ORIXMonitorCore, executable orix-probe, test target
│ ├── Sources/ORIXMonitorCore/
│ │ ├── Metrics/ Metric.swift (MetricID, MetricCatalog, CounterMath, MonotonicClock)
│ │ ├── Collectors/ CPU, Memory, Disk, Network, Process, PowerThermalGPU
│ │ ├── Scheduler/ TelemetryEngine.swift
│ │ ├── Storage/ TimeSeriesStore.swift
│ │ ├── Analysis/ AlertEngine.swift, IntelligenceEngine.swift
│ │ └── Reporting/ ReportGenerator.swift
│ ├── Sources/orix-probe/ main.swift
│ └── Tests/ORIXMonitorCoreTests/ MetricMathTests, StoreTests, AnalysisTests, LiveCollectorTests
├── UITests/ ORIXMonitorUITests.swift (XCTest UI tests)
├── Scripts/ Build, signing, packaging, benchmark, localisation, screenshots
│ └── tools/ make-icon.swift, dmg-background.swift, winid.swift
├── design/icon/ Icon concepts and the chosen 1024 px render
└── docs/ This documentationGenerated, 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/.
Build settings worth knowing (project.yml)
| Setting | Value |
|---|---|
| Bundle identifier | ai.spboucher.orix.monitor (UI tests: ai.spboucher.orix.monitor.uitests) |
SWIFT_VERSION / strict concurrency |
6.0 / complete |
MARKETING_VERSION / CURRENT_PROJECT_VERSION |
1.0.0 / 1 |
| Hardened Runtime | enabled |
GENERATE_INFOPLIST_FILE |
yes — there is no hand-written Info.plist |
| Localisation | SWIFT_EMIT_LOC_STRINGS, LOCALIZATION_PREFERS_STRING_CATALOGS, development language en |
| Release | whole-module compilation, manual signing, --timestamp, no injected base entitlements |
project.yml references no entitlements file.
Scripts
All scripts cd to the repository root, so they can be run from anywhere.
| Script | What it does |
|---|---|
Scripts/build.sh generate |
Runs xcodegen generate. |
Scripts/build.sh debug |
Generates the project and builds the Debug configuration through Scripts/xb.sh. Default when no argument is given. |
Scripts/build.sh test |
Runs swift test in Packages/ORIXMonitorCore, printing only errors, recorded issues and the summary line. |
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. |
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. |
Scripts/build.sh all |
test, then debug, then uitest. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Scripts/localize.py [--missing] [--unused] |
Rebuilds the string catalogue. See below. |
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. |
Scripts/tools/make-icon.swift |
Draws the five icon concepts and exports the chosen one at every size. See icon design. |
Scripts/tools/dmg-background.swift |
Draws the 660 × 440 pt disk-image background at 2×. |
Scripts/tools/winid.swift |
Prints the on-screen window IDs (largest first) of a process, for screencapture -l. |
Scripts 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.
Launch arguments
LaunchOptions (in MonitorModel.swift) reads these from the argument domain of UserDefaults, so each is passed as -Name value.
| Argument | Value | Effect |
|---|---|---|
-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". |
-ORIXDataDir |
directory path | The history database is <dir>/telemetry.sqlite instead of ~/Library/Application Support/ORIX Monitor/telemetry.sqlite. |
-ORIXSection |
an AppSection raw value: overview, cpu, gpu, memory, disk, network, processes, power, thermal, history, insights, alerts, reports |
The page shown at launch. |
-ORIXAppearance |
system, light, dark |
Sets the appearance preference. |
-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. |
-ORIXPrivacy |
YES |
Turns the privacy mask on (addresses, host and user names shown as "•••"). |
-ORIXPreset |
a dashboard layout name, case-insensitive (Overview, Performance, Compact, or a saved layout) |
Selects that dashboard. |
-AppleLanguages "(fr-CA)" -AppleLocale fr_CA |
standard macOS arguments | Run the app in another language for one launch, without changing any preference. |
-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. |
Cautions:
-ORIXInterval,-ORIXAppearance,-ORIXPrivacyand-ORIXPresetchange settings, soLaunchOptionshonours 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>.- The scripts and tests also pass
-ApplePersistenceIgnoreState YESso macOS does not restore windows from a previous run.
Example — an isolated dark instance on the Memory page sampling every second:
"build/dd/Build/Products/Debug/ORIX Monitor.app/Contents/MacOS/ORIX Monitor" \
-ORIXUITest YES -ORIXDataDir /tmp/orix-dev -ORIXSection memory \
-ORIXAppearance dark -ORIXInterval 1 -ApplePersistenceIgnoreState YESLocalisation workflow
English is the source language; Canadian French (fr-CA) is the translation.
| File | Role |
|---|---|
App/Resources/Localizable.xcstrings |
The string catalogue shipped in the app. Generated by Scripts/localize.py; do not edit by hand. |
Scripts/translations-fr-CA.json |
The source of truth for French: a flat JSON object mapping each English key to its French value. |
Strings reach the catalogue from three places:
- Compiler-extracted keys —
Text("…"),Label("…"),LocalizedStringKeyliterals. Xcode writes them to.stringsdatafiles during a build (SWIFT_EMIT_LOC_STRINGS). - Run-time keys in the app — English strings passed to
L("…")(aString(localized:)lookup defined inTokens.swift), found by a regular expression overApp/Sources/**/*.swiftandORIXMonitorCore/Reporting/*.swift. - 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 --stringsprints them as JSON, and the script adds them. A few literal keys (dashboard preset names, battery-health words) are added explicitly.
Steps after adding or changing user-visible text:
Scripts/xb.sh # build, so the compiler emits .stringsdata
Scripts/localize.py --missing # rebuild the catalogue; write build/missing-fr.json
# add the missing keys to Scripts/translations-fr-CA.json
Scripts/localize.py # rebuild again; the summary line should report 0 missing
Scripts/localize.py --unused # optional: list translations whose key no longer existsWhat 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).
The core stays free of app resources: ReportGenerator takes a Localizer closure, and the app passes L.
To 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).
Conventions
- Every first-party source file starts with the ORIX Monitor header (file path, description, author, contact).
Scripts/check.shenforces it. - Pure arithmetic lives in caseless enums (
…Math) separate from I/O so it can be unit-tested. - No credentials, certificates, databases or machine reports in the repository;
.gitignoreandScripts/check.shboth guard this.
Not provided
- No continuous-integration configuration is present in the repository.
- No Swift Package Manager manifest for the app itself: the app builds only through the generated Xcode project.
- No linter or formatter configuration.
- No script publishes a release;
Scripts/release.shstops at locally verified artifacts.