40 lines
2.6 KiB
Markdown
40 lines
2.6 KiB
Markdown
---
|
||
summary: "Signing steps for macOS debug builds generated by packaging scripts"
|
||
read_when:
|
||
- Building or signing mac debug builds
|
||
---
|
||
# mac signing (debug builds)
|
||
|
||
This app is usually built from `scripts/package-mac-app.sh`, which now:
|
||
|
||
- sets a stable debug bundle identifier: `com.clawdis.mac.debug`
|
||
- writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
|
||
- calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). Requires a valid signing identity.
|
||
- uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
|
||
- inject build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
|
||
- **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
|
||
- reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert; otherwise signing falls back to ad‑hoc.
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
# from repo root
|
||
scripts/package-mac-app.sh # ad-hoc signing
|
||
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh # real cert
|
||
```
|
||
|
||
### Ad-hoc Signing Note
|
||
When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID.
|
||
|
||
## Build metadata for About
|
||
|
||
`package-mac-app.sh` stamps the bundle with:
|
||
- `ClawdisBuildTimestamp`: ISO8601 UTC at package time
|
||
- `ClawdisGitCommit`: short git hash (or `unknown` if unavailable)
|
||
|
||
The About tab reads these keys to show version, build date, git commit, and whether it’s a debug build (via `#if DEBUG`). Run the packager to refresh these values after code changes.
|
||
|
||
## Why
|
||
|
||
TCC permissions are tied to the bundle identifier *and* code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Signing the binaries (ad‑hoc by default) and keeping a fixed bundle id/path (`dist/Clawdis.app`) preserves the grants between builds, matching the VibeTunnel approach.
|