Repository Public
1# Development setup23How to get from a fresh checkout to a running Debug build, how the packages are built on their own, and4which command-line switches the app and the preview executables understand. Everything here is taken5from `project.yml`, `Scripts/*.sh`, the `Package.swift` files and the sources named in each section.67Related documents: [testing.md](testing.md), [performance.md](performance.md),8[localization.md](localization.md), [accessibility.md](accessibility.md),9[../architecture/overview.md](../architecture/overview.md), [../release/signing.md](../release/signing.md).1011## 1. Requirements1213| Requirement | Value | Where it is declared |14|---|---|---|15| Deployment target | macOS 14.0 | `project.yml` (`deploymentTarget`, `MACOSX_DEPLOYMENT_TARGET`); every `Package.swift` has `platforms: [.macOS(.v14)]` |16| Swift language version | 6.0, strict concurrency `complete` for the app target | `project.yml` (`SWIFT_VERSION`, `SWIFT_STRICT_CONCURRENCY`); every `Package.swift` starts with `// swift-tools-version: 6.0` |17| Xcode | `xcodeVersion: "27.2"` in `project.yml` | `project.yml` |18| Architectures | Debug: arm64 only (`ONLY_ACTIVE_ARCH: YES`); Release: `arm64 x86_64` | `project.yml` (`configs`) |19| XcodeGen | required: `ORIXSheet.xcodeproj` is generated from `project.yml` | `Scripts/build.sh generate` |20| DuckDB | v2.0.1 universal shared library, downloaded and pinned by SHA-256 | `Scripts/fetch-duckdb.sh` |21| Signing identity (Debug) | `Apple Development`, manual signing, team `3YM54G49SN` | `project.yml` |22| Signing identity (Release) | `Developer ID Application` | `project.yml`, `Scripts/sign.sh` |2324Source: `project.yml`, `Scripts/build.sh`, `Scripts/fetch-duckdb.sh`, `Packages/*/Package.swift` (22 packages, all with tools version 6.0 and `.macOS(.v14)`), read on 2026-11-21.2526The build machine on which the numbers of this repository were measured is described in27`docs/research/technology-evaluation.md`: macOS 27.0 (26A5425a), Apple M5 Max, 18 cores, 48 GB RAM,28Xcode 27.2 (27B52), Swift 6.4.2. No other configuration was tried; in particular **no build on an Intel29Mac and no run on macOS 14 or 15 is recorded anywhere in the repository**, although the Release30configuration produces a universal binary and the deployment target is 14.0.3132### Optional tools3334| Tool | Needed for | Behaviour when absent |35|---|---|---|36| `/opt/homebrew/bin/python3` with openpyxl, pandas | interoperability tests of `SheetIO`; regenerating fixtures | the tests are disabled by `.enabled(if: Tools.hasPython)`, not failed |37| A Python ≥ 3.9 interpreter (any location the app discovers) | Python Studio at run time; tests of `SheetPython` / `FeaturePython` | the tests are disabled with the comment "No Python ≥ 3.9 interpreter was found on this Mac" |38| `/opt/homebrew/bin/soffice` (LibreOffice) | LibreOffice interoperability tests of `SheetIO`, the template cross-check, regenerating fixtures | tests disabled / skipped |39| `create-dmg` | the styled disk image of `Scripts/package.sh` | the script falls back to a plain `hdiutil` image |40| Apple Intelligence (FoundationModels, macOS 26+) | the on-device assistant | the framework is weak-linked and every use is guarded; the panel reports the model as unavailable |41| Accessibility permission for the test runner | the accessibility-tree tests of `SheetUI` | the suite is disabled (`AXIsProcessTrusted()`) |4243Source: `Packages/SheetIO/Tests/SheetIOTests/TestSupport.swift` (`Tools`), `Packages/SheetPython/Tests/SheetPythonTests/Support.swift` (`Interp`), `Scripts/package.sh`, `Packages/SheetIntelligence/Package.swift` (comment on weak linking), `Packages/SheetUI/Tests/SheetUITests/AccessibilityTests.swift`.4445## 2. Repository layout4647```48App/Sources/ the application shell (9 Swift files): document, menus, settings, welcome, launch arguments49App/Resources/ Info.plist, entitlements (an empty dictionary), asset catalog, Localizable.xcstrings50App/Tests/ AppIntegrationTests.swift (XCTest bundle hosted in the app)51Packages/ 22 Swift packages (libraries, feature panels, preview executables, benchmarks)52Scripts/ build.sh, fetch-duckdb.sh, test-all.sh, sign.sh, notarize.sh, package.sh,53 secret-scan.sh, localize.py (+ translations/), check-docs.py54Vendor/duckdb/ CDuckDB.xcframework and headers, created by fetch-duckdb.sh (not in git)55design/ icon sources and concepts, DMG background56docs/ this documentation57project.yml XcodeGen specification of ORIXSheet.xcodeproj58build/, dist/ build products (ignored by git)59```6061`.gitignore` excludes `.build/`, `build/`, `dist/`, `DerivedData/`, `.swiftpm/`, `Vendor/duckdb/dl/`,62`Vendor/duckdb/CDuckDB.xcframework/`, `Vendor/python/`, signing material (`*.p8`, `*.p12`,63`*.mobileprovision`, `*.cer`), `.env` files and Python caches.6465## 3. First build6667<!-- diagram: setup-build-flow -->68```mermaid69flowchart TD70 A["Scripts/fetch-duckdb.sh<br/>download, verify SHA-256,<br/>create CDuckDB.xcframework"] --> B["xcodegen generate<br/>project.yml to ORIXSheet.xcodeproj"]71 B --> C["xcodebuild Debug<br/>build/DerivedData"]72 C --> D["ORIX Sheet.app (Debug, arm64)"]73 B --> E["Scripts/sign.sh<br/>xcodebuild Release + Developer ID"]74 E --> F["dist/ORIX Sheet.app<br/>(universal, hardened runtime)"]75 A --> G["swift build / swift test<br/>inside Packages/SheetData,<br/>FeatureData, SheetAutomation"]76```77SVG fallback: 7879```sh80Scripts/build.sh generate # fetch DuckDB if needed, then regenerate ORIXSheet.xcodeproj81Scripts/build.sh debug # build the Debug app into build/DerivedData (generates first if needed)82Scripts/build.sh run # open "build/DerivedData/Build/Products/Debug/ORIX Sheet.app"83Scripts/build.sh test # Scripts/test-all.sh: swift test in every package84Scripts/build.sh release # Scripts/sign.sh: Release build signed with Developer ID, into dist/85```8687`Scripts/build.sh` with no argument runs `debug`. The script filters the `xcodebuild` output down to88lines containing `error:`, warnings whose text starts with `unre` (the `grep` pattern is89`warning: unre`) and the `** BUILD … **` line. Other warnings are therefore not shown by the script.9091### fetch-duckdb9293`Scripts/fetch-duckdb.sh` downloads94`duckdb-shared-libs-osx-universal.tar.gz` of DuckDB **v2.0.1** from the project's GitHub releases,95checks it against the SHA-256 pinned in the script96(`9a4be5a2a31ad5bb8c92bf37f18d59b9c10a79b392d7848cabd6eb2e05837449`; the script stops if the check97fails), copies `duckdb.h` into `Vendor/duckdb/Headers` with a `module.modulemap`, and wraps98`libduckdb.dylib` into `Vendor/duckdb/CDuckDB.xcframework` with `xcodebuild -create-xcframework`. It does99nothing when the xcframework is already present; `--force` rebuilds it. This is the only step of a100normal build that uses the network. The extracted library is 128 MB on disk101(`du -sh Vendor/duckdb/dl/libduckdb.dylib`, measured 2026-11-21), which is why it is not kept in git.102103The xcframework is consumed as a `binaryTarget` by `Packages/SheetData/Package.swift`; `FeatureData` and104`SheetAutomation` depend on `SheetData`. Those three packages (and the app) do not build before the105script has run once. All other packages build without it.106107### XcodeGen108109`ORIXSheet.xcodeproj` is a generated artifact: edit `project.yml`, then run110`Scripts/build.sh generate` (or `xcodegen generate`). The project declares two targets:111112| Target | Type | Sources | Notes |113|---|---|---|---|114| `ORIXSheet` | application | `App/Sources`, the asset catalog, `Localizable.xcstrings` | bundle id `ai.spboucher.orix.sheet`, product name "ORIX Sheet", hardened runtime on, App Sandbox off, manual signing |115| `ORIXSheetTests` | `bundle.unit-test` | `App/Tests` | hosted in the app (`TEST_HOST`), bundle id `ai.spboucher.orix.sheet.tests` |116117Source: `project.yml`, read on 2026-11-21.118119The app target links fourteen local packages: `SheetCore`, `SheetFormat`, `SheetEngine`, `SheetIO`,120`SheetUI`, `FeatureAudit`, `FeatureAutomation`, `SheetAutomation`, `SheetTemplates`,121`FeatureIntelligence`, `FeatureData`, `FeaturePython`, `FeatureCharts` and `FeatureAnalysis`122(`SheetAutomation` is declared in the `packages` list and reaches the target through123`FeatureAutomation`; the other thirteen are listed as target dependencies). The remaining libraries124(`FunctionsNumeric`, `FunctionsText`, `FunctionsLookup`, `SheetData`, `SheetCharts`, `SheetAnalytics`,125`SheetPython`, `SheetIntelligence`) come in transitively.126127`App/Sources/Features.swift` registers the features by hand in `Features.registerAll()` and assigns128`Welcome.provider` with the template chooser (`App/Sources/TemplateChooser.swift`) and129`TemplateLibrary`, so the chooser is shown at launch (when the "show welcome" setting is on) and from130*File ▸ New from Template…* (⇧⌘N).131132The scheme's test action passes `-ApplePersistenceIgnoreState YES` and `-ORIXTesting YES` to the host133app (section 5).134135## 4. Building and testing packages on their own136137Every package is a plain SwiftPM package with local path dependencies; it can be built without Xcode138and without the app:139140```sh141cd Packages/SheetCore && swift build # debug142cd Packages/SheetEngine && swift build -c release143cd Packages/FunctionsNumeric && swift test # one package's tests144Scripts/test-all.sh SheetCore SheetFormat # several packages, with a summary table145```146147Each package keeps its own `.build/` directory, so the first build of a package high in the dependency148graph recompiles its dependencies. Use `--scratch-path <dir>` to build somewhere else (for instance when149another build of the same package is running). The dependency graph is described in150[../architecture/overview.md](../architecture/overview.md).151152Timings observed while preparing this documentation (release builds from a cold scratch directory on the153build machine, 2026-11-21, other builds running at the same time): `sheet-preview` 30 s,154`audit-preview` 43 s, `charts-preview` 47 s. They are indications, not benchmarks.155156## 5. Launch arguments of the app157158The app reads the following arguments through `UserDefaults` (each is passed as `-Name value` on the159command line). They exist for tests, screenshots and automation.160161| Argument | Effect |162|---|---|163| `-ORIXOpen <path>` | open a file at launch (suppresses the untitled document) |164| `-ORIXTemplate <id>` | open the template with that identifier (`TemplateLibrary`, see [../templates.md](../templates.md)) instead of the untitled document; ignored when `-ORIXOpen` is also given or the identifier is unknown |165| `-ORIXSheet <name>` | activate the sheet with that name (applied before `-ORIXSelect`) |166| `-ORIXSelect <A1 ref>` | select a cell or range (`session.goTo`) |167| `-ORIXPane <id>` | show an inspector pane; `none` hides the inspector |168| `-ORIXStudio <id>` | show a studio pane |169| `-ORIXBottom <pane id>` | show a bottom pane |170| `-ORIXSidebar YES\|NO` | show or hide the sidebar |171| `-ORIXAction <action id>` | perform the registered workspace action with that identifier (for example `automation.studio`) |172| `-ORIXFind 1` | open the find-and-replace bar |173| `-ORIXTesting YES` | do not open an untitled document or the welcome window at launch; set by the `test` action of the `ORIXSheet` scheme for the app-hosted tests (read in `AppDelegate.applicationShouldOpenUntitledFile`, not in `LaunchArguments`) |174| `-ORIXAppearance light\|dark` | force the appearance |175| `-ORIXWindowSize <W>x<H>` | set the content size of the document window |176| `-ORIXShot <png>` | render the front window's content view to a PNG, print `grid draw <ms>` when a grid is present, then exit |177| `-ORIXShotDelay <seconds>` | delay before the capture (default 1.5 s) |178| `-ORIXShotWindow settings\|help\|pagesetup` | with `-ORIXShot`: open and capture that window instead of the document |179| `-ORIXDumpMenus <json>` | write the main-menu tree (titles, key equivalents, actions) as JSON, then exit; used by the localization and shortcut checks |180181Source: `App/Sources/AppDelegate.swift` (`enum LaunchArguments` and its doc comment, which lists all of them except `-ORIXTesting`), `project.yml` (scheme `ORIXSheet`, `test.commandLineArguments`).182183Order of application (`LaunchArguments.apply`, `configure`): the menu dump is scheduled, the appearance is forced, then the file or template is opened; once a document exists: sheet, selection, inspector pane, sidebar, studio, bottom pane, action, find bar, the auxiliary window of `-ORIXShotWindow`, window size, and finally the capture.184185Example:186187```sh188"build/DerivedData/Build/Products/Debug/ORIX Sheet.app/Contents/MacOS/ORIX Sheet" \189 -ORIXOpen /tmp/model.orixsheet -ORIXSelect B2:D10 -ORIXAppearance dark -ORIXShot /tmp/shot.png190```191192The capture is produced by the app itself (`cacheDisplay(in:to:)` on the content view); it does not need193Screen Recording permission.194195### Environment variables read by shipping code196197| Variable | Read by | Effect |198|---|---|---|199| `ORIX_SHEET_SUPPORT_DIR` | `Packages/SheetPython/Sources/SheetPython/Paths.swift`, `Packages/SheetAutomation/Sources/SheetAutomation/Store/Store.swift` | overrides the application-support directory (trust store, audit log, automation store); used by tests to isolate state |200| `ORIX_ANALYSIS_LANG` | `Packages/FeatureAnalysis/Sources/AnalysisKit/Localization.swift` | forces the language of the analysis panels |201| `ORIX_DATA_LANGUAGE` | `Packages/FeatureData/Sources/FeatureData/Support/Localization.swift` | forces the language of the data panels |202| `ORIX_WHATIF_DEMO_WRITE_SUMMARY` | `Packages/FeatureAnalysis/Sources/WhatIfTools/ScenarioStore.swift` | demo aid of the what-if tools |203204Source: `grep -rn 'ProcessInfo.processInfo.environment\["' Packages App --include='*.swift'`, run on 2026-11-21. Variables read only by tests or by `Package.swift` files are listed in [testing.md](testing.md).205206## 6. Preview executables207208Most UI packages ship a small AppKit executable that opens the real views on synthetic data. They are209the fastest way to work on a panel without building the whole app, and with `--shot` they render their210window to a PNG and exit, which is how the screenshots used for visual review are produced.211212| Executable | Package | Options (from the header comment of its `main.swift`) |213|---|---|---|214| `sheet-preview` | SheetUI | `[--shot out.png] [--dark] [--size WxH]` — a workbook window with demo content |215| `audit-preview` | FeatureAudit | `[--pane <id>] [--dialog rule\|table\|sort\|dedupe\|names\|filter] [--select Sheet!A1:B2] [--shot out.png] [--dark] [--size WxH] [--audit] [--bench] [--lang fr-CA]` |216| `charts-preview` | FeatureCharts | `[--state sheet\|picker\|inspector\|viewer\|figure\|dashboard\|perf] [--kind <chart kind>] [--tab data\|style\|axes\|elements] [--hover x,y] [--template id] [--panel n] [--export-figure out.pdf\|svg\|png] [--shot out.png] [--dark] [--size WxH]` |217| `data-preview` | FeatureData | `[--pane data\|sql\|import\|insert\|refused\|empty\|missing\|sidebar\|transform\|transform-sql\|pivot\|pivot-create] [--shot out.png] [--dark] [--size WxH] [--lang en\|fr-CA] [--rows N] [--bench]` — generates synthetic sample files in a temporary directory |218| `python-studio-preview` | FeaturePython | `[--shot out.png] [--dark] [--size WxH] [--run] [--script demo\|error\|loop] [--tab console\|tables\|plots\|changes\|history] [--consent] [--no-python] [--info] [--environment] [--inspector] [--fr] [--delay seconds]` |219| `intelligence-preview` | FeatureIntelligence | `[--shot out.png] [--dark] [--size WxH] [--lang fr-CA] [--panel-only]` |220| `analysis-preview`, `preview-statsbasic`, `preview-statsmodels`, `preview-finance`, `preview-whatif` | FeatureAnalysis | `[--pane <id>] [--tool <id>] [--shot out.png] [--dark] [--size WxH]`, `--list` prints the available ids |221| `chart-gallery` | SheetCharts | `chart-gallery <output-directory>` — one PNG (2x), SVG and PDF per chart kind, a dark PNG per kind and three multi-panel figures, all on synthetic data |222| `templates-preview` | SheetTemplates | `--template <id> [--locale fr_CA] [--dark] [--sheet <n>] [--size WxH] [--shot out.png] [--chrome]`, `--list` prints the template ids. Charts are drawn when FeatureCharts is linked and conditional formats when FeatureAudit is linked; the harness prints which are active |223| `automation-preview` | FeatureAutomation | `[--state editor\|running\|finished\|history\|schedule] [--shot out.png] [--dark] [--size WxH] [--compact] [--fr]` — sample files are generated in a temporary folder and Application Support is redirected there, so the user's workflow library, history and approvals are not touched |224225Source: header comments and `CommandLine.arguments` uses of the `main.swift` files under `Packages/*/Sources/*-preview/`, `Packages/FeatureAnalysis/Sources/AnalysisPreviewKit/Preview.swift`, `Packages/SheetCharts/Sources/chart-gallery/main.swift`; `Package.swift` of each package.226227Run them with SwiftPM from the package directory, for example:228229```sh230cd Packages/SheetUI && swift run sheet-preview --dark --size 1440x900231cd Packages/FeatureCharts && swift run charts-preview --state figure --shot /tmp/figure.png232cd Packages/FeatureAudit && swift run -c release audit-preview --bench233```234235A few sources parse flags that their header comment does not list (for example `--finding` and236`--no-audit` in `audit-preview`, `--whatif` in `charts-preview`, `--approve`, `--empty` and237`--unrestricted` in `python-studio-preview`, `--idle`, `--request`, `--simulate-unavailable` and `--task`238in `intelligence-preview`). Read the `main.swift` of the harness before relying on one of them.239240### Command-line tools that are not previews241242| Executable | Package | Purpose |243|---|---|---|244| `orix-bench` | SheetEngine | engine benchmark: `swift run -c release orix-bench [--json out.json] [--quick]`; produced `docs/benchmarks/engine.json` and `engine.txt` |245| `orix-data-bench` | SheetData | data-engine benchmark: `orix-data-bench --dir /tmp/orix-bench [--rows 10000000] [--threads N] [--memory-gb N] [--keep]`, JSON report on stdout |246| `orix-sheet` | SheetAutomation | command-line interface of ORIX Sheet (`convert`, `recalc`, `eval`, `info`, `audit`, `sql`, `run`, `templates`, `functions`, `version`); the release build embeds it in the app at `Contents/MacOS/orix-sheet`. See [../architecture/automation.md](../architecture/automation.md) |247248Source: `Packages/SheetEngine/Sources/orix-bench/main.swift`, `Packages/SheetData/Sources/orix-data-bench/main.swift`, `Packages/SheetAutomation/Sources/orix-sheet/main.swift`.249250## 7. Localization and documentation checks251252```sh253Scripts/localize.py # scan the code, merge the tables, regenerate both catalogs254Scripts/localize.py --check # verify only; exit 1 on any problem255python3 Scripts/check-docs.py # validate relative links, images and diagram fallbacks of docs/**/*.md256python3 docs/assets/diagrams/make_diagrams.py # regenerate the SVG fallbacks from the Mermaid blocks257Scripts/secret-scan.sh # scan tracked and untracked files for credentials before a push258```259260`Scripts/localize.py` is documented in [localization.md](localization.md).261262## 8. Things that are easy to get wrong263264- **Forgetting `fetch-duckdb.sh`.** `swift build` in `SheetData`, `FeatureData` or `SheetAutomation`265 fails on the missing binary target. `Scripts/build.sh generate` and `Scripts/sign.sh` call the script266 for you; a bare `swift build` does not.267- **Editing `ORIXSheet.xcodeproj`.** It is regenerated; put the change in `project.yml`.268- **Running the same package's build twice at once.** SwiftPM locks `.build/`; use `--scratch-path`.269- **Debug numbers.** `orix-bench` prints a warning in a debug build; the I/O benchmark document states a270 debug build is 2–4 times slower. Measure in release ([performance.md](performance.md)).271- **Python generators.** The generator scripts hard-code `/opt/homebrew/bin/python3` and272 `/opt/homebrew/bin/soffice`; `/usr/bin/python3` (3.9.6 on the build machine) has no scientific273 packages (`docs/research/technology-evaluation.md`).274