Development setup
Requirements
Read from project.yml and Packages/ORIXDocsKit/Package.swift:
| Requirement | Value | Source |
|---|---|---|
| Deployment target | macOS 15.0 | options.deploymentTarget in project.yml; platforms: [.macOS(.v15)] in Package.swift |
| Swift language version | 6.0, strict concurrency complete, default actor isolation MainActor for the app target |
SWIFT_VERSION, SWIFT_STRICT_CONCURRENCY, SWIFT_DEFAULT_ACTOR_ISOLATION |
| Swift tools version | 6.0 | first line of Package.swift |
| Project generator | XcodeGen (project.yml is the source; ORIXDocs.xcodeproj is generated) |
project.yml |
| Package dependency | SwiftMath (https://github.com/mgriebling/SwiftMath), pinned by revision |
Package.swift, Package.resolved |
| Signing | Debug: automatic. Release: manual, "Developer ID Application", hardened runtime, team 3YM54G49SN |
settings in project.yml |
| Localisations | en, fr-CA |
CFBundleLocalizations |
The package needs network access once, to fetch SwiftMath; nothing else is downloaded. The engines have no other third-party dependency.
Optional tools used by some tests and scripts, each skipped or reported as "not run" when absent: Poppler (pdffonts, pdftotext, pdfimages in /opt/homebrew/bin) for the PDF tests; pandoc and LibreOffice (soffice) for the DOCX and format cross-checks; create-dmg for the disk image.
Generate and build
# Generate the Xcode project (after any change to project.yml or to the file list)
xcodegen generate
# Build the app (generates the project, builds Debug into build/DerivedData)
Scripts/build.sh # or: Scripts/build.sh release
# The same without the script
xcodebuild -project ORIXDocs.xcodeproj -scheme ORIXDocs -configuration Debug -derivedDataPath build/DerivedData build
# Build and test the engines without Xcode
cd Packages/ORIXDocsKit
swift build
swift test --no-parallelThe built application is build/DerivedData/Build/Products/Debug/ORIX Docs.app. build/, dist/, .build/ and DerivedData/ are ignored by git (.gitignore).
To work on one engine while another does not compile, restrict the package with ORIX_ONLY, a comma-separated list of target names (handled at the top of Package.swift):
ORIX_ONLY=DocModel,DocReferences,DocReferencesTests swift test --no-parallelRunning the tests is described in testing.md; benchmarks in performance.md; the command-line tool and workflows in automation.md.
Repository layout
ORIXDocs/
├── project.yml XcodeGen definition: app target, UI test bundle, scheme, document types
├── ORIXDocs.xcodeproj generated by xcodegen
├── App/
│ ├── Resources/ Info.plist, entitlements, Assets.xcassets (AppIcon, AccentColor)
│ └── Sources/
│ ├── App/ AppDelegate and main menu, settings, launch options, template chooser, self-test, demo content
│ ├── Document/ ORIXDocument (NSDocument), DocumentSession, commands, window controller
│ ├── Canvas/ EditorCanvasView: drawing, keyboard, mouse, clipboard, accessibility
│ ├── Workspace/ WorkspaceView (mode bar, ruler, canvas host, status bar), FormatBar
│ ├── Sidebar/ Outline, Pages, Find, Review panels
│ ├── Inspector/ Typography, Styles, Document, Table, Object, References, Publish, Auditor, Intelligence
│ ├── Sheets/ Equation, link, citation, cross-reference, table, export, compare, formula, caption sheets
│ ├── Automation/ Workflows sheet, App Intents
│ ├── Intelligence/ Text tools and on-device writing panel
│ └── DesignSystem/ Tokens and shared components
├── Packages/ORIXDocsKit/ the engines (no SwiftUI)
│ ├── Package.swift
│ ├── Sources/
│ │ ├── DocModel/ model, styles, numbering, editing operations, change tracking
│ │ ├── DocContainer/ ZIP reader and writer, shared import/export types
│ │ ├── DocDOCX/ WordprocessingML import and export
│ │ ├── DocFormats/ native container, Markdown, HTML, RTF, plain text, PDF text import
│ │ ├── DocMath/ LaTeX math typesetting (SwiftMath)
│ │ ├── DocReferences/ BibTeX, RIS, CSL-JSON; citation and bibliography formatting
│ │ ├── DocLayout/ typesetting, pagination, rendering, PDF publishing
│ │ ├── DocReview/ document comparison
│ │ ├── DocAudit/ document auditor and research checks
│ │ ├── DocTemplates/ template library
│ │ ├── DocAutomation/ converter facade, workflows, text intelligence
│ │ ├── orixdocs/ command-line tool
│ │ └── orixbench/ benchmark tool
│ └── Tests/ one test target per engine (Swift Testing)
├── UITests/ XCUITest suite (EditorUITests.swift)
├── Scripts/ build.sh, test.sh, recovery-test.sh, docx-compat.sh, l10n.py, release.sh, notarize.sh, package.sh
├── design/
│ ├── icon/ make-icon.swift, concept images, 1024 px master
│ └── dmg/ make-background.swift (disk image artwork)
└── docs/ architecture, compatibility, design, development, reports, research, release, screenshots, assetsThe app target compiles everything under App/Sources and depends on the package product ORIXDocsKit, which re-exports all library targets. Dependencies between engines are listed in overview.md.
Launch options
The application reads options from UserDefaults, so they are given on the command line as -Key value. They exist for tests, screenshots and scripts; none appears in the interface. Those of LaunchOptions (App/Sources/App/AppSettings.swift) are applied once, to the first document window, and only when the launch is "automated": -ORIXTemplate, -ORIXOpen, -ORIXUITest or -ORIXSelfTest is present. An automated launch also suppresses the untitled document and the template chooser at start-up.
| Key | Type | Effect |
|---|---|---|
-ORIXTemplate |
string (template id) | Creates a document from that template at launch (blank, thesis, research-report, …). |
-ORIXOpen |
string (path) | Opens that file at launch. |
-ORIXUITest |
boolean | Marks the launch as automated; no other effect. |
-ORIXMode |
string (writing, pageLayout, review, academic, publishing, focus) |
Sets the workspace mode. |
-ORIXInspector |
string (format, styles, document, table, object, academic, publish, audit, intelligence) |
Shows the inspector on that tab. |
-ORIXSidebar |
string (outline, pages, search, review) |
Shows the sidebar on that tab. |
-ORIXZoom |
number (1 = 100 %) | Sets the zoom; when present, the automatic fit of a narrow window is skipped (WorkspaceView.swift). |
-ORIXAppearance |
string | dark forces Dark Aqua; any other value forces Aqua. |
-ORIXPage |
integer (1-based) | Scrolls to that page 0.4 s after the window opens. |
-ORIXHideInspector, -ORIXHideSidebar |
YES | Start with that panel hidden. |
-ORIXAudit |
YES | Runs the document auditor 0.7 s after the window opens. |
-ORIXChooserSnapshot |
path | Shows the template chooser, writes its window to that PNG and exits. |
-ORIXSaveTo |
path | Saves the new document to that .orixdoc file. |
-ORIXType |
text | Types the text through real key events and keeps running (recovery test). |
-ORIXDumpText |
path | Writes the body text to that file and exits. |
-ORIXDemo |
string | Applies named demo content after 0.3 s (DemoContent.apply; names such as review, table, cells, object, equation, select, find, end). |
-ORIXSaveTo |
string (path) | Saves the document to that path as a native file after 0.5 s. |
-ORIXSelfTest |
string (path of the JSON report) | Runs the interaction self-test after 1 s, writes the report and exits (testing.md). |
-ORIXType |
string | Types the text through real key events after 1 s and keeps running (used by Scripts/recovery-test.sh). |
-ORIXDumpText |
string (path) | Writes the body paragraphs as plain text after 0.8 s and exits. |
-ORIXSheet |
string (equation, link, citation, xref, table, export, compare, warnings, properties, formula, caption, automation) |
Opens that sheet after 0.6 s. |
-ORIXWidth, -ORIXHeight |
numbers (points) | Sets the window's content size; the height defaults to 880 when only the width is given. -ORIXHeight alone has no effect. |
-ORIXSnapshot |
string (path) | Renders the window (or the sheet showing) to a PNG, then exits. |
-ORIXSnapshotDelay |
number (seconds, default 1.6) | Delay before the snapshot. |
Read outside LaunchOptions:
| Key | Type | Where | Effect |
|---|---|---|---|
-ORIXAutosaveDelay |
number (seconds, minimum 1, default 5) | AppDelegate.swift |
Sets NSDocumentController.autosavingDelay (persistence.md). |
-ORIXCompareWith |
string (path) | Sheets/CompareSheet.swift |
The compare sheet loads that file and compares at once. |
-ORIXCompareSnapshot |
string (path) | Sheets/ComparisonWindow.swift |
Captures the comparison window to a PNG and leaves. |
-ORIXAutomationDemo |
string (run) |
Automation/AutomationSheet.swift |
Debug builds: runs the selected workflow into a scratch folder. |
-ORIXIntelligenceAction |
string (action id) | Inspector/IntelligenceInspector.swift |
Runs that writing action when the panel appears. |
-ORIXIntelligenceDemo, -ORIXIntelligenceApply, -ORIXIntelligenceTool |
strings | same file | Debug builds only: a scripted answer for screenshots, applying a proposal (accept, insert, undo), running a text tool. |
Two ordinary preference keys are also set this way by the scripts: -checkSpelling NO (an AppSettings key) and the system keys -ApplePersistenceIgnoreState YES and -AppleLanguages "(en)".
Example, as used by Scripts/test.sh:
"build/DerivedData/Build/Products/Debug/ORIX Docs.app/Contents/MacOS/ORIX Docs" \
-ApplePersistenceIgnoreState YES -ORIXTemplate blank \
-ORIXSelfTest "$PWD/build/selftest.json" -checkSpelling NO -AppleLanguages "(en)"