Files
routine/docs/building-the-mac-app.md

3.8 KiB

Building Routine.dmg on a Mac (once, for everyone)

install-mac.sh is the way to install Routine on a Mac today: one line in Terminal. A .dmg you open and drag to Applications is friendlier, but it has to be built on a Mac, and nobody has run the build yet. If you have a Mac, this is how to build it once and send it back, so it can be put up for download. Untested so far: if any step fails, send the whole Terminal output.

What you need

  • macOS 13 (Ventura) or newer. The app you build runs on the same kind of Mac as yours: on an Apple-silicon Mac (M1 and later) you build the Apple-silicon version; on an Intel Mac, the Intel one. (Both are welcome.)
  • About 2 GB of free space and an internet connection. No Xcode, Homebrew or admin password.

Build it

In Terminal (⌘ Space, type Terminal):

cd ~/Downloads
curl -fsSL https://git.autonomic.zone/trav/routine/archive/main.tar.gz | tar -xzf -
cd routine
scripts/build-mac-app.sh

It downloads uv, a Python and the packages into build/mac/ (nothing outside this folder), freezes the app with PyInstaller, signs it ad hoc and makes the disk image. At the end it prints

Done: …/routine/dist/Routine-<version>.dmg (… MB), for arm64 Macs.

Check it, then send it

  1. Open dist/Routine-<version>.dmg: a window shows Routine and an Applications folder.
  2. Drag Routine onto Applications, eject the disk image, open Routine from Launchpad.
  3. Walk through docs/mac-testing.md from step 2 (skip step 1's install line, and in step 9 remove it by dragging Routine from Applications to the Bin).
  4. Send dist/Routine-<version>.dmg (it's too big for most email: a file-sharing link is fine), with the last lines the build printed and your macOS version and chip.

To start over: delete build/ and dist/ and run the script again.

What people see when they open it: Gatekeeper

The app is signed "ad hoc" (codesign -s -), not with an Apple Developer ID, and it isn't notarized by Apple (that needs a paid developer account). So the first time someone opens a copy they downloaded, macOS stops it. It only happens once per copy.

macOS 15 Sequoia and newer:

  1. Double-clicking says "Routine" Not Opened: Apple could not verify "Routine" is free of malware that may harm your Mac or compromise your privacy. Click Done (not Move to Bin).
  2. Open System Settings → Privacy & Security, scroll down to Security: it says "Routine" was blocked to protect your Mac. Click Open Anyway, then enter your password.
  3. Open Routine again and click Open Anyway in the box that appears. From then on it opens normally.

macOS 13 Ventura and 14 Sonoma: right-click (or Control-click) Routine in Applications → Open, then Open in the box that appears. (Or the System Settings route above.)

In Terminal, any version (for people comfortable with it): after dragging it to Applications,

xattr -dr com.apple.quarantine /Applications/Routine.app

and it opens without the warning.

The one-line installer (install-mac.sh) doesn't hit any of this: it builds the app on the Mac itself, and nothing it downloads is marked as "from the internet".

Notes for whoever maintains this

  • The script pins uv, Python 3.13, PySide6-Essentials and PyInstaller (scripts/build-mac-app.sh). PySide6-Essentials has no Qt Multimedia, so sounds play through macOS's own afplay.
  • The data the app keeps is outside the bundle (~/Library/Application Support/Routine), so the .dmg app and the installer's app can replace each other freely.
  • Real signing + notarization later: a Developer ID certificate in place of -, then xcrun notarytool submit … --wait and xcrun stapler staple on the .dmg.
  • The freezing part was tried on Linux (BUILD_TEST=1: it builds and runs); the .app, plutil, codesign and hdiutil steps have never run.