mcpField
M
macos-build

macos-build

github.com/fayazaraDevelopment685619 installsUpdated 22w ago
Repository

About macos-build

A command-line guide for building native macOS Xcode projects, aimed at developers compiling or verifying an app. It covers locating projects and schemes, running xcodebuild, and diagnosing common build failures.

Key features

  1. 01Find Xcode projects and workspaces
  2. 02List available schemes
  3. 03Build with xcodebuild
  4. 04Filter and interpret build output
  5. 05Diagnose common build failures

Use cases

  1. 01Verifying compilation after code changes
  2. 02Building a macOS app with a chosen scheme
  3. 03Diagnosing dependency, signing, or SDK errors
  4. 04Selecting an Xcode toolchain for a beta SDK

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/fayazara/macos-app-skills --skill macos-build

After installing, type/macos-buildin Claude Code to confirm it loaded.

Details

From the project README

Build macOS App

Build any native macOS Xcode project from the command line using xcodebuild.

Finding the Project

Before building, locate the Xcode project or workspace:

find . -maxdepth 2 -name "*.xcodeproj" -o -name "*.xcworkspace" | head -5

Then list available schemes:

xcodebuild -list -project "YourApp.xcodeproj" 2>/dev/null | grep -A 20 "Schemes:"

Build Command

Use this command template, replacing the project path and scheme:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild build \
  -project "YourApp.xcodeproj" \
  -scheme "YourApp" \
  -configuration Debug \
  -destination "platform=macOS" \
  2>&1 | grep -E "(BUILD SUCCEEDED|BUILD FAILED|error:)" | head -20

For workspaces (projects with SPM dependencies or CocoaPods):

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild build \
  -workspace "YourApp.xcworkspace" \
  -scheme "YourApp" \
  -configuration Debug \
  -destination "platform=macOS" \
  2>&1 | grep -E "(BUILD SUCCEEDED|BUILD FAILED|error:)" | head -20

Interpreting Results

  • BUILD SUCCEEDED -- the build passed, report success to the user.
  • BUILD FAILED with error: lines -- read each error, identify the source file and line, and help the user fix them. After fixing, re-run the build to verify.
  • If the output is empty or unclear, re-run without the grep filter to get full output for diagnosis.

When to Build

  • After making code changes, if the user asks to verify they compile
  • When the user explicitly says "build", "compile", or "check if it builds"
  • After fixing build errors, to confirm the fix worked

Xcode Beta Toolchains

If the project targets a beta SDK (e.g., macOS 26 Tahoe), you may need to point to the beta Xcode:

DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer xcodebuild build ...

Check which Xcode is available:

ls /Applications/ | grep -i xcode

Common Build Failures

ErrorFix
no such module 'Sparkle'SPM dependency not resolved. Try xcodebuild -resolvePackageDependencies first
no signing identity foundSet CODE_SIGN_IDENTITY="" and CODE_SIGNING_ALLOWED=NO for command-line builds
SDK "macosx" cannot be locatedWrong DEVELOPER_DIR. Check Xcode installation path
scheme not foundRun xcodebuild -list to see available schemes

Comments

Markdown supported