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
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 simulatorOpen 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:
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 uitestAfter 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 |
xcrun simctl launch "ORIX iPhone" ai.spboucher.orix.scan -ORIXUITest YES -ORIXReset YES -ORIXDemo YESRelease 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:
Scripts/build.sh debug && Scripts/localize.pyScripts/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
Scripts/check.shChecks 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
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, assetsArchitecture: docs/architecture/overview.md.