macOS SwiftPM App Packaging (No Xcode)
Overview
Bootstrap a complete SwiftPM macOS app folder, then build, package, and run it without Xcode. Use assets/templates/bootstrap/ for the starter layout and references/packaging.md + references/release.md for packaging and release details.
Two-Step Workflow
Bootstrap the project folder
- Copy
assets/templates/bootstrap/ into a new repo.
- Rename
MyApp in Package.swift, Sources/MyApp/, and version.env.
- Customize
APP_NAME, BUNDLE_ID, and versions.
Build, package, and run the bootstrapped app
- Copy scripts from
assets/templates/ into your repo (for example, Scripts/).
- Build/tests:
swift build and swift test.
- Package:
Scripts/package_app.sh.
- Run:
Scripts/compile_and_run.sh (preferred) or Scripts/launch.sh.
- Release (optional):
Scripts/sign-and-notarize.sh and Scripts/make_appcast.sh.
- Tag + GitHub release (optional): create a git tag, upload the zip/appcast to the GitHub release, and publish.
Minimum End-to-End Example
Shortest path from bootstrap to a running app:
# 1. Copy and rename the skeleton
cp -R assets/templates/bootstrap/ ~/Projects/MyApp
cd ~/Projects/MyApp
sed -i '' 's/MyApp/HelloApp/g' Package.swift version.env
# 2. Copy scripts
cp assets/templates/package_app.sh Scripts/
cp assets/templates/compile_and_run.sh Scripts/
chmod +x Scripts/*.sh
# 3. Build and launch
swift build
Scripts/compile_and_run.sh
Validation Checkpoints
Run these after key steps to catch failures early before proceeding to the next stage.
After packaging (Scripts/package_app.sh):
# Confirm .app bundle structure is intact
ls -R build/HelloApp.app/Contents
# Check that the binary is present and executable
file build/HelloApp.app/Contents/MacOS/HelloApp
After signing (Scripts/sign-and-notarize.sh or ad-hoc dev signing):
# Inspect signature and entitlements
codesign -dv --verbose=4 build/HelloApp.app
# Verify the bundle passes Gatekeeper checks locally
spctl --assess --type execute --verbose build/HelloApp.app
After notarization and stapling:
# Confirm the staple ticket is attached
stapler validate build/HelloApp.app
# Re-run Gatekeeper to confirm notarization is recognised
spctl --assess --type execute --verbose build/HelloApp.app
Common Notarization Failures
| Symptom |
Likely Cause |
Recovery |
The software asset has already been uploaded |
Duplicate submission for same version |
Bump BUILD_NUMBER in version.env and repackage. |
Package Invalid: Invalid Code Signing Entitlements |
Entitlements in .entitlements file don't match provisioning |
Audit entitlements against Apple's allowed set; remove unsupported keys. |
The executable does not have the hardened runtime enabled |
Missing --options runtime flag in codesign invocation |
Edit sign-and-notarize.sh to add --options runtime to all codesign calls. |
| Notarization hangs / no status email |
xcrun notarytool network or credential issue |
Run xcrun notarytool history to check status; re-export App Store Connect API key if expired. |
stapler validate fails after successful notarization |
Ticket not yet propagated |
Wait ~60 s, then re-run xcrun stapler staple. |
Templates
assets/templates/package_app.sh: Build binaries, create the .app bundle, copy resources, sign.assets/templates/compile_and_run.sh: Dev loop to kill running app, package, launch.assets/templates/build_icon.sh: Generate .icns from an Icon Composer file (requires Xcode install).assets/templates/sign-and-notarize.sh: Notarize, staple, and zip a release build.assets/templates/make_appcast.sh: Generate Sparkle appcast entries for updates.assets/templates/setup_dev_signing.sh: Create a stable dev code-signing identity.assets/templates/launch.sh: Simple launcher for a packaged .app.assets/templates/version.env: Example version file consumed by packaging scripts.assets/templates/bootstrap/: Minimal SwiftPM macOS app skeleton (Package.swift, Sources/, version.env).
Notes
- Keep entitlements and signing configuration explicit; edit the template scripts instead of reimplementing.
- Remove Sparkle steps if you do not use Sparkle for updates.
- Sparkle relies on the bundle build number (
CFBundleVersion), so BUILD_NUMBER in version.env must increase for each update.
- For menu bar apps, set
MENU_BAR_APP=1 when packaging to emit LSUIElement in Info.plist.
1---
2name: macos-spm-app-packaging
3description: >-
4 Scaffold, build, and package SwiftPM-based macOS apps without Xcode project. Use when: creating macOS app bundles from SPM, signing, notarizing, or building appcasts.
5license: MIT
6compatibility: "macOS with Swift Package Manager"
7metadata:
8 author: terminal-skills
9 version: "1.0.0"
10 category: development
11 tags: [macos, spm, packaging, distribution, notarization]
12 use-cases:
13 - "Package a SwiftPM app into a signed .app bundle"
14 - "Set up notarization and appcast for macOS distribution"
15 agents: [claude-code, openai-codex, gemini-cli, cursor]
16---
17
18# macOS SwiftPM App Packaging (No Xcode)
19
20## Overview
21Bootstrap a complete SwiftPM macOS app folder, then build, package, and run it without Xcode. Use `assets/templates/bootstrap/` for the starter layout and `references/packaging.md` + `references/release.md` for packaging and release details.
22
23## Two-Step Workflow
241) Bootstrap the project folder
25 - Copy `assets/templates/bootstrap/` into a new repo.
26 - Rename `MyApp` in `Package.swift`, `Sources/MyApp/`, and `version.env`.
27 - Customize `APP_NAME`, `BUNDLE_ID`, and versions.
28
292) Build, package, and run the bootstrapped app
30 - Copy scripts from `assets/templates/` into your repo (for example, `Scripts/`).
31 - Build/tests: `swift build` and `swift test`.
32 - Package: `Scripts/package_app.sh`.
33 - Run: `Scripts/compile_and_run.sh` (preferred) or `Scripts/launch.sh`.
34 - Release (optional): `Scripts/sign-and-notarize.sh` and `Scripts/make_appcast.sh`.
35 - Tag + GitHub release (optional): create a git tag, upload the zip/appcast to the GitHub release, and publish.
36
37## Minimum End-to-End Example
38Shortest path from bootstrap to a running app:
39```bash
40# 1. Copy and rename the skeleton
41cp -R assets/templates/bootstrap/ ~/Projects/MyApp
42cd ~/Projects/MyApp
43sed -i '' 's/MyApp/HelloApp/g' Package.swift version.env
44
45# 2. Copy scripts
46cp assets/templates/package_app.sh Scripts/
47cp assets/templates/compile_and_run.sh Scripts/
48chmod +x Scripts/*.sh
49
50# 3. Build and launch
51swift build
52Scripts/compile_and_run.sh
53```
54
55## Validation Checkpoints
56Run these after key steps to catch failures early before proceeding to the next stage.
57
58**After packaging (`Scripts/package_app.sh`):**
59```bash
60# Confirm .app bundle structure is intact
61ls -R build/HelloApp.app/Contents
62
63# Check that the binary is present and executable
64file build/HelloApp.app/Contents/MacOS/HelloApp
65```
66
67**After signing (`Scripts/sign-and-notarize.sh` or ad-hoc dev signing):**
68```bash
69# Inspect signature and entitlements
70codesign -dv --verbose=4 build/HelloApp.app
71
72# Verify the bundle passes Gatekeeper checks locally
73spctl --assess --type execute --verbose build/HelloApp.app
74```
75
76**After notarization and stapling:**
77```bash
78# Confirm the staple ticket is attached
79stapler validate build/HelloApp.app
80
81# Re-run Gatekeeper to confirm notarization is recognised
82spctl --assess --type execute --verbose build/HelloApp.app
83```
84
85## Common Notarization Failures
86| Symptom | Likely Cause | Recovery |
87|---|---|---|
88| `The software asset has already been uploaded` | Duplicate submission for same version | Bump `BUILD_NUMBER` in `version.env` and repackage. |
89| `Package Invalid: Invalid Code Signing Entitlements` | Entitlements in `.entitlements` file don't match provisioning | Audit entitlements against Apple's allowed set; remove unsupported keys. |
90| `The executable does not have the hardened runtime enabled` | Missing `--options runtime` flag in `codesign` invocation | Edit `sign-and-notarize.sh` to add `--options runtime` to all `codesign` calls. |
91| Notarization hangs / no status email | `xcrun notarytool` network or credential issue | Run `xcrun notarytool history` to check status; re-export App Store Connect API key if expired. |
92| `stapler validate` fails after successful notarization | Ticket not yet propagated | Wait ~60 s, then re-run `xcrun stapler staple`. |
93
94## Templates
95- `assets/templates/package_app.sh`: Build binaries, create the .app bundle, copy resources, sign.
96- `assets/templates/compile_and_run.sh`: Dev loop to kill running app, package, launch.
97- `assets/templates/build_icon.sh`: Generate .icns from an Icon Composer file (requires Xcode install).
98- `assets/templates/sign-and-notarize.sh`: Notarize, staple, and zip a release build.
99- `assets/templates/make_appcast.sh`: Generate Sparkle appcast entries for updates.
100- `assets/templates/setup_dev_signing.sh`: Create a stable dev code-signing identity.
101- `assets/templates/launch.sh`: Simple launcher for a packaged .app.
102- `assets/templates/version.env`: Example version file consumed by packaging scripts.
103- `assets/templates/bootstrap/`: Minimal SwiftPM macOS app skeleton (Package.swift, Sources/, version.env).
104
105## Notes
106- Keep entitlements and signing configuration explicit; edit the template scripts instead of reimplementing.
107- Remove Sparkle steps if you do not use Sparkle for updates.
108- Sparkle relies on the bundle build number (`CFBundleVersion`), so `BUILD_NUMBER` in `version.env` must increase for each update.
109- For menu bar apps, set `MENU_BAR_APP=1` when packaging to emit `LSUIElement` in Info.plist.
terminalskills