Repository Public
1<!--2ORIX Docs3File: docs/development/setup.md4Description: Requirements, project generation, build commands, repository layout and launch options.5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->8# Development setup910## Requirements1112Read from `project.yml` and `Packages/ORIXDocsKit/Package.swift`:1314| Requirement | Value | Source |15|---|---|---|16| Deployment target | macOS 15.0 | `options.deploymentTarget` in `project.yml`; `platforms: [.macOS(.v15)]` in `Package.swift` |17| 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` |18| Swift tools version | 6.0 | first line of `Package.swift` |19| Project generator | XcodeGen (`project.yml` is the source; `ORIXDocs.xcodeproj` is generated) | `project.yml` |20| Package dependency | SwiftMath (`https://github.com/mgriebling/SwiftMath`), pinned by revision | `Package.swift`, `Package.resolved` |21| Signing | Debug: automatic. Release: manual, "Developer ID Application", hardened runtime, team `3YM54G49SN` | `settings` in `project.yml` |22| Localisations | `en`, `fr-CA` | `CFBundleLocalizations` |2324The package needs network access once, to fetch SwiftMath; nothing else is downloaded. The engines have no other third-party dependency.2526Optional 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.2728## Generate and build2930```sh31# Generate the Xcode project (after any change to project.yml or to the file list)32xcodegen generate3334# Build the app (generates the project, builds Debug into build/DerivedData)35Scripts/build.sh # or: Scripts/build.sh release3637# The same without the script38xcodebuild -project ORIXDocs.xcodeproj -scheme ORIXDocs -configuration Debug -derivedDataPath build/DerivedData build3940# Build and test the engines without Xcode41cd Packages/ORIXDocsKit42swift build43swift test --no-parallel44```4546The built application is `build/DerivedData/Build/Products/Debug/ORIX Docs.app`. `build/`, `dist/`, `.build/` and `DerivedData/` are ignored by git (`.gitignore`).4748To 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`):4950```sh51ORIX_ONLY=DocModel,DocReferences,DocReferencesTests swift test --no-parallel52```5354Running the tests is described in [testing.md](testing.md); benchmarks in [performance.md](performance.md); the command-line tool and workflows in [automation.md](automation.md).5556## Repository layout5758```text59ORIXDocs/60├── project.yml XcodeGen definition: app target, UI test bundle, scheme, document types61├── ORIXDocs.xcodeproj generated by xcodegen62├── App/63│ ├── Resources/ Info.plist, entitlements, Assets.xcassets (AppIcon, AccentColor)64│ └── Sources/65│ ├── App/ AppDelegate and main menu, settings, launch options, template chooser, self-test, demo content66│ ├── Document/ ORIXDocument (NSDocument), DocumentSession, commands, window controller67│ ├── Canvas/ EditorCanvasView: drawing, keyboard, mouse, clipboard, accessibility68│ ├── Workspace/ WorkspaceView (mode bar, ruler, canvas host, status bar), FormatBar69│ ├── Sidebar/ Outline, Pages, Find, Review panels70│ ├── Inspector/ Typography, Styles, Document, Table, Object, References, Publish, Auditor, Intelligence71│ ├── Sheets/ Equation, link, citation, cross-reference, table, export, compare, formula, caption sheets72│ ├── Automation/ Workflows sheet, App Intents73│ ├── Intelligence/ Text tools and on-device writing panel74│ └── DesignSystem/ Tokens and shared components75├── Packages/ORIXDocsKit/ the engines (no SwiftUI)76│ ├── Package.swift77│ ├── Sources/78│ │ ├── DocModel/ model, styles, numbering, editing operations, change tracking79│ │ ├── DocContainer/ ZIP reader and writer, shared import/export types80│ │ ├── DocDOCX/ WordprocessingML import and export81│ │ ├── DocFormats/ native container, Markdown, HTML, RTF, plain text, PDF text import82│ │ ├── DocMath/ LaTeX math typesetting (SwiftMath)83│ │ ├── DocReferences/ BibTeX, RIS, CSL-JSON; citation and bibliography formatting84│ │ ├── DocLayout/ typesetting, pagination, rendering, PDF publishing85│ │ ├── DocReview/ document comparison86│ │ ├── DocAudit/ document auditor and research checks87│ │ ├── DocTemplates/ template library88│ │ ├── DocAutomation/ converter facade, workflows, text intelligence89│ │ ├── orixdocs/ command-line tool90│ │ └── orixbench/ benchmark tool91│ └── Tests/ one test target per engine (Swift Testing)92├── UITests/ XCUITest suite (EditorUITests.swift)93├── Scripts/ build.sh, test.sh, recovery-test.sh, docx-compat.sh, l10n.py, release.sh, notarize.sh, package.sh94├── design/95│ ├── icon/ make-icon.swift, concept images, 1024 px master96│ └── dmg/ make-background.swift (disk image artwork)97└── docs/ architecture, compatibility, design, development, reports, research, release, screenshots, assets98```99100The 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](../architecture/overview.md).101102## Launch options103104The 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.105106| Key | Type | Effect |107|---|---|---|108| `-ORIXTemplate` | string (template id) | Creates a document from that template at launch (`blank`, `thesis`, `research-report`, …). |109| `-ORIXOpen` | string (path) | Opens that file at launch. |110| `-ORIXUITest` | boolean | Marks the launch as automated; no other effect. |111| `-ORIXMode` | string (`writing`, `pageLayout`, `review`, `academic`, `publishing`, `focus`) | Sets the workspace mode. |112| `-ORIXInspector` | string (`format`, `styles`, `document`, `table`, `object`, `academic`, `publish`, `audit`, `intelligence`) | Shows the inspector on that tab. |113| `-ORIXSidebar` | string (`outline`, `pages`, `search`, `review`) | Shows the sidebar on that tab. |114| `-ORIXZoom` | number (1 = 100 %) | Sets the zoom; when present, the automatic fit of a narrow window is skipped (`WorkspaceView.swift`). |115| `-ORIXAppearance` | string | `dark` forces Dark Aqua; any other value forces Aqua. |116| `-ORIXPage` | integer (1-based) | Scrolls to that page 0.4 s after the window opens. |117| `-ORIXHideInspector`, `-ORIXHideSidebar` | YES | Start with that panel hidden. |118| `-ORIXAudit` | YES | Runs the document auditor 0.7 s after the window opens. |119| `-ORIXChooserSnapshot` | path | Shows the template chooser, writes its window to that PNG and exits. |120| `-ORIXSaveTo` | path | Saves the new document to that `.orixdoc` file. |121| `-ORIXType` | text | Types the text through real key events and keeps running (recovery test). |122| `-ORIXDumpText` | path | Writes the body text to that file and exits. |123| `-ORIXDemo` | string | Applies named demo content after 0.3 s (`DemoContent.apply`; names such as `review`, `table`, `cells`, `object`, `equation`, `select`, `find`, `end`). |124| `-ORIXSaveTo` | string (path) | Saves the document to that path as a native file after 0.5 s. |125| `-ORIXSelfTest` | string (path of the JSON report) | Runs the interaction self-test after 1 s, writes the report and exits ([testing.md](testing.md#interaction-self-test)). |126| `-ORIXType` | string | Types the text through real key events after 1 s and keeps running (used by `Scripts/recovery-test.sh`). |127| `-ORIXDumpText` | string (path) | Writes the body paragraphs as plain text after 0.8 s and exits. |128| `-ORIXSheet` | string (`equation`, `link`, `citation`, `xref`, `table`, `export`, `compare`, `warnings`, `properties`, `formula`, `caption`, `automation`) | Opens that sheet after 0.6 s. |129| `-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. |130| `-ORIXSnapshot` | string (path) | Renders the window (or the sheet showing) to a PNG, then exits. |131| `-ORIXSnapshotDelay` | number (seconds, default 1.6) | Delay before the snapshot. |132133Read outside `LaunchOptions`:134135| Key | Type | Where | Effect |136|---|---|---|---|137| `-ORIXAutosaveDelay` | number (seconds, minimum 1, default 5) | `AppDelegate.swift` | Sets `NSDocumentController.autosavingDelay` ([persistence.md](../architecture/persistence.md#autosave-versions-and-recovery)). |138| `-ORIXCompareWith` | string (path) | `Sheets/CompareSheet.swift` | The compare sheet loads that file and compares at once. |139| `-ORIXCompareSnapshot` | string (path) | `Sheets/ComparisonWindow.swift` | Captures the comparison window to a PNG and leaves. |140| `-ORIXAutomationDemo` | string (`run`) | `Automation/AutomationSheet.swift` | Debug builds: runs the selected workflow into a scratch folder. |141| `-ORIXIntelligenceAction` | string (action id) | `Inspector/IntelligenceInspector.swift` | Runs that writing action when the panel appears. |142| `-ORIXIntelligenceDemo`, `-ORIXIntelligenceApply`, `-ORIXIntelligenceTool` | strings | same file | Debug builds only: a scripted answer for screenshots, applying a proposal (`accept`, `insert`, `undo`), running a text tool. |143144Two 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)"`.145146Example, as used by `Scripts/test.sh`:147148```sh149"build/DerivedData/Build/Products/Debug/ORIX Docs.app/Contents/MacOS/ORIX Docs" \150 -ApplePersistenceIgnoreState YES -ORIXTemplate blank \151 -ORIXSelfTest "$PWD/build/selftest.json" -checkSpelling NO -AppleLanguages "(en)"152```153