SPB Git

Repository Public License

setup.md 14.4 KB

# 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

bash
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 directly

The core can be built and exercised without Xcode's project at all:

bash
cd Packages/ORIXMonitorCore
swift build
swift run orix-probe                 # one real reading of every collector
swift run orix-probe --capabilities  # plus the capability rows

# Project layout

text
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 documentation

Generated, 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, -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>.
  • The scripts and tests also pass -ApplePersistenceIgnoreState YES so macOS does not restore windows from a previous run.

Example — an isolated dark instance on the Memory page sampling every second:

bash
"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 YES

# Localisation 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:

  1. Compiler-extracted keys — Text("…"), Label("…"), LocalizedStringKey literals. Xcode writes them to .stringsdata files during a build (SWIFT_EMIT_LOC_STRINGS).
  2. 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.
  3. 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.

Steps after adding or changing user-visible text:

bash
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 exists

What 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.sh enforces 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; .gitignore and Scripts/check.sh both 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.sh stops at locally verified artifacts.
Files main
Menu

Theme