MacOS_Debug_Release_Guide.md

🧭 macOS Debug Release Guide

A generic step-by-step guide to build, export, and publish a macOS Debug build on GitHub.

---

🚀 1. Prepare the Archive

Run the following command in Terminal from your Xcode project root:

xcodebuild clean archive   -scheme YourAppScheme   -configuration Debug   -archivePath ./build/YourAppName.xcarchive

This creates a .xcarchive in the ./build folder.

---

🧾 2. Create ExportOptions.plist

Create a file named ExportOptions.plist with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>debugging</string>
    <key>signingStyle</key>
    <string>manual</string>
    <key>compileBitcode</key>
    <false/>
    <key>destination</key>
    <string>export</string>
    <key>stripSwiftSymbols</key>
    <false/>
    <key>generateAppStoreInformation</key>
    <false/>
    <key>manageAppVersionAndBuildNumber</key>
    <false/>
    <key>uploadSymbols</key>
    <false/>
    <key>uploadBitcode</key>
    <false/>
</dict>
</plist>

This configuration exports an unsigned Debug build for local testing or GitHub release.
No teamID is required.

---

🧱 3. Export the Build

Run this command to export the .app file:

xcodebuild -exportArchive   -archivePath ./build/YourAppName.xcarchive   -exportOptionsPlist ./ExportOptions.plist   -exportPath ./build

After running this, the exported .app will be available in the ./build folder.

---

🗜️ 4. Zip the App for GitHub Release

Zip the .app so it's ready to upload to GitHub:

cd build
zip -r YourAppName_Debug.zip YourAppName.app

---

🏷️ 5. Tag the Version

Tag the commit and push the version tag to GitHub:

git checkout main
git pull origin main
git tag -a v1.0.0-debug -m "Debug v1.0.0"
git push origin v1.0.0-debug

---

📦 6. Create the GitHub Release

Steps to publish the Debug build on GitHub:

1. Go to your repository’s Releases tab
2. Click “Draft a new release”
3. Choose your pushed tag (e.g., v1.0.0-debug)
4. Add release notes describing the Debug build
5. Upload YourAppName_Debug.zip as an asset
6. Click Publish Release

---

✅ Result

Your GitHub release page will now include a downloadable .zip of your macOS Debug app.
Users can unzip it and run the app directly (macOS may prompt with "unidentified developer" on first launch).