Development setup
How to get from a fresh checkout to a running Debug build, how the packages are built on their own, and
which command-line switches the app and the preview executables understand. Everything here is taken
from project.yml, Scripts/*.sh, the Package.swift files and the sources named in each section.
Related documents: testing.md, performance.md, localization.md, accessibility.md, ../architecture/overview.md, ../release/signing.md.
1. Requirements
| Requirement | Value | Where it is declared |
|---|---|---|
| Deployment target | macOS 14.0 | project.yml (deploymentTarget, MACOSX_DEPLOYMENT_TARGET); every Package.swift has platforms: [.macOS(.v14)] |
| 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 |
| Xcode | xcodeVersion: "27.2" in project.yml |
project.yml |
| Architectures | Debug: arm64 only (ONLY_ACTIVE_ARCH: YES); Release: arm64 x86_64 |
project.yml (configs) |
| XcodeGen | required: ORIXSheet.xcodeproj is generated from project.yml |
Scripts/build.sh generate |
| DuckDB | v2.0.1 universal shared library, downloaded and pinned by SHA-256 | Scripts/fetch-duckdb.sh |
| Signing identity (Debug) | Apple Development, manual signing, team 3YM54G49SN |
project.yml |
| Signing identity (Release) | Developer ID Application |
project.yml, Scripts/sign.sh |
Source: 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.
The build machine on which the numbers of this repository were measured is described in
docs/research/technology-evaluation.md: macOS 27.0 (26A5425a), Apple M5 Max, 18 cores, 48 GB RAM,
Xcode 27.2 (27B52), Swift 6.4.2. No other configuration was tried; in particular no build on an Intel
Mac and no run on macOS 14 or 15 is recorded anywhere in the repository, although the Release
configuration produces a universal binary and the deployment target is 14.0.
Optional tools
| Tool | Needed for | Behaviour when absent |
|---|---|---|
/opt/homebrew/bin/python3 with openpyxl, pandas |
interoperability tests of SheetIO; regenerating fixtures |
the tests are disabled by .enabled(if: Tools.hasPython), not failed |
| 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" |
/opt/homebrew/bin/soffice (LibreOffice) |
LibreOffice interoperability tests of SheetIO, the template cross-check, regenerating fixtures |
tests disabled / skipped |
create-dmg |
the styled disk image of Scripts/package.sh |
the script falls back to a plain hdiutil image |
| 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 |
| Accessibility permission for the test runner | the accessibility-tree tests of SheetUI |
the suite is disabled (AXIsProcessTrusted()) |
Source: 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.
2. Repository layout
App/Sources/ the application shell (9 Swift files): document, menus, settings, welcome, launch arguments
App/Resources/ Info.plist, entitlements (an empty dictionary), asset catalog, Localizable.xcstrings
App/Tests/ AppIntegrationTests.swift (XCTest bundle hosted in the app)
Packages/ 22 Swift packages (libraries, feature panels, preview executables, benchmarks)
Scripts/ build.sh, fetch-duckdb.sh, test-all.sh, sign.sh, notarize.sh, package.sh,
secret-scan.sh, localize.py (+ translations/), check-docs.py
Vendor/duckdb/ CDuckDB.xcframework and headers, created by fetch-duckdb.sh (not in git)
design/ icon sources and concepts, DMG background
docs/ this documentation
project.yml XcodeGen specification of ORIXSheet.xcodeproj
build/, dist/ build products (ignored by git).gitignore excludes .build/, build/, dist/, DerivedData/, .swiftpm/, Vendor/duckdb/dl/,
Vendor/duckdb/CDuckDB.xcframework/, Vendor/python/, signing material (*.p8, *.p12,
*.mobileprovision, *.cer), .env files and Python caches.
3. First build
flowchart TD
A["Scripts/fetch-duckdb.sh<br/>download, verify SHA-256,<br/>create CDuckDB.xcframework"] --> B["xcodegen generate<br/>project.yml to ORIXSheet.xcodeproj"]
B --> C["xcodebuild Debug<br/>build/DerivedData"]
C --> D["ORIX Sheet.app (Debug, arm64)"]
B --> E["Scripts/sign.sh<br/>xcodebuild Release + Developer ID"]
E --> F["dist/ORIX Sheet.app<br/>(universal, hardened runtime)"]
A --> G["swift build / swift test<br/>inside Packages/SheetData,<br/>FeatureData, SheetAutomation"]
SVG fallback:
Scripts/build.sh generate # fetch DuckDB if needed, then regenerate ORIXSheet.xcodeproj
Scripts/build.sh debug # build the Debug app into build/DerivedData (generates first if needed)
Scripts/build.sh run # open "build/DerivedData/Build/Products/Debug/ORIX Sheet.app"
Scripts/build.sh test # Scripts/test-all.sh: swift test in every package
Scripts/build.sh release # Scripts/sign.sh: Release build signed with Developer ID, into dist/Scripts/build.sh with no argument runs debug. The script filters the xcodebuild output down to
lines containing error:, warnings whose text starts with unre (the grep pattern is
warning: unre) and the ** BUILD … ** line. Other warnings are therefore not shown by the script.
fetch-duckdb
Scripts/fetch-duckdb.sh downloads
duckdb-shared-libs-osx-universal.tar.gz of DuckDB v2.0.1 from the project's GitHub releases,
checks it against the SHA-256 pinned in the script
(9a4be5a2a31ad5bb8c92bf37f18d59b9c10a79b392d7848cabd6eb2e05837449; the script stops if the check
fails), copies duckdb.h into Vendor/duckdb/Headers with a module.modulemap, and wraps
libduckdb.dylib into Vendor/duckdb/CDuckDB.xcframework with xcodebuild -create-xcframework. It does
nothing when the xcframework is already present; --force rebuilds it. This is the only step of a
normal build that uses the network. The extracted library is 128 MB on disk
(du -sh Vendor/duckdb/dl/libduckdb.dylib, measured 2026-11-21), which is why it is not kept in git.
The xcframework is consumed as a binaryTarget by Packages/SheetData/Package.swift; FeatureData and
SheetAutomation depend on SheetData. Those three packages (and the app) do not build before the
script has run once. All other packages build without it.
XcodeGen
ORIXSheet.xcodeproj is a generated artifact: edit project.yml, then run
Scripts/build.sh generate (or xcodegen generate). The project declares two targets:
| Target | Type | Sources | Notes |
|---|---|---|---|
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 |
ORIXSheetTests |
bundle.unit-test |
App/Tests |
hosted in the app (TEST_HOST), bundle id ai.spboucher.orix.sheet.tests |
Source: project.yml, read on 2026-11-21.
The app target links fourteen local packages: SheetCore, SheetFormat, SheetEngine, SheetIO,
SheetUI, FeatureAudit, FeatureAutomation, SheetAutomation, SheetTemplates,
FeatureIntelligence, FeatureData, FeaturePython, FeatureCharts and FeatureAnalysis
(SheetAutomation is declared in the packages list and reaches the target through
FeatureAutomation; the other thirteen are listed as target dependencies). The remaining libraries
(FunctionsNumeric, FunctionsText, FunctionsLookup, SheetData, SheetCharts, SheetAnalytics,
SheetPython, SheetIntelligence) come in transitively.
App/Sources/Features.swift registers the features by hand in Features.registerAll() and assigns
Welcome.provider with the template chooser (App/Sources/TemplateChooser.swift) and
TemplateLibrary, so the chooser is shown at launch (when the "show welcome" setting is on) and from
File ▸ New from Template… (⇧⌘N).
The scheme's test action passes -ApplePersistenceIgnoreState YES and -ORIXTesting YES to the host
app (section 5).
4. Building and testing packages on their own
Every package is a plain SwiftPM package with local path dependencies; it can be built without Xcode and without the app:
cd Packages/SheetCore && swift build # debug
cd Packages/SheetEngine && swift build -c release
cd Packages/FunctionsNumeric && swift test # one package's tests
Scripts/test-all.sh SheetCore SheetFormat # several packages, with a summary tableEach package keeps its own .build/ directory, so the first build of a package high in the dependency
graph recompiles its dependencies. Use --scratch-path <dir> to build somewhere else (for instance when
another build of the same package is running). The dependency graph is described in
../architecture/overview.md.
Timings observed while preparing this documentation (release builds from a cold scratch directory on the
build machine, 2026-11-21, other builds running at the same time): sheet-preview 30 s,
audit-preview 43 s, charts-preview 47 s. They are indications, not benchmarks.
5. Launch arguments of the app
The app reads the following arguments through UserDefaults (each is passed as -Name value on the
command line). They exist for tests, screenshots and automation.
| Argument | Effect |
|---|---|
-ORIXOpen <path> |
open a file at launch (suppresses the untitled document) |
-ORIXTemplate <id> |
open the template with that identifier (TemplateLibrary, see ../templates.md) instead of the untitled document; ignored when -ORIXOpen is also given or the identifier is unknown |
-ORIXSheet <name> |
activate the sheet with that name (applied before -ORIXSelect) |
-ORIXSelect <A1 ref> |
select a cell or range (session.goTo) |
-ORIXPane <id> |
show an inspector pane; none hides the inspector |
-ORIXStudio <id> |
show a studio pane |
-ORIXBottom <pane id> |
show a bottom pane |
-ORIXSidebar YES|NO |
show or hide the sidebar |
-ORIXAction <action id> |
perform the registered workspace action with that identifier (for example automation.studio) |
-ORIXFind 1 |
open the find-and-replace bar |
-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) |
-ORIXAppearance light|dark |
force the appearance |
-ORIXWindowSize <W>x<H> |
set the content size of the document window |
-ORIXShot <png> |
render the front window's content view to a PNG, print grid draw <ms> when a grid is present, then exit |
-ORIXShotDelay <seconds> |
delay before the capture (default 1.5 s) |
-ORIXShotWindow settings|help|pagesetup |
with -ORIXShot: open and capture that window instead of the document |
-ORIXDumpMenus <json> |
write the main-menu tree (titles, key equivalents, actions) as JSON, then exit; used by the localization and shortcut checks |
Source: App/Sources/AppDelegate.swift (enum LaunchArguments and its doc comment, which lists all of them except -ORIXTesting), project.yml (scheme ORIXSheet, test.commandLineArguments).
Order 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.
Example:
"build/DerivedData/Build/Products/Debug/ORIX Sheet.app/Contents/MacOS/ORIX Sheet" \
-ORIXOpen /tmp/model.orixsheet -ORIXSelect B2:D10 -ORIXAppearance dark -ORIXShot /tmp/shot.pngThe capture is produced by the app itself (cacheDisplay(in:to:) on the content view); it does not need
Screen Recording permission.
Environment variables read by shipping code
| Variable | Read by | Effect |
|---|---|---|
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 |
ORIX_ANALYSIS_LANG |
Packages/FeatureAnalysis/Sources/AnalysisKit/Localization.swift |
forces the language of the analysis panels |
ORIX_DATA_LANGUAGE |
Packages/FeatureData/Sources/FeatureData/Support/Localization.swift |
forces the language of the data panels |
ORIX_WHATIF_DEMO_WRITE_SUMMARY |
Packages/FeatureAnalysis/Sources/WhatIfTools/ScenarioStore.swift |
demo aid of the what-if tools |
Source: 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.
6. Preview executables
Most UI packages ship a small AppKit executable that opens the real views on synthetic data. They are
the fastest way to work on a panel without building the whole app, and with --shot they render their
window to a PNG and exit, which is how the screenshots used for visual review are produced.
| Executable | Package | Options (from the header comment of its main.swift) |
|---|---|---|
sheet-preview |
SheetUI | [--shot out.png] [--dark] [--size WxH] — a workbook window with demo content |
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] |
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] |
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 |
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] |
intelligence-preview |
FeatureIntelligence | [--shot out.png] [--dark] [--size WxH] [--lang fr-CA] [--panel-only] |
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 |
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 |
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 |
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 |
Source: 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.
Run them with SwiftPM from the package directory, for example:
cd Packages/SheetUI && swift run sheet-preview --dark --size 1440x900
cd Packages/FeatureCharts && swift run charts-preview --state figure --shot /tmp/figure.png
cd Packages/FeatureAudit && swift run -c release audit-preview --benchA few sources parse flags that their header comment does not list (for example --finding and
--no-audit in audit-preview, --whatif in charts-preview, --approve, --empty and
--unrestricted in python-studio-preview, --idle, --request, --simulate-unavailable and --task
in intelligence-preview). Read the main.swift of the harness before relying on one of them.
Command-line tools that are not previews
| Executable | Package | Purpose |
|---|---|---|
orix-bench |
SheetEngine | engine benchmark: swift run -c release orix-bench [--json out.json] [--quick]; produced docs/benchmarks/engine.json and engine.txt |
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 |
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 |
Source: Packages/SheetEngine/Sources/orix-bench/main.swift, Packages/SheetData/Sources/orix-data-bench/main.swift, Packages/SheetAutomation/Sources/orix-sheet/main.swift.
7. Localization and documentation checks
Scripts/localize.py # scan the code, merge the tables, regenerate both catalogs
Scripts/localize.py --check # verify only; exit 1 on any problem
python3 Scripts/check-docs.py # validate relative links, images and diagram fallbacks of docs/**/*.md
python3 docs/assets/diagrams/make_diagrams.py # regenerate the SVG fallbacks from the Mermaid blocks
Scripts/secret-scan.sh # scan tracked and untracked files for credentials before a pushScripts/localize.py is documented in localization.md.
8. Things that are easy to get wrong
- Forgetting
fetch-duckdb.sh.swift buildinSheetData,FeatureDataorSheetAutomationfails on the missing binary target.Scripts/build.sh generateandScripts/sign.shcall the script for you; a bareswift builddoes not. - Editing
ORIXSheet.xcodeproj. It is regenerated; put the change inproject.yml. - Running the same package's build twice at once. SwiftPM locks
.build/; use--scratch-path. - Debug numbers.
orix-benchprints a warning in a debug build; the I/O benchmark document states a debug build is 2–4 times slower. Measure in release (performance.md). - Python generators. The generator scripts hard-code
/opt/homebrew/bin/python3and/opt/homebrew/bin/soffice;/usr/bin/python3(3.9.6 on the build machine) has no scientific packages (docs/research/technology-evaluation.md).