SPB Git

Repository Public

setup.md 19.7 KB

# 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

text
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: Build flow

sh
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:

sh
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 table

Each 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:

sh
"build/DerivedData/Build/Products/Debug/ORIX Sheet.app/Contents/MacOS/ORIX Sheet" \
    -ORIXOpen /tmp/model.orixsheet -ORIXSelect B2:D10 -ORIXAppearance dark -ORIXShot /tmp/shot.png

The 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:

sh
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 --bench

A 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

sh
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 push

Scripts/localize.py is documented in localization.md.

# 8. Things that are easy to get wrong

  • Forgetting fetch-duckdb.sh. swift build in SheetData, FeatureData or SheetAutomation fails on the missing binary target. Scripts/build.sh generate and Scripts/sign.sh call the script for you; a bare swift build does not.
  • Editing ORIXSheet.xcodeproj. It is regenerated; put the change in project.yml.
  • Running the same package's build twice at once. SwiftPM locks .build/; use --scratch-path.
  • Debug numbers. orix-bench prints 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/python3 and /opt/homebrew/bin/soffice; /usr/bin/python3 (3.9.6 on the build machine) has no scientific packages (docs/research/technology-evaluation.md).
Files main
Menu

Theme