SPB Git

Repository Public

setup.md 10.8 KB 153 lines markdown

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
Files main
Menu

Theme