SPB Git

Repository Public License

setup.md 6.8 KB

# Development setup

# Requirements

Tool Version used Notes
Xcode 27.2 iOS SDK 27.2
Swift 6.4 toolchain, Swift 6 language mode Strict concurrency is complete; the app target uses SWIFT_DEFAULT_ACTOR_ISOLATION: MainActor
XcodeGen any recent release brew install xcodegen; the .xcodeproj is generated and not committed
Deployment target iOS / iPadOS 18.0 The package also declares macOS 15 so the engines can be tested on the host
Python 3 with Pillow for Scripts/shots.py on iPad runs Used by the helper scripts only

There are no third-party dependencies to resolve.

# Getting started

bash
git clone https://git.spboucher.ai/orix-scan.git ORIXScan
cd ORIXScan
Scripts/build.sh generate      # writes ORIXScan.xcodeproj from project.yml
Scripts/build.sh kit           # engine and design-system tests on the Mac
Scripts/build.sh debug         # Debug build for the simulator

Open ORIXScan.xcodeproj in Xcode to run the app. The scanner needs a camera, so it is unavailable in the Simulator; the app says so and everything else works through imports or the demo documents (below).

# Scripts/build.sh

Command What it does
generate Runs xcodegen generate
kit swift test --no-parallel in Packages/ORIXKit (host Mac)
debug Debug build for the simulator named by ORIX_SIM
release Release build for the generic iOS Simulator destination
uitest [xcodebuild args] Boots the simulator, runs ORIXScanUITests, writes the result bundle to build/results/ and exports its attachments to build/shots/<simulator>/
all generate, kit, debug, uitest

Output is filtered to errors and test summaries; full logs are in build/logs/. ORIX_SIM selects the simulator (default ORIX iPhone).

# Simulators

The scripts use two dedicated simulators so that test runs do not collide with other projects on the same Mac:

bash
xcrun simctl create "ORIX iPhone" "iPhone 17 Pro"
xcrun simctl create "ORIX iPad" "iPad Pro 13-inch (M5)"

ORIX_SIM="ORIX iPad" Scripts/build.sh uitest

After a UI test run, Scripts/shots.py <simulator_dir> (for example ORIX_iPhone) copies the named screenshots to build/shots/<simulator_dir>/named/.

# Debug launch arguments

Compiled only in Debug builds (App/Sources/Debug/DemoContent.swift):

Argument Effect
-ORIXUITest YES Uses a separate store under the temporary directory instead of the user's library
-ORIXReset YES Empties that store and resets the related preferences first
-ORIXDemo YES When the library is empty, draws sample documents on the device and runs them through the real engines
bash
xcrun simctl launch "ORIX iPhone" ai.spboucher.orix.scan -ORIXUITest YES -ORIXReset YES -ORIXDemo YES

Release builds contain none of this.

# Localization

The app is written in English and localized to French (Canada) with string catalogs (App/Resources/Localizable.xcstrings, App/Resources/InfoPlist.xcstrings). After changing user-facing strings:

bash
Scripts/build.sh debug && Scripts/localize.py

Scripts/localize.py re-extracts the keys from the build's .stringsdata files with xcstringstool sync, merges Scripts/translations-fr.json, writes plural variants, and exits with an error if a key has no French translation. --no-sync merges the translations without re-extracting.

# Hygiene

bash
Scripts/check.sh

Checks that every first-party source file starts with the author header, and scans tracked and untracked (non-ignored) files for signing material, credentials and private addresses. It exits non-zero on any finding. .gitignore excludes build products, the generated project, and every kind of key, certificate, profile and .env file.

# Benchmarks

Scripts/benchmark.sh runs the OCR accuracy benchmark and the engine timings on the host Mac and writes JSON to docs/development/benchmarks/. These measure the engine code the app ships, on the Mac, not on an iPhone or iPad.

# Release scripts

Scripts/release.sh archive | export | validate | upload builds the Release archive, exports the IPA for App Store Connect, validates it and uploads it. The API key identifiers are read from the environment or from ~/.config/orix-scan/asc.env; nothing secret is in the repository, and upload refuses to run unless ORIX_UPLOAD_AUTHORIZED=yes is set. The App Store Connect metadata is in docs/release/app-store.md.

# Project layout

text
ORIXScan/
├── project.yml                      XcodeGen definition (app + UI tests)
├── App/
│   ├── Resources/                   Info.plist, PrivacyInfo.xcprivacy, string catalogs, Assets.xcassets
│   └── Sources/
│       ├── Core/                    ORIXScanApp, AppModel, Router, RootView, AppSettings, Naming, SharedViews
│       ├── Home/                    HomeView
│       ├── Library/                 LibraryView
│       ├── Document/                DocumentView, PageEditorView, PageOrganizerView, DocumentTextView, ExportSheet
│       ├── Capture/                 ScannerView
│       ├── Actions/                 ActionsView, WorkflowEditorView, WorkflowRunView
│       ├── Settings/                SettingsView
│       ├── Platform/                Intents, Support
│       └── Debug/                   DemoContent (Debug only)
├── Packages/ORIXKit/
│   ├── Package.swift
│   ├── Sources/
│   │   ├── ORIXDesign/              Tokens, Components, Haptics
│   │   └── ORIXKit/
│   │       ├── Model/               Document, Geometry
│   │       ├── Imaging/             PageRenderer, DocumentDetector, QualityAnalyzer
│   │       ├── OCR/                 OCREngine, OCRModel, ReadingOrder, TableExtractor, TextMetrics
│   │       ├── PDF/                 SearchablePDFBuilder, PDFTools
│   │       ├── Storage/             DocumentStore, DocumentProcessor, Library
│   │       └── Actions/             Workflow, WorkflowEngine
│   └── Tests/ORIXKitTests/          EngineTests, PipelineTests, LibraryTests, BenchmarkTests, Support
├── UITests/                         ORIXScanUITests
├── Scripts/                         build.sh, release.sh, benchmark.sh, check.sh, localize.py, shots.py, translations-fr.json, ExportOptions.plist
├── design/icon/                     concepts, master artwork, build.py, contact.py
└── docs/                            architecture, design, development, release, assets

Architecture: docs/architecture/overview.md.

Files main
Menu

Theme