SPB Git

Repository Public MIT

setup.md 11.7 KB 216 lines markdown

1<!--2ORIX Calc3File: docs/development/setup.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Development setup89ORIX Calc is a universal iOS / iPadOS app. The Xcode project is generated; the source of truth is `project.yml` plus the10local Swift packages under `Packages/`. The architecture is described in11[`docs/architecture/overview.md`](../architecture/overview.md); how to run the tests is in [`testing.md`](testing.md).1213## Requirements1415| Item | Value | Read from |16|---|---|---|17| Swift tools version | 6.2 (`// swift-tools-version: 6.2`) | every `Package.swift` |18| Swift language mode | 6, strict concurrency `complete` | `swiftLanguageModes: [.v6]`; `SWIFT_VERSION: "6.0"`, `SWIFT_STRICT_CONCURRENCY: complete` in `project.yml` |19| iOS deployment target | 26.0 | `project.yml` (`deploymentTarget`), `.iOS(.v26)` in the packages |20| macOS (command-line package builds and tests) | 15 or later | `.macOS(.v15)` in the packages |21| Device families | iPhone and iPad (`TARGETED_DEVICE_FAMILY: "1,2"`); Mac Catalyst, "Designed for iPad" on Mac and visionOS are off | `project.yml` |22| XcodeGen | on the `PATH` as `xcodegen` | `Scripts/generate.sh` |23| Python 3 | used by `Scripts/generate.sh`, `Scripts/asc.py` and the reference generators | scripts |24| Bundle identifier | `ai.spboucher.orix.calc`, version 1.0.0 (1) | `project.yml` |2526The engine `VALIDATION.md` records were produced with Swift 6.4.2 on macOS 27. An Xcode release that provides the iOS 2627SDK and a Swift 6.2 or later toolchain is required; the repository does not pin an Xcode version.2829### Third-party dependencies3031Two, both pinned to exact versions and resolved in `Packages/ORIXExpression/Package.resolved`:3233| Package | Version | Licence | Used by |34|---|---|---|---|35| [BigInt](https://github.com/attaswift/BigInt) (attaswift) | 5.7.0 (exact) | MIT | `ORIXExpression`, `ORIXSymbolic` |36| [Swift Numerics](https://github.com/apple/swift-numerics) (Apple) | 1.1.1 (exact) | Apache 2.0 | `ORIXExpression` (`ComplexModule`, `RealModule`) |3738System frameworks, as listed in the app's Settings screen (`App/Sources/SettingsView.swift`): SwiftUI, SwiftData,39Swift Charts, Accelerate (LAPACK, compiled with `ACCELERATE_NEW_LAPACK`), Vision, App Intents, CryptoKit. Everything else40is first-party code in this repository.4142## Repository layout4344```45ORIXCalc/46├── project.yml                  XcodeGen definition: app, unit-test and UI-test targets, one scheme47├── App/48│   ├── Sources/                 App target: entry point, adaptive shell, history, settings, intents, Math Camera view, FeatureRegistry49│   └── Resources/               Info.plist, asset catalogue, privacy manifest50├── Packages/51│   ├── ORIXNumerics/            Explanation, VerificationReport, root finding, quadrature, differentiation52│   ├── ORIXExpression/          Typed values, exact arithmetic, parser, evaluator, formatter, RPN53│   ├── ORIXFinancial/           TVM, cash flows, loans, bonds, investment analysis, options, sensitivity54│   ├── ORIXStatistics/          Special functions, descriptive statistics, distributions, inference, regression, simulation55│   ├── ORIXUnits/               Unit catalogue, exact conversion, rate conventions, currency tables56│   ├── ORIXSymbolic/            Simplify, polynomials, calculus, solving, limits, series, optimisation, ODEs57│   ├── ORIXGraph/               Graph computation: sampling, analysis, implicit curves, 3D meshes (no UI)58│   ├── ORIXWorkspace/           Notebook document model, dependency graph, recalculation, exports, .orixcalc format59│   ├── ORIXMathCamera/          Vision text recognition and normalisation into parseable input60│   ├── ORIXUI/                  Design tokens and components, AppModel (shared session), SwiftData store61│   ├── ORIXFeatureCalculator/   Standard and Scientific environments62│   ├── ORIXFeatureFinancial/    Financial environment63│   ├── ORIXFeatureGraph/        Graph environment (2D and 3D)64│   ├── ORIXFeatureMath/         Math environment65│   ├── ORIXFeatureStatistics/   Statistics environment66│   ├── ORIXFeatureConvert/      Convert environment67│   └── ORIXFeatureWorkspace/    Workspace environment68├── Tests/                       App unit tests (ORIXCalcTests)69├── UITests/                     XCUITests (ORIXCalcUITests)70├── Benchmarks/                  Command-line benchmark package (orix-bench)71├── Scripts/                     generate, test-all, shot, screenshots, release, secret-scan, asc.py72└── docs/                        architecture, mathematics, development, design, release, research, assets, screenshots73```7475Ignored by git (`.gitignore`): `.build/`, `build/`, `dist/`, `DerivedData/`, `*.xcodeproj/`, signing material and `.env`76files. The Xcode project is therefore never committed; generate it.7778Engine packages that carry references also have `API.md`, `VALIDATION.md` and a `Reference/` directory (Financial,79Statistics, Units, Symbolic; Graph has the two documents and no `Reference/`).8081## Generate the project8283```sh84Scripts/generate.sh85```8687The script rewrites `project.yml` into a temporary spec and runs `xcodegen generate`:8889- A package listed in `project.yml` whose `Package.swift` is absent is left out of the project, so the app still builds90  while a package is missing.91- `ORIX_EXCLUDE="ORIXGraph ORIXFeatureGraph" Scripts/generate.sh` leaves packages out on purpose.92- The placeholder `__ORIX_FEATURE_FLAGS__` in `SWIFT_ACTIVE_COMPILATION_CONDITIONS` is replaced by one flag per feature93  package that is present: `ORIX_HAS_FINANCIAL`, `ORIX_HAS_CONVERT`, `ORIX_HAS_GRAPH`, `ORIX_HAS_MATH`,94  `ORIX_HAS_STATISTICS`, `ORIX_HAS_WORKSPACE`. `App/Sources/FeatureRegistry.swift` imports each feature under its flag and95  shows `UnavailableFeature` for an environment that was left out.9697`ORIXFeatureCalculator` is always required (the app imports it unconditionally).9899## Simulators100101The scripts address two dedicated simulators by name: **"ORIXCalc iPhone"** (`Scripts/test-all.sh`, `Scripts/shot.sh`)102and **"ORIXCalc iPad"** (`Scripts/shot.sh ipad`). Create them once, choosing a device type and a runtime that are103installed (iOS 26 or later):104105```sh106xcrun simctl list devicetypes          # pick an iPhone and an iPad identifier107xcrun simctl list runtimes             # pick an iOS runtime identifier108xcrun simctl create "ORIXCalc iPhone" <iphone-devicetype-id> <ios-runtime-id>109xcrun simctl create "ORIXCalc iPad"   <ipad-devicetype-id>   <ios-runtime-id>110```111112The repository does not prescribe particular device models.113114## Build and run115116```sh117Scripts/generate.sh118xcodebuild -project ORIXCalc.xcodeproj -scheme ORIXCalc -configuration Debug \119  -destination "platform=iOS Simulator,name=ORIXCalc iPhone" -derivedDataPath build/DerivedData build120```121122`Scripts/shot.sh` expects the Debug product at `build/DerivedData/Build/Products/Debug-iphonesimulator/ORIXCalc.app`,123which is where the command above puts it. To launch it and capture the screen:124125```sh126Scripts/shot.sh iphone /tmp/standard.png -ORIXMode standard -ORIXExpression "1234.5*(3+4)"127```128129`shot.sh` boots the simulator, overrides the status bar, installs the app, launches it with `-ORIXInMemory 1` plus the130arguments given, waits `ORIX_SHOT_DELAY` seconds (default 4) and saves a screenshot. `Scripts/screenshots.sh` uses it to131regenerate `docs/screenshots/` from the running app. Alternatively open `ORIXCalc.xcodeproj` in Xcode and run the132`ORIXCalc` scheme.133134Engine packages build and test from the command line without Xcode's project: `cd Packages/ORIXFinancial && swift build`.135136## Launch arguments137138Read by `LaunchOptions` in `App/Sources/ORIXCalcApp.swift`. They exist for UI tests and for capturing real screenshots;139they never change calculations.140141| Argument | Value | Effect |142|---|---|---|143| `-ORIXMode` | `standard`, `scientific`, `financial`, `graph`, `math`, `statistics`, `convert`, `workspace` | Opens that environment (`CalcMode` raw value) |144| `-ORIXSection` | a section name, for example `tvm`, `bond` (Financial) | Passed to the screen of the environment named by `-ORIXMode` (as `category` for Convert) |145| `-ORIXDemo` | `1` | Passes `demo: true` to the feature screens; used by `Scripts/screenshots.sh` |146| `-ORIXInMemory` | `1` | In-memory store and an ephemeral `UserDefaults` suite; nothing is persisted |147| `-ORIXCompanion` | `1` | Shows the companion calculator of the iPad shell |148| `-ORIXAppearance` | `system`, `light`, `dark` | Overrides the appearance preference |149| `-ORIXExpression` | an expression | Sets it in the calculator and evaluates it at launch |150151## File-header convention152153Every first-party file starts with a header carrying the product name, the path from the repository root, a one-line154description, the author and the contact.155156Swift (`Package.swift` keeps `// swift-tools-version` on the first line, above the header):157158```swift159// ORIX Calc160// File: Packages/ORIXFinancial/Sources/ORIXFinancial/TVM.swift161// Description: …162//163// Author: Simon-Pierre Boucher164// Contact: contact@spboucher.ai165```166167Shell, Python and YAML use the same lines with `#` (after the shebang). Markdown uses an HTML comment:168169```md170<!--171ORIX Calc172File: docs/development/setup.md173Author: Simon-Pierre Boucher174Contact: contact@spboucher.ai175-->176```177178## Adding an environment179180Feature packages do not depend on each other; each depends on `ORIXUI` and on its engine.1811821. **Package.** Create `Packages/ORIXFeature<Name>/` with a `Package.swift` modelled on an existing feature package183   (tools 6.2, `.iOS(.v26)`, `.macOS(.v15)`, Swift 6 language mode, dependencies `../ORIXUI` + the engine, one library184   target, one test target).1852. **Screen contract.** Expose one public SwiftUI view named `<Name>Screen` that reads the shared session from the186   environment and takes its launch parameters in the initialiser:187188   ```swift189   public struct FinancialScreen: View {190       @Environment(AppModel.self) private var model191       public init(section: String? = nil, demo: Bool = false) { … }192   }193   ```194195   Cross-environment actions go through the `AppModel` mailboxes or the `graphPreview` environment seam, never through an196   import of another feature package.1973. **Mode.** Add the case to `CalcMode` (`Packages/ORIXUI/Sources/ORIXUI/Core/CalcMode.swift`: title, symbol, tint,198   tagline; the ⌘-number shortcut follows the case order).1994. **`project.yml`.** Add the package under `packages:` and under the `ORIXCalc` target's `dependencies:`.2005. **`Scripts/generate.sh`.** Add the name to the `features` list so that an `ORIX_HAS_<NAME>` flag is emitted.2016. **`App/Sources/FeatureRegistry.swift`.** Import the package under `#if ORIX_HAS_<NAME>`, add the `case` to202   `screen(for:calculator:options:)` with the `UnavailableFeature` fallback, and register any native functions the203   environment contributes to the expression engine in `registerNatives`.2047. **Tests.** Add the package to the `features` loop of `Scripts/test-all.sh`.205206## Other scripts207208| Script | Purpose |209|---|---|210| `Scripts/test-all.sh [engines\|features\|app\|all]` | Runs the test suites and writes `build/test-summary.txt` |211| `Scripts/screenshots.sh` | Captures the running app into `docs/screenshots/` |212| `Scripts/release.sh archive \| export \| validate \| upload` | Release archive, App Store Connect export, validation and, only on explicit request, upload; see [`docs/release/testflight.md`](../release/testflight.md) |213| `Scripts/secret-scan.sh` | Scans tracked and staged files for credentials, private material and build products; exits non-zero on a finding |214| `Scripts/asc.py` | Minimal App Store Connect API client |215| `cd Benchmarks && swift run -c release orix-bench` | Engine benchmark; results in [`benchmark-results.md`](benchmark-results.md) |216
Files main
Menu

Theme