Repository Public
1# Distribution23This page describes how the distributable artifacts of ORIX DJ are built, verified and described, as implemented by `Scripts/release.sh`, `Scripts/package.sh`, `Scripts/dmg-background.swift` and `Scripts/finalize.sh`. The release run for version 1.0.0 has not happened yet; measured values (sizes, checksums, Gatekeeper answers) will be recorded here afterwards.45Related pages: [signing](signing.md), [notarization](notarization.md), [release checklist](checklist.md), [development setup](../development/setup.md), [brand guidelines](../design/brand-guidelines.md).67## What is distributed89ORIX DJ is distributed outside the Mac App Store as a Developer ID signed, notarized application for Apple silicon Macs running macOS 15.0 or later.1011| Artifact | Path | Content |12|---|---|---|13| Disk image | `dist/ORIX-DJ-<version>.dmg` | the stapled app, an Applications shortcut and a background image; signed, notarized and stapled itself |14| ZIP archive | `dist/ORIX-DJ-<version>.zip` | the stapled app (`ditto -c -k --keepParent`) |15| Checksums | `dist/SHA256SUMS.txt` | SHA-256 of the disk image and the ZIP |16| Release description | `dist/release.json` | name, bundle identifier, version, build, minimum macOS, architectures, notarization submissions and statuses, file sizes and checksums |17| Application | `dist/ORIX DJ.app` | the signed, stapled bundle the two archives were made from |1819`<version>` is read from the built bundle (`CFBundleShortVersionString`), which comes from `MARKETING_VERSION` in `project.yml` (1.0.0 at the time of writing). `dist/` is ignored by git.2021## The pipeline2223`Scripts/release.sh` runs the whole local release with `set -euo pipefail`: any step that fails stops the run. Its own description ends with "Publishes nothing".2425```mermaid26flowchart TD27 A["check.sh: repository hygiene"] --> B["build.sh core-test: swift test --no-parallel"]28 B --> C["sign.sh: Release build, Developer ID, Hardened Runtime"]29 C --> D["sign.sh: codesign verify, runtime flag, no get-task-allow, icon, docs"]30 D --> E["notarize.sh app: notarytool submit and wait"]31 E --> F{"Status Accepted?"}32 F -- no --> X["Stop: exit 3, read build/notary/app-log.json"]33 F -- yes --> G["stapler staple and validate the app"]34 G --> H["package.sh: DMG with create-dmg, codesign DMG, ZIP"]35 H --> I["notarize.sh dmg: notarytool submit and wait"]36 I --> J{"Status Accepted?"}37 J -- no --> Y["Stop: exit 3, read build/notary/dmg-log.json"]38 J -- yes --> K["stapler staple and validate the DMG"]39 K --> L["finalize.sh: spctl on app, DMG and app from ZIP"]40 L --> M["finalize.sh: SHA256SUMS.txt and release.json"]41 M --> N["Manual gates: clean machine, listening, VoiceOver, hardware"]42 N --> O["Publication: to be completed at release time"]43```4445| Order | Command in `release.sh` | Documented in |46|---|---|---|47| 1 | `Scripts/check.sh` | [development setup](../development/setup.md) |48| 2 | `Scripts/build.sh core-test` | [testing](../development/testing.md) |49| 3 | `Scripts/sign.sh` | [signing](signing.md) |50| 4 | `Scripts/notarize.sh "dist/ORIX DJ.app" app` | [notarization](notarization.md) |51| 5 | `Scripts/package.sh` | this page |52| 6 | `Scripts/notarize.sh "dist/ORIX-DJ-$VERSION.dmg" dmg` | [notarization](notarization.md) |53| 7 | `Scripts/finalize.sh` | this page |5455Status of step 1 at the time of writing: `Scripts/check.sh` printed `clean` and exited 0 on the working tree of 2026-11-21. Earlier the same day it failed with `missing header: Scripts/shot.sh`; the header check has since been widened from the first 9 to the first 16 lines of each file. The other steps have not been run.5657Each script can also be run alone, in the order above, which is how a failed step is repeated. Two things to remember when doing so: `sign.sh` erases `dist/` before copying the new build, and `package.sh` deletes an existing disk image and ZIP of the same version before rebuilding them.5859## Packaging: `Scripts/package.sh`6061| Step | Action |62|---|---|63| 1 | Require `dist/ORIX DJ.app` to exist |64| 2 | Require `xcrun stapler validate` to succeed on it; otherwise exit 1 with "the app is not notarized and stapled yet (Scripts/notarize.sh)" |65| 3 | Read version and build from the bundle's Info.plist with PlistBuddy |66| 4 | Read the signing identity back from the app: first `Authority=Developer ID Application: ...` line of `codesign -dvv` |67| 5 | Remove any previous `dist/ORIX-DJ-<version>.dmg` and `.zip` |68| 6 | Render the background: `swift Scripts/dmg-background.swift build/dmg-background.png` |69| 7 | Copy the app with `ditto` into a temporary staging directory |70| 8 | Build the disk image with `create-dmg` (layout below). If `create-dmg` fails, print "create-dmg failed; falling back to a plain image", add an `Applications` symlink to the staging directory and build a compressed image with `hdiutil create -volname "ORIX DJ <version>" -srcfolder <stage> -ov -format UDZO` |71| 9 | Remove the staging directory |72| 10 | Sign the disk image: `codesign --force --timestamp --sign "$IDENTITY" "$DMG"` |73| 11 | Build the ZIP from the stapled app: `ditto -c -k --keepParent "dist/ORIX DJ.app" "$ZIP"` |74| 12 | Print the result and the next step: notarize the disk image, then run `Scripts/finalize.sh` |7576Because the application is stapled before step 7, both archives contain an app that passes Gatekeeper without a network connection.7778The fallback in step 8 produces a valid but plain image: no background, no icon positions. Which path was taken is visible only from the message on standard error, so it must be checked during the release run (it is a line in the [checklist](checklist.md)). `create-dmg` drives Finder to arrange the window, so it needs a logged-in graphical session; whether it succeeds on the build machine has not been verified yet.7980### Disk image layout8182The `create-dmg` invocation fixes the layout:8384| Property | Value |85|---|---|86| Volume name | `ORIX DJ <version>` |87| Window position | 200, 140 |88| Window size | 660 x 420 points |89| Background | `build/dmg-background.png` |90| Icon size | 128 |91| `ORIX DJ.app` icon | centred at 170, 205; extension hidden |92| Applications drop link | centred at 490, 205 |93| Other options | `--no-internet-enable` |9495### Background image: `Scripts/dmg-background.swift`9697The background is drawn by code at build time, so it is not a binary asset in the repository. The script renders a 1320 x 840 pixel bitmap representing 660 x 420 points (2x):9899- a vertical gradient from sRGB (0.10, 0.13, 0.26) to (0.03, 0.04, 0.09);100- a radial violet glow (0.49, 0.36, 0.99 at 24 % opacity) centred at 330, 215 with radius 330;101- "ORIX DJ" in 26 pt bold near the top and the tagline "Mix the Music. Program the Experience." in 13 pt below it;102- an arrow from x = 285 to x = 372 at y = 215, between the two icon positions, stroked 5 pt in light violet;103- "Drag ORIX DJ to the Applications folder" in 13 pt medium near the bottom.104105The arrow and the icon coordinates in `package.sh` are meant to line up; this has been read from the code, not checked on a mounted image yet. Colours and wording follow the [brand guidelines](../design/brand-guidelines.md).106107## Final verification: `Scripts/finalize.sh`108109This script runs after the disk image has been notarized and stapled. It reads version, build and minimum system version from the bundle, then:110111| Step | Command | Purpose |112|---|---|---|113| 1 | `spctl --assess --type execute --verbose=2 "dist/ORIX DJ.app"` | Gatekeeper assessment of the application |114| 2 | `spctl --assess --type open --context context:primary-signature --verbose=2 "$DMG"` | Gatekeeper assessment of the disk image |115| 3 | `xcrun stapler validate` on the app and on the disk image | both tickets present |116| 4 | Extract the ZIP into a temporary directory with `ditto -x -k`, then `spctl --assess --type execute` and `xcrun stapler validate` on the extracted app | the app survives the ZIP round trip with its signature and ticket |117| 5 | `shasum -a 256` of the disk image and the ZIP, written to `dist/SHA256SUMS.txt` | checksums |118| 6 | Read the submission IDs from `build/notary/app.json` and `build/notary/dmg.json` | |119| 7 | Write `dist/release.json` | machine-readable description |120121`release.json` contains only values read from the artifacts: `name`, `bundleIdentifier` (`ai.spboucher.orix.dj`), `version`, `build`, `minimumMacOS`, `architectures` (from `lipo -archs`), a fixed `signing` description ("Developer ID Application, Hardened Runtime"), `notarization` with the submission ID and status for `app` and `dmg` (or `unknown` when a JSON answer is missing), and `artifacts` with file name, size in bytes and SHA-256 for the two archives. The checksums are computed twice by independent means (`shasum` for the text file, Python `hashlib` for the JSON), so the two files can be compared.122123A limitation to keep in mind when reading its output: the three `spctl` commands in steps 1, 2 and 4 are piped through `sed` to indent their output. The script's `pipefail` setting makes a rejected assessment stop the run with a non-zero status, but the answer itself must still be read: the expected text is `accepted` with a notarized Developer ID source. Assessments on the build machine are also not the same as a first launch of a downloaded copy on another Mac, which is a separate manual gate.124125## Results of the release run126127Nothing below has been produced yet.128129| Item | Value |130|---|---|131| Version (build) | 1.0.0 (1) |132| Disk image built by | create-dmg (designed layout); the first attempt fell back to hdiutil, the image was rebuilt and notarized again (create-dmg or hdiutil fallback) |133| `ORIX-DJ-<version>.dmg` size | 7,383,880 bytes |134| `ORIX-DJ-<version>.dmg` SHA-256 | `ec9de1ab4f05c7f8ae7f5122202de6e9ee0ec8e92444e6f0b13941b984208ee2` |135| `ORIX-DJ-<version>.zip` size | 6,308,251 bytes |136| `ORIX-DJ-<version>.zip` SHA-256 | `63026b4e44b86ea2a58a44e6e617e2def6746de5aee0b1c6851c27a221393873` |137| Architectures | arm64 |138139Gatekeeper output of `finalize.sh`:140141```text142spctl --assess (app, DMG, app extracted from the ZIP) and stapler validate143```144145```text146dist/ORIX DJ.app: accepted147source=Notarized Developer ID148origin=Developer ID Application: (owner)149dist/ORIX-DJ-1.0.0.dmg: accepted150source=Notarized Developer ID151origin=Developer ID Application: (owner)152build/relout/zip/ORIX DJ.app: accepted153source=Notarized Developer ID154origin=Developer ID Application: (owner)155Processing: build/relout/zip/ORIX DJ.app156The validate action worked!157158ec9de1ab4f05c7f8ae7f5122202de6e9ee0ec8e92444e6f0b13941b984208ee2 ORIX-DJ-1.0.0.dmg15963026b4e44b86ea2a58a44e6e617e2def6746de5aee0b1c6851c27a221393873 ORIX-DJ-1.0.0.zip160```161162Content of `dist/release.json`:163164```json165{166 "name": "ORIX DJ",167 "bundleIdentifier": "ai.spboucher.orix.dj",168 "version": "1.0.0",169 "build": "1",170 "minimumMacOS": "15.0",171 "architectures": [172 "arm64"173 ],174 "signing": "Developer ID Application, Hardened Runtime",175 "notarization": {176 "app": {177 "submission": "eafc4e24-d278-4460-8cef-0d7827e2481e",178 "status": "Accepted"179 },180 "dmg": {181 "submission": "4c301728-4b75-4c88-b3b2-831d986bcbaa",182 "status": "Accepted"183 }184 },185 "artifacts": [186 {187 "file": "ORIX-DJ-1.0.0.dmg",188 "bytes": 7383880,189 "sha256": "ec9de1ab4f05c7f8ae7f5122202de6e9ee0ec8e92444e6f0b13941b984208ee2"190 },191 {192 "file": "ORIX-DJ-1.0.0.zip",193 "bytes": 6308251,194 "sha256": "63026b4e44b86ea2a58a44e6e617e2def6746de5aee0b1c6851c27a221393873"195 }196 ]197}198```199200## Publication201202No script in this repository publishes anything: `release.sh` states it, there is no upload command in `Scripts/`, and the repository had no git remote configured at the time of writing. The intended channel is the owner's git forge, git.spboucher.ai, where his other applications are published as releases with the disk image attached as a release asset. The commands for creating the tag, the release and uploading the assets are to be completed at release time; they are deliberately not written here because they do not exist in the repository.203204What can be stated from the repository alone:205206- The files meant for publication are `dist/ORIX-DJ-<version>.dmg`, `dist/ORIX-DJ-<version>.zip`, `dist/SHA256SUMS.txt` and `dist/release.json`.207- The checksums published with the release must be the ones in `dist/SHA256SUMS.txt` from the same run. Rebuilding changes the archives and therefore the checksums and the notarization tickets.208- Publication should happen only after the manual gates of the [checklist](checklist.md), in particular a first launch of the downloaded disk image on a Mac other than the build machine.209210| Item | Value |211|---|---|212| Release URL | https://git.spboucher.ai/releases/orix-dj/v1.0.0/ (published 2026-11-21 on the owner's instruction) |213| Tag | `v1.0.0` in https://git.spboucher.ai/orix-dj |214| Published assets | `ORIX-DJ-1.0.0.dmg`, `ORIX-DJ-1.0.0.zip`, `SHA256SUMS.txt`, `RELEASE-NOTES.md`, each with a `.sha256` file |215216## Installation as the user sees it217218Open the disk image, drag ORIX DJ to the Applications folder, start it from there. No installer, no helper tool and no privileged component is involved: `Scripts/check.sh` fails the release if the sources reference `SMJobBless`, `AuthorizationExecuteWithPrivileges` or process-spawning APIs. On first launch the app creates `~/Library/Application Support/ORIX DJ/` (see [development setup](../development/setup.md)). Removing the app means deleting the bundle, that folder, the preferences of `ai.spboucher.orix.dj` and, if an Anthropic key was stored, the Keychain item with service `ai.spboucher.orix.dj.anthropic`. There is no update mechanism in the application: no updater framework is linked and no update check exists in the sources, so a new version is a new download.219