SPB Git

Repository Public MIT

setup.md 11.7 KB

# Development setup

ORIX Calc is a universal iOS / iPadOS app. The Xcode project is generated; the source of truth is project.yml plus the local Swift packages under Packages/. The architecture is described in docs/architecture/overview.md; how to run the tests is in testing.md.

# Requirements

Item Value Read from
Swift tools version 6.2 (// swift-tools-version: 6.2) every Package.swift
Swift language mode 6, strict concurrency complete swiftLanguageModes: [.v6]; SWIFT_VERSION: "6.0", SWIFT_STRICT_CONCURRENCY: complete in project.yml
iOS deployment target 26.0 project.yml (deploymentTarget), .iOS(.v26) in the packages
macOS (command-line package builds and tests) 15 or later .macOS(.v15) in the packages
Device families iPhone and iPad (TARGETED_DEVICE_FAMILY: "1,2"); Mac Catalyst, "Designed for iPad" on Mac and visionOS are off project.yml
XcodeGen on the PATH as xcodegen Scripts/generate.sh
Python 3 used by Scripts/generate.sh, Scripts/asc.py and the reference generators scripts
Bundle identifier ai.spboucher.orix.calc, version 1.0.0 (1) project.yml

The engine VALIDATION.md records were produced with Swift 6.4.2 on macOS 27. An Xcode release that provides the iOS 26 SDK and a Swift 6.2 or later toolchain is required; the repository does not pin an Xcode version.

# Third-party dependencies

Two, both pinned to exact versions and resolved in Packages/ORIXExpression/Package.resolved:

Package Version Licence Used by
BigInt (attaswift) 5.7.0 (exact) MIT ORIXExpression, ORIXSymbolic
Swift Numerics (Apple) 1.1.1 (exact) Apache 2.0 ORIXExpression (ComplexModule, RealModule)

System frameworks, as listed in the app's Settings screen (App/Sources/SettingsView.swift): SwiftUI, SwiftData, Swift Charts, Accelerate (LAPACK, compiled with ACCELERATE_NEW_LAPACK), Vision, App Intents, CryptoKit. Everything else is first-party code in this repository.

# Repository layout

text
ORIXCalc/
├── project.yml                  XcodeGen definition: app, unit-test and UI-test targets, one scheme
├── App/
│   ├── Sources/                 App target: entry point, adaptive shell, history, settings, intents, Math Camera view, FeatureRegistry
│   └── Resources/               Info.plist, asset catalogue, privacy manifest
├── Packages/
│   ├── ORIXNumerics/            Explanation, VerificationReport, root finding, quadrature, differentiation
│   ├── ORIXExpression/          Typed values, exact arithmetic, parser, evaluator, formatter, RPN
│   ├── ORIXFinancial/           TVM, cash flows, loans, bonds, investment analysis, options, sensitivity
│   ├── ORIXStatistics/          Special functions, descriptive statistics, distributions, inference, regression, simulation
│   ├── ORIXUnits/               Unit catalogue, exact conversion, rate conventions, currency tables
│   ├── ORIXSymbolic/            Simplify, polynomials, calculus, solving, limits, series, optimisation, ODEs
│   ├── ORIXGraph/               Graph computation: sampling, analysis, implicit curves, 3D meshes (no UI)
│   ├── ORIXWorkspace/           Notebook document model, dependency graph, recalculation, exports, .orixcalc format
│   ├── ORIXMathCamera/          Vision text recognition and normalisation into parseable input
│   ├── ORIXUI/                  Design tokens and components, AppModel (shared session), SwiftData store
│   ├── ORIXFeatureCalculator/   Standard and Scientific environments
│   ├── ORIXFeatureFinancial/    Financial environment
│   ├── ORIXFeatureGraph/        Graph environment (2D and 3D)
│   ├── ORIXFeatureMath/         Math environment
│   ├── ORIXFeatureStatistics/   Statistics environment
│   ├── ORIXFeatureConvert/      Convert environment
│   └── ORIXFeatureWorkspace/    Workspace environment
├── Tests/                       App unit tests (ORIXCalcTests)
├── UITests/                     XCUITests (ORIXCalcUITests)
├── Benchmarks/                  Command-line benchmark package (orix-bench)
├── Scripts/                     generate, test-all, shot, screenshots, release, secret-scan, asc.py
└── docs/                        architecture, mathematics, development, design, release, research, assets, screenshots

Ignored by git (.gitignore): .build/, build/, dist/, DerivedData/, *.xcodeproj/, signing material and .env files. The Xcode project is therefore never committed; generate it.

Engine packages that carry references also have API.md, VALIDATION.md and a Reference/ directory (Financial, Statistics, Units, Symbolic; Graph has the two documents and no Reference/).

# Generate the project

sh
Scripts/generate.sh

The script rewrites project.yml into a temporary spec and runs xcodegen generate:

  • A package listed in project.yml whose Package.swift is absent is left out of the project, so the app still builds while a package is missing.
  • ORIX_EXCLUDE="ORIXGraph ORIXFeatureGraph" Scripts/generate.sh leaves packages out on purpose.
  • The placeholder __ORIX_FEATURE_FLAGS__ in SWIFT_ACTIVE_COMPILATION_CONDITIONS is replaced by one flag per feature package that is present: ORIX_HAS_FINANCIAL, ORIX_HAS_CONVERT, ORIX_HAS_GRAPH, ORIX_HAS_MATH, ORIX_HAS_STATISTICS, ORIX_HAS_WORKSPACE. App/Sources/FeatureRegistry.swift imports each feature under its flag and shows UnavailableFeature for an environment that was left out.

ORIXFeatureCalculator is always required (the app imports it unconditionally).

# Simulators

The scripts address two dedicated simulators by name: "ORIXCalc iPhone" (Scripts/test-all.sh, Scripts/shot.sh) and "ORIXCalc iPad" (Scripts/shot.sh ipad). Create them once, choosing a device type and a runtime that are installed (iOS 26 or later):

sh
xcrun simctl list devicetypes          # pick an iPhone and an iPad identifier
xcrun simctl list runtimes             # pick an iOS runtime identifier
xcrun simctl create "ORIXCalc iPhone" <iphone-devicetype-id> <ios-runtime-id>
xcrun simctl create "ORIXCalc iPad"   <ipad-devicetype-id>   <ios-runtime-id>

The repository does not prescribe particular device models.

# Build and run

sh
Scripts/generate.sh
xcodebuild -project ORIXCalc.xcodeproj -scheme ORIXCalc -configuration Debug \
  -destination "platform=iOS Simulator,name=ORIXCalc iPhone" -derivedDataPath build/DerivedData build

Scripts/shot.sh expects the Debug product at build/DerivedData/Build/Products/Debug-iphonesimulator/ORIXCalc.app, which is where the command above puts it. To launch it and capture the screen:

sh
Scripts/shot.sh iphone /tmp/standard.png -ORIXMode standard -ORIXExpression "1234.5*(3+4)"

shot.sh boots the simulator, overrides the status bar, installs the app, launches it with -ORIXInMemory 1 plus the arguments given, waits ORIX_SHOT_DELAY seconds (default 4) and saves a screenshot. Scripts/screenshots.sh uses it to regenerate docs/screenshots/ from the running app. Alternatively open ORIXCalc.xcodeproj in Xcode and run the ORIXCalc scheme.

Engine packages build and test from the command line without Xcode's project: cd Packages/ORIXFinancial && swift build.

# Launch arguments

Read by LaunchOptions in App/Sources/ORIXCalcApp.swift. They exist for UI tests and for capturing real screenshots; they never change calculations.

Argument Value Effect
-ORIXMode standard, scientific, financial, graph, math, statistics, convert, workspace Opens that environment (CalcMode raw value)
-ORIXSection a section name, for example tvm, bond (Financial) Passed to the screen of the environment named by -ORIXMode (as category for Convert)
-ORIXDemo 1 Passes demo: true to the feature screens; used by Scripts/screenshots.sh
-ORIXInMemory 1 In-memory store and an ephemeral UserDefaults suite; nothing is persisted
-ORIXCompanion 1 Shows the companion calculator of the iPad shell
-ORIXAppearance system, light, dark Overrides the appearance preference
-ORIXExpression an expression Sets it in the calculator and evaluates it at launch

# File-header convention

Every first-party file starts with a header carrying the product name, the path from the repository root, a one-line description, the author and the contact.

Swift (Package.swift keeps // swift-tools-version on the first line, above the header):

swift
// ORIX Calc
// File: Packages/ORIXFinancial/Sources/ORIXFinancial/TVM.swift
// Description: …
//
// Author: Simon-Pierre Boucher
// Contact: contact@spboucher.ai

Shell, Python and YAML use the same lines with # (after the shebang). Markdown uses an HTML comment:

md
<!--
ORIX Calc
File: docs/development/setup.md
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Adding an environment

Feature packages do not depend on each other; each depends on ORIXUI and on its engine.

  1. Package. Create Packages/ORIXFeature<Name>/ with a Package.swift modelled on an existing feature package (tools 6.2, .iOS(.v26), .macOS(.v15), Swift 6 language mode, dependencies ../ORIXUI + the engine, one library target, one test target).

  2. Screen contract. Expose one public SwiftUI view named <Name>Screen that reads the shared session from the environment and takes its launch parameters in the initialiser:

    swift
    public struct FinancialScreen: View {
        @Environment(AppModel.self) private var model
        public init(section: String? = nil, demo: Bool = false) { … }
    }

    Cross-environment actions go through the AppModel mailboxes or the graphPreview environment seam, never through an import of another feature package.

  3. Mode. Add the case to CalcMode (Packages/ORIXUI/Sources/ORIXUI/Core/CalcMode.swift: title, symbol, tint, tagline; the ⌘-number shortcut follows the case order).

  4. project.yml. Add the package under packages: and under the ORIXCalc target's dependencies:.

  5. Scripts/generate.sh. Add the name to the features list so that an ORIX_HAS_<NAME> flag is emitted.

  6. App/Sources/FeatureRegistry.swift. Import the package under #if ORIX_HAS_<NAME>, add the case to screen(for:calculator:options:) with the UnavailableFeature fallback, and register any native functions the environment contributes to the expression engine in registerNatives.

  7. Tests. Add the package to the features loop of Scripts/test-all.sh.

# Other scripts

Script Purpose
Scripts/test-all.sh [engines|features|app|all] Runs the test suites and writes build/test-summary.txt
Scripts/screenshots.sh Captures the running app into docs/screenshots/
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
Scripts/secret-scan.sh Scans tracked and staged files for credentials, private material and build products; exits non-zero on a finding
Scripts/asc.py Minimal App Store Connect API client
cd Benchmarks && swift run -c release orix-bench Engine benchmark; results in benchmark-results.md
Files main
Menu

Theme