SPB Git

Repository Public

distribution.md 13.4 KB

# Distribution

This 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.

Related pages: signing, notarization, release checklist, development setup, brand guidelines.

# What is distributed

ORIX 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.

Artifact Path Content
Disk image dist/ORIX-DJ-<version>.dmg the stapled app, an Applications shortcut and a background image; signed, notarized and stapled itself
ZIP archive dist/ORIX-DJ-<version>.zip the stapled app (ditto -c -k --keepParent)
Checksums dist/SHA256SUMS.txt SHA-256 of the disk image and the ZIP
Release description dist/release.json name, bundle identifier, version, build, minimum macOS, architectures, notarization submissions and statuses, file sizes and checksums
Application dist/ORIX DJ.app the signed, stapled bundle the two archives were made from

<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.

# The pipeline

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".

flowchart TD
    A["check.sh: repository hygiene"] --> B["build.sh core-test: swift test --no-parallel"]
    B --> C["sign.sh: Release build, Developer ID, Hardened Runtime"]
    C --> D["sign.sh: codesign verify, runtime flag, no get-task-allow, icon, docs"]
    D --> E["notarize.sh app: notarytool submit and wait"]
    E --> F{"Status Accepted?"}
    F -- no --> X["Stop: exit 3, read build/notary/app-log.json"]
    F -- yes --> G["stapler staple and validate the app"]
    G --> H["package.sh: DMG with create-dmg, codesign DMG, ZIP"]
    H --> I["notarize.sh dmg: notarytool submit and wait"]
    I --> J{"Status Accepted?"}
    J -- no --> Y["Stop: exit 3, read build/notary/dmg-log.json"]
    J -- yes --> K["stapler staple and validate the DMG"]
    K --> L["finalize.sh: spctl on app, DMG and app from ZIP"]
    L --> M["finalize.sh: SHA256SUMS.txt and release.json"]
    M --> N["Manual gates: clean machine, listening, VoiceOver, hardware"]
    N --> O["Publication: to be completed at release time"]
Order Command in release.sh Documented in
1 Scripts/check.sh development setup
2 Scripts/build.sh core-test testing
3 Scripts/sign.sh signing
4 Scripts/notarize.sh "dist/ORIX DJ.app" app notarization
5 Scripts/package.sh this page
6 Scripts/notarize.sh "dist/ORIX-DJ-$VERSION.dmg" dmg notarization
7 Scripts/finalize.sh this page

Status 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.

Each 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.

# Packaging: Scripts/package.sh

Step Action
1 Require dist/ORIX DJ.app to exist
2 Require xcrun stapler validate to succeed on it; otherwise exit 1 with "the app is not notarized and stapled yet (Scripts/notarize.sh)"
3 Read version and build from the bundle's Info.plist with PlistBuddy
4 Read the signing identity back from the app: first Authority=Developer ID Application: ... line of codesign -dvv
5 Remove any previous dist/ORIX-DJ-<version>.dmg and .zip
6 Render the background: swift Scripts/dmg-background.swift build/dmg-background.png
7 Copy the app with ditto into a temporary staging directory
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
9 Remove the staging directory
10 Sign the disk image: codesign --force --timestamp --sign "$IDENTITY" "$DMG"
11 Build the ZIP from the stapled app: ditto -c -k --keepParent "dist/ORIX DJ.app" "$ZIP"
12 Print the result and the next step: notarize the disk image, then run Scripts/finalize.sh

Because the application is stapled before step 7, both archives contain an app that passes Gatekeeper without a network connection.

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

# Disk image layout

The create-dmg invocation fixes the layout:

Property Value
Volume name ORIX DJ <version>
Window position 200, 140
Window size 660 x 420 points
Background build/dmg-background.png
Icon size 128
ORIX DJ.app icon centred at 170, 205; extension hidden
Applications drop link centred at 490, 205
Other options --no-internet-enable

# Background image: Scripts/dmg-background.swift

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

  • a vertical gradient from sRGB (0.10, 0.13, 0.26) to (0.03, 0.04, 0.09);
  • a radial violet glow (0.49, 0.36, 0.99 at 24 % opacity) centred at 330, 215 with radius 330;
  • "ORIX DJ" in 26 pt bold near the top and the tagline "Mix the Music. Program the Experience." in 13 pt below it;
  • an arrow from x = 285 to x = 372 at y = 215, between the two icon positions, stroked 5 pt in light violet;
  • "Drag ORIX DJ to the Applications folder" in 13 pt medium near the bottom.

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

# Final verification: Scripts/finalize.sh

This script runs after the disk image has been notarized and stapled. It reads version, build and minimum system version from the bundle, then:

Step Command Purpose
1 spctl --assess --type execute --verbose=2 "dist/ORIX DJ.app" Gatekeeper assessment of the application
2 spctl --assess --type open --context context:primary-signature --verbose=2 "$DMG" Gatekeeper assessment of the disk image
3 xcrun stapler validate on the app and on the disk image both tickets present
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
5 shasum -a 256 of the disk image and the ZIP, written to dist/SHA256SUMS.txt checksums
6 Read the submission IDs from build/notary/app.json and build/notary/dmg.json
7 Write dist/release.json machine-readable description

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.

A 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.

# Results of the release run

Nothing below has been produced yet.

Item Value
Version (build) 1.0.0 (1)
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)
ORIX-DJ-<version>.dmg size 7,383,880 bytes
ORIX-DJ-<version>.dmg SHA-256 ec9de1ab4f05c7f8ae7f5122202de6e9ee0ec8e92444e6f0b13941b984208ee2
ORIX-DJ-<version>.zip size 6,308,251 bytes
ORIX-DJ-<version>.zip SHA-256 63026b4e44b86ea2a58a44e6e617e2def6746de5aee0b1c6851c27a221393873
Architectures arm64

Gatekeeper output of finalize.sh:

text
spctl --assess (app, DMG, app extracted from the ZIP) and stapler validate
text
dist/ORIX DJ.app: accepted
source=Notarized Developer ID
origin=Developer ID Application: (owner)
dist/ORIX-DJ-1.0.0.dmg: accepted
source=Notarized Developer ID
origin=Developer ID Application: (owner)
build/relout/zip/ORIX DJ.app: accepted
source=Notarized Developer ID
origin=Developer ID Application: (owner)
Processing: build/relout/zip/ORIX DJ.app
The validate action worked!

ec9de1ab4f05c7f8ae7f5122202de6e9ee0ec8e92444e6f0b13941b984208ee2  ORIX-DJ-1.0.0.dmg
63026b4e44b86ea2a58a44e6e617e2def6746de5aee0b1c6851c27a221393873  ORIX-DJ-1.0.0.zip

Content of dist/release.json:

json
{
 "name": "ORIX DJ",
 "bundleIdentifier": "ai.spboucher.orix.dj",
 "version": "1.0.0",
 "build": "1",
 "minimumMacOS": "15.0",
 "architectures": [
  "arm64"
 ],
 "signing": "Developer ID Application, Hardened Runtime",
 "notarization": {
  "app": {
   "submission": "eafc4e24-d278-4460-8cef-0d7827e2481e",
   "status": "Accepted"
  },
  "dmg": {
   "submission": "4c301728-4b75-4c88-b3b2-831d986bcbaa",
   "status": "Accepted"
  }
 },
 "artifacts": [
  {
   "file": "ORIX-DJ-1.0.0.dmg",
   "bytes": 7383880,
   "sha256": "ec9de1ab4f05c7f8ae7f5122202de6e9ee0ec8e92444e6f0b13941b984208ee2"
  },
  {
   "file": "ORIX-DJ-1.0.0.zip",
   "bytes": 6308251,
   "sha256": "63026b4e44b86ea2a58a44e6e617e2def6746de5aee0b1c6851c27a221393873"
  }
 ]
}

# Publication

No 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.

What can be stated from the repository alone:

  • The files meant for publication are dist/ORIX-DJ-<version>.dmg, dist/ORIX-DJ-<version>.zip, dist/SHA256SUMS.txt and dist/release.json.
  • 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.
  • Publication should happen only after the manual gates of the checklist, in particular a first launch of the downloaded disk image on a Mac other than the build machine.
Item Value
Release URL https://git.spboucher.ai/releases/orix-dj/v1.0.0/ (published 2026-11-21 on the owner's instruction)
Tag v1.0.0 in https://git.spboucher.ai/orix-dj
Published assets ORIX-DJ-1.0.0.dmg, ORIX-DJ-1.0.0.zip, SHA256SUMS.txt, RELEASE-NOTES.md, each with a .sha256 file

# Installation as the user sees it

Open 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). 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.

Files main
Menu

Theme