SPB Git

Repository Public

setup.md 10.8 KB

# 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

sh
# 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-parallel

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

sh
ORIX_ONLY=DocModel,DocReferences,DocReferencesTests swift test --no-parallel

Running the tests is described in testing.md; benchmarks in performance.md; the command-line tool and workflows in automation.md.

# Repository layout

text
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, assets

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

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

Theme