Repository Public License
1<!-- ORIX Clean / File: docs/development/setup.md / Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai -->2# Development setup34How to build, run and extend ORIX Clean from a clone of the repository.56## Requirements78| Tool | Needed for | Notes |9|---|---|---|10| macOS with Xcode | Everything | Developed with Xcode 27.2 and Swift 6.4.2 on macOS 27.0. The package declares `swift-tools-version: 6.0`; the deployment target is macOS 15.0. Older Xcode versions were not tried |11| XcodeGen (`xcodegen`) | Generating `ORIXClean.xcodeproj` from `project.yml` | The project file is generated; edit `project.yml`, not the project |12| Python 3 (`python3`) | `Scripts/localize.py` | Standard library only |13| `hdiutil` | UI tests and some core tests | Part of macOS |14| `create-dmg` | `Scripts/package.sh` only | Falls back to a plain `hdiutil` image when it fails |15| Developer ID Application identity, `notarytool` keychain profile | Release only | See `docs/release/` |1617No third-party Swift package is used. Debug builds are signed ad hoc (`CODE_SIGN_IDENTITY: "-"`), so no18developer account is needed to build, run or test.1920## Repository layout2122```23App/ SwiftUI application (Sources, Resources, Info.plist, entitlements)24Packages/ORIXCleanCore/ Core library, orix-bench CLI, tests25UITests/ XCUITest scenarios26Scripts/ build, check, localize, icon, screenshots, signing, notarization, packaging27design/icon/ Icon concepts and the 1024-pixel icon28docs/ This documentation29project.yml XcodeGen definition30build/, dist/ Generated, ignored by git31```3233## Building and running3435`Scripts/build.sh` is the entry point. It changes to the repository root itself.3637| Command | What it does |38|---|---|39| `Scripts/build.sh generate` | Runs `Scripts/localize.py` (when `translations-fr.json` exists), then `xcodegen generate` |40| `Scripts/build.sh debug` | `generate`, then `xcodebuild` for the `ORIXClean` scheme in Debug into `build/DerivedData` |41| `Scripts/build.sh core-test` | `swift test` in `Packages/ORIXCleanCore` |42| `Scripts/build.sh uitest` | Builds a disposable disk image with the sample home folder and runs the UI tests on it (see `testing.md`) |43| `Scripts/build.sh run` | Opens `build/DerivedData/Build/Products/Debug/ORIX Clean.app` |44| `Scripts/build.sh all` | `core-test`, then `debug`. This is the default |4546The script prints a filtered summary (errors, build and test verdicts, failed test cases). The complete UI test47log is written to `build/uitest.log`.4849To work in Xcode: `Scripts/build.sh generate`, then open `ORIXClean.xcodeproj`. The scheme `ORIXClean` builds50the application and the UI test bundle. The core package can also be opened on its own51(`Packages/ORIXCleanCore/Package.swift`).5253`Scripts/check.sh` verifies repository hygiene and exits non-zero on any finding:5455- the author header on every Swift, shell and Python file and on `project.yml`;56- no signing material (`.p8`, `.p12`, `.cer`, provisioning profiles, keychains, `.env`, `AuthKey_*`);57- no credential-like strings or private network addresses;58- no network code in `App/Sources` or the core library (`URLSession`, `NWConnection`, `CFSocket`,59 `import Network`, `URLRequest`, `WKWebView`);60- no privilege escalation or private API markers (`AuthorizationExecuteWithPrivileges`, `SMJobBless`,61 `NSAppleScript`, `/usr/bin/sudo`, `dlopen(`, `_CS`, `csrutil`).6263## Project settings worth knowing6465| Setting | Value |66|---|---|67| Bundle identifier | `ai.spboucher.orix.clean` |68| Deployment target | macOS 15.0 |69| Swift | language mode 6, strict concurrency `complete`, default actor isolation `MainActor` in the application target |70| Sandbox | off (`ENABLE_APP_SANDBOX: NO`) |71| Hardened Runtime | on |72| Entitlements | empty dictionary (`App/ORIXClean.entitlements`) |73| Debug | ad hoc signature, active architecture |74| Release | `Developer ID Application`, manual signing, `--timestamp`, `arm64 x86_64` |75| Version | `MARKETING_VERSION` 1.0.0, `CURRENT_PROJECT_VERSION` 1 |7677## Launch arguments7879The application reads these through `UserDefaults` (`LaunchOptions.fromProcess`), so each is passed as80`-Name value`. They exist for UI tests, screenshots and benchmarks; none changes what the engines measure.8182| Argument | Value | Effect |83|---|---|---|84| `-ORIXHome` | directory | Uses this directory as the home folder for caches, developer data, Downloads, Trash, applications (`<home>/Applications` only), leftovers and the safety policy. Other volumes' Trashes and the Launch Services lookup are disabled |85| `-ORIXStore` | `memory` or a file path | History database: in memory, or at the given path. Default is the Application Support path |86| `-ORIXScanRoot` | directory | Starts a scan of this directory when the window appears |87| `-ORIXSection` | `overview`, `map`, `largeFiles`, `duplicates`, `similar`, `caches`, `developer`, `downloads`, `applications`, `trash`, `history`, `actions`, `reports` | Section shown at launch |88| `-ORIXAutoAnalyze` | `YES` | Runs the duplicate and similar-image searches as soon as the scan finishes |89| `-ORIXExportDir` | directory | Reports are written there without showing a save panel |90| `-ORIXAppearance` | `light` or `dark` | Overrides the appearance setting |91| `-ORIXSkipOnboarding` | `YES` | Does not show the first-launch sheet |92| `-ORIXWindowSize` | `WIDTHxHEIGHT`, for example `980x620` | Resizes the main window at launch |9394Debug builds only, and only together with `-ORIXHome`: `-ORIXDemoSelect` (`duplicates`, `uninstall`, or any other value for caches and DerivedData),95`-ORIXDemoPreview YES` and `-ORIXDemoConfirm YES` drive the real engines into a state for screenshots96(`AppModel.runDemo`). This code is inside `#if DEBUG` and is not compiled into Release builds.9798Useful standard arguments: `-onboarded NO` (show onboarding again), `-ApplePersistenceIgnoreState YES`,99`-AppleLanguages "(fr-CA)"`.100101The temporary-items rule of the cache catalogue is skipped under `-ORIXHome` (the temporary folder belongs to102the real user), and the path displayed in Settings is always the default database path.103104Example:105106```sh107"build/DerivedData/Build/Products/Debug/ORIX Clean.app/Contents/MacOS/ORIX Clean" \108 -ORIXHome /tmp/orix-demo/home -ORIXStore memory -ORIXScanRoot /tmp/orix-demo/home \109 -ORIXSection map -ORIXSkipOnboarding YES -ORIXAutoAnalyze YES110```111112## The sample folder (fixture generator)113114`orix-bench fixture <dir> [scale]` writes a sample home folder with real files of real sizes.115116```sh117cd Packages/ORIXCleanCore && swift build -c release118.build/release/orix-bench fixture /tmp/orix-demo/home # scale 1: 182 files, 1.89 GB119.build/release/orix-bench fixture /tmp/orix-demo/home 0.25 # the scale used by the UI tests120```121122**The target directory is deleted first** (`Fixture.build` removes it before writing). Point it at a new123directory under `/tmp`, never at a real folder.124125Content, all generated with a seeded pseudo-random generator so that runs are reproducible:126127- movies, music, documents and an archive, with modification dates set in the past;128- exact duplicates as real copies (a video in three places, a dataset, an audio file) and one APFS clone of a129 disk image;130- 18 generated pictures with resized, recompressed, PNG and edited versions for similar-image analysis;131- a Downloads folder with installers, disk images, archives, an extracted archive and an incomplete download;132- three applications with Library files, and leftovers of two applications that are not installed;133- developer data: DerivedData for three projects, an Xcode archive, device support, simulator caches,134 Homebrew, SwiftPM, npm and pip caches, a `node_modules` and a `.build` folder next to their manifests;135- three files in `.Trash` (one file and a folder of two).136137`Scripts/shot.sh <out.png> <section> [dark|light] [extra args…]` launches an isolated instance on the sample138folder (`ORIX_DEMO_HOME`, default `/tmp/orix-demo/home`), waits `ORIX_WAIT` seconds (default 5) and captures139the window by window id.140141Other `orix-bench` commands are described in `performance.md`.142143## Adding or changing a string1441451. Write the string in code as `L("English text")`, with `%@` and `%d` placeholders where needed. The English146 text is the key.1472. Add the same key with its French translation to `Scripts/translations-fr.json`.1483. Run `Scripts/build.sh generate` (or `python3 Scripts/localize.py`). It rewrites149 `App/Resources/Localizable.xcstrings` (en and fr-CA) and `InfoPlist.xcstrings`.150151`localize.py` fails and lists the problem when a key has no French translation or when the placeholders of the152translation differ from those of the key. `python3 Scripts/localize.py --keys` prints the keys found in the153sources. A key that reaches `L()` through a variable is invisible to the extractor and must be added to the154`EXTRA` list in the script; sidebar group names are an example. Translations of the privacy usage strings are155in the `INFO` dictionary of the same script. At the time of writing the catalogue holds 683 keys.156157## Adding a language158159Not scripted. It would need a second translations file, an extra localization in `localize.py`'s output and160the language added to `CFBundleLocalizations` in `project.yml`.161162## Conventions163164- Every first-party source file starts with the three-line header (file path, description, author);165 `Scripts/check.sh` enforces the author line.166- Engines go in the core package and stay free of UI imports; anything that needs AppKit or SwiftUI goes in167 `App/Sources`.168- Destructive code paths are exercised only on temporary directories and disk images (see `testing.md`).169