Homebrew primer

Why Homebrew

Homebrew is the de-facto package manager for macOS. Publishing a cask or formula lets users install Nimbus with a single command. No manual .dmg downloads, no Gatekeeper warnings when bottles are signed, and `brew upgrade` handles updates automatically.

Formula vs Cask

A formula builds from source or installs a precompiled bottle. Use this when you distribute a raw binary or CLI tool. A cask wraps a .app bundle, .pkg installer, or .dmg — the right choice for the Nimbus GUI. Casks live in the homebrew-cask repo and require only a Ruby DSL file.

Anatomy of a cask

cask "nimbus" do
  version "2.1.0"
  sha256 "abc123..."

  url "https://getnimbus.net/dl/macos/nimbus-#{version}.dmg"
  name "Nimbus"
  desc "Premium system utility"
  homepage "https://getnimbus.net"

  app "Nimbus.app"

  zap trash: [
    "~/Library/Application Support/Nimbus",
    "~/Library/Preferences/com.fooglegiber.nimbus.plist",
  ]
end

The zap stanza cleans up leftovers on uninstall. Always include it.

Submitting to homebrew-cask

1. Fork Homebrew/homebrew-cask on GitHub.
2. Place your nimbus.rb in Casks/n/.
3. Run brew audit --cask nimbus locally.
4. Open a PR. Maintainers will verify the download, checksum, and app structure.
5. Once merged, users can run brew install --cask nimbus immediately.

Private tap alternative

If you prefer not to go through public review, host a private tap. Create a GitHub repo named homebrew-nimbus with a Casks/nimbus.rb file. Users tap it once:

brew tap fooglegiber/nimbus brew install --cask nimbus

Private taps skip audit requirements but you lose discoverability.

Code-signing & notarization

Homebrew does not notarize on your behalf. Before shipping a .dmg, sign with your Developer ID certificate and submit to Apple notary service. Unsigned casks trigger Gatekeeper and erode trust. Use xcrun notarytool submit and staple the ticket.

Auto-updates

Casks with a version and url using #{version} are picked up by brew livecheck. Pair with a GitHub release pipeline that updates the cask file on each tag push. Users get seamless upgrades via brew upgrade.