feat(build): ship .dmg disk images instead of .zip

Author: Максим Лясковский

.github/workflows/release.yml

@@ -102,11 +102,8 @@ jobs:
       - name: Build LinkBridge.app
         run: ./scripts/build_app.sh
 
-      - name: Package .app as a zip with ditto
-        run: |
-          cd dist
-          ditto -c -k --keepParent LinkBridge.app "LinkBridge-v${{ inputs.version }}.zip"
-          ls -la
+      - name: Package .app as a .dmg with hdiutil
+        run: ./scripts/build_dmg.sh "${{ inputs.version }}"
 
       - name: Create draft GitHub Release
         env:
@@ -117,4 +114,4 @@ jobs:
             --title "LinkBridge v${{ inputs.version }}" \
             --notes-file release-notes.md \
             --draft \
-            "dist/LinkBridge-v${{ inputs.version }}.zip"
+            "dist/LinkBridge-v${{ inputs.version }}.dmg"

CHANGELOG.md

@@ -29,7 +29,7 @@ with a pure-Python macOS menu bar app. The Linux sources are archived under
 - 24 ppqn clock generator with drift-compensated absolute-time scheduling
 - Reactive Ableton Link integration via `aalink` callbacks (no polling)
 - Settings persistence at `~/Library/Application Support/LinkBridge/settings.json`
-- Distributed as a double-clickable `LinkBridge.app` bundle (custom icon, `LSUIElement`)
+- Distributed as a `.dmg` disk image containing the `LinkBridge.app` bundle and a drag-to-install Applications shortcut (custom icon, `LSUIElement`)
 - 22 unit tests covering Settings, MidiOutput, and ClockEngine
 - py2app build via `./scripts/build_app.sh`
 - GitHub Actions CI: tests on every PR, releases via `workflow_dispatch`

README.md

@@ -39,19 +39,37 @@ pip install -r requirements-dev.txt
 ./scripts/build_app.sh
 ```
 
-The bundle is produced at `dist/LinkBridge.app`. Drag it to `/Applications`
-or run it in place.
+The bundle is produced at `dist/LinkBridge.app`. To package it as a
+distributable disk image:
+
+```bash
+./scripts/build_dmg.sh 2.0.0
+```
+
+This produces `dist/LinkBridge-v2.0.0.dmg` containing `LinkBridge.app`
+plus a symlink to `/Applications` for drag-to-install. Releases on
+GitHub Releases ship the `.dmg` exclusively.
+
+**Installation flow:**
+
+- Download `LinkBridge-v<version>.dmg` from the
+  [latest release](https://github.com/AnyByte/LinkBridge/releases/latest)
+- Double-click the `.dmg` to mount it
+- Drag `LinkBridge.app` onto the `Applications` shortcut in the disk
+  image window
+- Eject the disk image
+- Launch from `/Applications`
 
 **On first launch:**
 
+- The bundle is **unsigned** (no Apple Developer ID). macOS Gatekeeper
+  may block it the first time — right-click the `.app` in Finder, choose
+  **Open**, confirm the warning, then launch normally afterwards.
 - macOS asks for **local network permission** ("Allow LinkBridge to find
   devices on local networks?"). Click **Allow**, otherwise Ableton Link
   cannot discover any peers and the tempo stays at the default 120 BPM
   forever. The bundle includes a description string explaining what the
   permission is used for.
-- The bundle is **unsigned** (no Apple Developer ID). If macOS Gatekeeper
-  blocks it, right-click the `.app` in Finder, choose **Open**, confirm
-  the warning, then launch normally afterwards.
 
 ## Menu reference
 

scripts/build_dmg.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Package dist/LinkBridge.app into dist/LinkBridge-v<version>.dmg using hdiutil.
+#
+# Usage:
+#   ./scripts/build_dmg.sh <version>
+#
+# Requires that ./scripts/build_app.sh has already produced dist/LinkBridge.app.
+# The resulting .dmg, when mounted, shows a Finder window with LinkBridge.app
+# next to a symlink to /Applications so the user can drag-to-install.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+VERSION="${1:-}"
+if [[ -z "$VERSION" ]]; then
+    echo "usage: $0 <version>" >&2
+    exit 2
+fi
+
+APP="dist/LinkBridge.app"
+DMG="dist/LinkBridge-v${VERSION}.dmg"
+
+if [[ ! -d "$APP" ]]; then
+    echo "error: $APP not found. Run ./scripts/build_app.sh first." >&2
+    exit 1
+fi
+
+rm -f "$DMG"
+
+# Build the contents of the disk image in a temp directory: the .app plus a
+# symlink to /Applications so the user can drag-to-install visually.
+STAGE=$(mktemp -d -t linkbridge-dmg)
+trap 'rm -rf "$STAGE"' EXIT
+
+ditto "$APP" "$STAGE/LinkBridge.app"
+ln -s /Applications "$STAGE/Applications"
+
+hdiutil create \
+    -volname "LinkBridge" \
+    -srcfolder "$STAGE" \
+    -ov \
+    -format UDZO \
+    "$DMG" >/dev/null
+
+echo "Built: $DMG"
+ls -lh "$DMG"