xcode-build-&-simulator（Xcode 构建 simulator）

Xcode Build & Simulator Skill

Overview

This skill provides comprehensive guidance for Apple platform development using native CLI tools:

• xcodebuild - Build, test, and archive Xcode projects
• xcrun simctl - Manage iOS/watchOS/tvOS simulators
• xcrun devicectl - Manage physical Apple devices
• swift - Swift Package Manager operations

Project Discovery

Find Projects & Workspaces

# Find all Xcode projects
find . -name "*.xcodeproj" -type d 2>/dev/null

# Find all workspaces
find . -name "*.xcworkspace" -type d 2>/dev/null

# Find Swift packages
find . -name "Package.swift" -type f 2>/dev/null

List Schemes & Build Settings

# List schemes in a project
xcodebuild -list -project MyApp.xcodeproj

# List schemes in a workspace
xcodebuild -list -workspace MyApp.xcworkspace

# Show build settings
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -showBuildSettings

# Show specific build setting
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -showBuildSettings | grep PRODUCT_BUNDLE_IDENTIFIER

Extract Bundle Identifier

# From built .app bundle
defaults read /path/to/MyApp.app/Info.plist CFBundleIdentifier

# Using plutil (more reliable)
plutil -extract CFBundleIdentifier raw /path/to/MyApp.app/Info.plist

# From project build settings
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -showBuildSettings | grep PRODUCT_BUNDLE_IDENTIFIER | awk '{print $3}'

Simulator Management

List Simulators

# List all simulators
xcrun simctl list devices

# List available (can be booted) simulators
xcrun simctl list devices available

# List only booted simulators
xcrun simctl list devices booted

# JSON output for parsing
xcrun simctl list devices -j

# List device types
xcrun simctl list devicetypes

# List available runtimes (iOS versions)
xcrun simctl list runtimes

Boot & Open Simulators

# Boot simulator by UDID
xcrun simctl boot <UDID>

# Boot by device name
xcrun simctl boot "iPhone 15 Pro"

# Open Simulator.app (GUI)
open -a Simulator

# Open specific simulator in GUI
open -a Simulator --args -CurrentDeviceUDID <UDID>

# Shutdown simulator
xcrun simctl shutdown <UDID>
xcrun simctl shutdown booted
xcrun simctl shutdown all

Erase & Delete Simulators

# Erase content and settings (keeps simulator)
xcrun simctl erase <UDID>
xcrun simctl erase all

# Delete simulator entirely
xcrun simctl delete <UDID>
xcrun simctl delete unavailable  # Remove unavailable simulators

Simulator Appearance & Settings

# Set dark/light mode
xcrun simctl ui booted appearance dark
xcrun simctl ui booted appearance light

# Set content size (accessibility)
xcrun simctl ui booted content_size extra-small
xcrun simctl ui booted content_size small
xcrun simctl ui booted content_size medium
xcrun simctl ui booted content_size large
xcrun simctl ui booted content_size extra-large
xcrun simctl ui booted content_size extra-extra-large
xcrun simctl ui booted content_size extra-extra-extra-large
xcrun simctl ui booted content_size accessibility-medium
xcrun simctl ui booted content_size accessibility-large
xcrun simctl ui booted content_size accessibility-extra-large

Location Simulation

# Set GPS location (latitude,longitude)
xcrun simctl location booted set 37.7749,-122.4194

# Set location by name (uses Apple Maps geocoding)
xcrun simctl location booted set "San Francisco, CA"

# Clear/reset location
xcrun simctl location booted clear

# Run GPX route simulation
xcrun simctl location booted start route.gpx

# Stop route simulation
xcrun simctl location booted stop

Status Bar Override (for screenshots)

# Override status bar appearance
xcrun simctl status_bar booted override \
  --time "9:41" \
  --batteryState charged \
  --batteryLevel 100 \
  --cellularMode active \
  --cellularBars 4 \
  --wifiBars 3 \
  --operatorName "Carrier"

# Clear all status bar overrides
xcrun simctl status_bar booted clear

Building for Simulator

Build Commands

# Build for iOS Simulator
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphonesimulator \
  -configuration Debug \
  build

# Build for specific simulator destination
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  build

# Build with custom derived data path
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphonesimulator \
  -derivedDataPath ./build \
  build

# Clean and build
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  clean build

# Build without code signing (simulator)
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphonesimulator \
  CODE_SIGN_IDENTITY="" \
  CODE_SIGNING_REQUIRED=NO \
  build

Find Built App Path

# From default DerivedData
find ~/Library/Developer/Xcode/DerivedData -name "MyApp.app" -path "*/Debug-iphonesimulator/*" -type d | head -1

# From custom derived data path
find ./build -name "*.app" -type d | head -1

# Get app path from build output
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphonesimulator \
  -showBuildSettings | grep -m1 "BUILT_PRODUCTS_DIR" | awk '{print $3}'

Install & Launch on Simulator

# Install app
xcrun simctl install booted /path/to/MyApp.app

# Launch app (returns immediately)
xcrun simctl launch booted com.yourcompany.MyApp

# Launch and wait for app to exit
xcrun simctl launch --console booted com.yourcompany.MyApp

# Launch with arguments
xcrun simctl launch booted com.yourcompany.MyApp --arg1 value1

# Launch with environment variables
xcrun simctl launch booted com.yourcompany.MyApp MYENV=value

# Terminate app
xcrun simctl terminate booted com.yourcompany.MyApp

# Uninstall app
xcrun simctl uninstall booted com.yourcompany.MyApp

Build & Run Combined Workflow

# Complete build-install-launch workflow
WORKSPACE="MyApp.xcworkspace"
SCHEME="MyApp"
BUNDLE_ID="com.yourcompany.MyApp"
SIMULATOR="iPhone 15 Pro"

# Boot simulator
xcrun simctl boot "$SIMULATOR" 2>/dev/null || true

# Build
xcodebuild -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -sdk iphonesimulator \
  -derivedDataPath ./build \
  build

# Find and install app
APP_PATH=$(find ./build -name "*.app" -path "*Debug-iphonesimulator*" -type d | head -1)
xcrun simctl install booted "$APP_PATH"

# Launch
xcrun simctl launch booted "$BUNDLE_ID"

Physical Device Development

List Connected Devices

# Using devicectl (iOS 17+, recommended)
xcrun devicectl list devices

# Using instruments (legacy)
xcrun xctrace list devices

# Using system_profiler
system_profiler SPUSBDataType | grep -A 11 "iPhone\|iPad"

Build for Device

# Build for iOS device
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphoneos \
  -configuration Debug \
  build

# Build for specific device
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS,id=<DEVICE_UDID>' \
  build

# Build and export for ad-hoc distribution
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphoneos \
  -configuration Release \
  -archivePath ./build/MyApp.xcarchive \
  archive

Install & Launch on Device (devicectl - iOS 17+)

# Install app on device
xcrun devicectl device install app --device <DEVICE_UDID> /path/to/MyApp.app

# Launch app on device
xcrun devicectl device process launch --device <DEVICE_UDID> com.yourcompany.MyApp

# Terminate app on device
xcrun devicectl device process terminate --device <DEVICE_UDID> com.yourcompany.MyApp

Device Log Capture

# Stream device logs (devicectl)
xcrun devicectl device log stream --device <DEVICE_UDID>

# Stream with process filter
xcrun devicectl device log stream --device <DEVICE_UDID> --process MyApp

# Capture syslog (legacy)
idevicesyslog -u <DEVICE_UDID>

macOS Development

Build macOS App

# Build for macOS
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk macosx \
  -configuration Debug \
  build

# Build for specific macOS version
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=macOS' \
  build

Find Built macOS App

# Find app bundle
find ~/Library/Developer/Xcode/DerivedData -name "MyApp.app" -path "*/Debug/*" -type d | head -1

Launch & Stop macOS App

# Launch macOS app
open /path/to/MyApp.app

# Launch with arguments
open /path/to/MyApp.app --args --arg1 value1

# Stop macOS app by name
killall "MyApp"

# Stop by process ID
kill $(pgrep -f "MyApp")

# Or using osascript
osascript -e 'quit app "MyApp"'

Test macOS App

xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=macOS'

Testing

Run Tests on Simulator

# Run all tests
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro'

# Run with result bundle
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  -resultBundlePath ./TestResults.xcresult

# Run specific test class
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  -only-testing:MyAppTests/MyTestClass

# Run specific test method
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  -only-testing:MyAppTests/MyTestClass/testSpecificMethod

# Skip specific tests
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  -skip-testing:MyAppTests/SlowTests

Run Tests on Device

xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppTests \
  -destination 'platform=iOS,id=<DEVICE_UDID>'

UI Tests

xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyAppUITests \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro'

Swift Package Manager

Build Package

# Build package (debug)
swift build

# Build release
swift build -c release

# Build with verbose output
swift build -v

# Build specific target
swift build --target MyTarget

# Build for specific platform
swift build --triple arm64-apple-ios-simulator

Run Package Executable

# Run executable target
swift run MyExecutable

# Run with arguments
swift run MyExecutable --arg1 value1

# Run release build
swift run -c release MyExecutable

Test Package

# Run all tests
swift test

# Run specific test
swift test --filter MyTestClass

# Run tests in parallel
swift test --parallel

# Generate code coverage
swift test --enable-code-coverage

Clean Package

# Clean build artifacts
swift package clean

# Reset package completely
swift package reset

# Update dependencies
swift package update

# Resolve dependencies
swift package resolve

Package Management

# Show dependencies
swift package show-dependencies

# Generate Xcode project
swift package generate-xcodeproj

# Dump package description
swift package dump-package

Screenshots & Video Capture

Screenshots

# Take screenshot of booted simulator
xcrun simctl io booted screenshot screenshot.png

# Screenshot specific simulator
xcrun simctl io <UDID> screenshot screenshot.png

# Screenshot with device mask (frame)
xcrun simctl io booted screenshot --mask black screenshot.png
xcrun simctl io booted screenshot --mask ignored screenshot.png

# Screenshot to stdout (for piping)
xcrun simctl io booted screenshot -

Video Recording

# Start recording (runs until Ctrl+C)
xcrun simctl io booted recordVideo video.mp4

# Record with codec
xcrun simctl io booted recordVideo --codec h264 video.mp4

# Record with mask
xcrun simctl io booted recordVideo --mask black video.mp4

# Background recording workflow
xcrun simctl io booted recordVideo video.mp4 &
VIDEO_PID=$!
# ... perform test actions ...
kill -INT $VIDEO_PID  # Stop recording gracefully

UI Automation

UI Element Discovery (describe_ui equivalent)

# Get accessibility hierarchy using Accessibility Inspector CLI
# First, enable in System Preferences > Privacy & Security > Accessibility

# Use XCUITest for programmatic access, or:

# Get window list
osascript -e 'tell application "System Events" to get every window of application process "Simulator"'

# Open Accessibility Inspector for visual inspection
open -a "Accessibility Inspector"

Tap at Coordinates

# Using AppleScript (requires Accessibility permissions)
osascript -e '
tell application "Simulator" to activate
delay 0.3
tell application "System Events"
    click at {200, 400}
end tell
'

# Tap with specific window
osascript -e '
tell application "System Events"
    tell process "Simulator"
        click at {200, 400} of window 1
    end tell
end tell
'

Long Press

osascript -e '
tell application "Simulator" to activate
delay 0.2
tell application "System Events"
    -- Click and hold for 1 second
    set mousePos to {200, 400}
    click at mousePos
    delay 1.0
end tell
'

Swipe Gestures

# Swipe up (scroll down)
osascript -e '
tell application "Simulator" to activate
tell application "System Events"
    tell process "Simulator"
        set frontWindow to window 1
        -- Perform swipe from bottom to top
        click at {200, 600} of frontWindow
        delay 0.05
        -- Note: For true swipes, use XCUITest or simctl gestures
    end tell
end tell
'

Keyboard Input (Type Text)

# Type text in focused field
osascript -e '
tell application "Simulator" to activate
delay 0.2
tell application "System Events"
    keystroke "Hello World"
end tell
'

# Type with special keys
osascript -e '
tell application "System Events"
    keystroke "a" using command down  -- Cmd+A (select all)
    keystroke return                   -- Press Enter
    keystroke tab                      -- Press Tab
    key code 51                        -- Delete/Backspace
end tell
'

Hardware Button Simulation

# Home button
osascript -e '
tell application "System Events"
    tell process "Simulator"
        click menu item "Home" of menu "Device" of menu bar 1
    end tell
end tell
'

# Lock screen
osascript -e '
tell application "System Events"
    tell process "Simulator"
        click menu item "Lock Screen" of menu "Device" of menu bar 1
    end tell
end tell
'

# Shake gesture
osascript -e '
tell application "System Events"
    tell process "Simulator"
        click menu item "Shake" of menu "Device" of menu bar 1
    end tell
end tell
'

# Rotate device
osascript -e '
tell application "System Events"
    tell process "Simulator"
        click menu item "Rotate Left" of menu "Device" of menu bar 1
    end tell
end tell
'

Open URL / Deep Links

# Open URL in simulator
xcrun simctl openurl booted "https://example.com"

# Open custom URL scheme (deep link)
xcrun simctl openurl booted "myapp://path/to/screen?param=value"

# Open universal link
xcrun simctl openurl booted "https://myapp.com/deeplink"

Log Capture

Simulator Logs

# Stream all logs
xcrun simctl spawn booted log stream

# Stream with process filter
xcrun simctl spawn booted log stream --predicate 'processImagePath contains "MyApp"'

# Stream specific log levels
xcrun simctl spawn booted log stream --level debug
xcrun simctl spawn booted log stream --level info
xcrun simctl spawn booted log stream --level error

# Stream with subsystem filter
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.yourcompany.MyApp"'

# Save logs to file
xcrun simctl spawn booted log stream --predicate 'processImagePath contains "MyApp"' > app.log &
LOG_PID=$!
# ... run tests ...
kill $LOG_PID

Collect Log Archive

# Collect logs to archive
xcrun simctl spawn booted log collect --output logs.logarchive

# Show logs from archive
log show logs.logarchive

# Filter archived logs
log show logs.logarchive --predicate 'processImagePath contains "MyApp"'
log show logs.logarchive --last 5m  # Last 5 minutes

App Container & Data

# Get app container paths
xcrun simctl get_app_container booted com.yourcompany.MyApp        # Bundle container
xcrun simctl get_app_container booted com.yourcompany.MyApp data   # Data container
xcrun simctl get_app_container booted com.yourcompany.MyApp groups # App groups

# List app container contents
APP_DATA=$(xcrun simctl get_app_container booted com.yourcompany.MyApp data)
ls -la "$APP_DATA/Documents/"
ls -la "$APP_DATA/Library/Caches/"

Push Notifications

# Create notification payload file
cat > notification.apns << 'EOF'
{
  "aps": {
    "alert": {
      "title": "Test Notification",
      "body": "This is a test push notification"
    },
    "badge": 1,
    "sound": "default"
  },
  "customKey": "customValue"
}
EOF

# Send push notification
xcrun simctl push booted com.yourcompany.MyApp notification.apns

# Send inline push (no file needed)
echo '{"aps":{"alert":"Quick test"}}' | xcrun simctl push booted com.yourcompany.MyApp -

Privacy & Permissions

# Grant permissions
xcrun simctl privacy booted grant photos com.yourcompany.MyApp
xcrun simctl privacy booted grant camera com.yourcompany.MyApp
xcrun simctl privacy booted grant microphone com.yourcompany.MyApp
xcrun simctl privacy booted grant contacts com.yourcompany.MyApp
xcrun simctl privacy booted grant calendar com.yourcompany.MyApp
xcrun simctl privacy booted grant reminders com.yourcompany.MyApp
xcrun simctl privacy booted grant location-always com.yourcompany.MyApp
xcrun simctl privacy booted grant location com.yourcompany.MyApp

# Revoke permissions
xcrun simctl privacy booted revoke photos com.yourcompany.MyApp
xcrun simctl privacy booted revoke all com.yourcompany.MyApp

# Reset permissions (ask again)
xcrun simctl privacy booted reset photos com.yourcompany.MyApp
xcrun simctl privacy booted reset all com.yourcompany.MyApp

Clean Operations

# Clean build products
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp clean

# Clean derived data for project
rm -rf ~/Library/Developer/Xcode/DerivedData/MyApp-*

# Clean all derived data
rm -rf ~/Library/Developer/Xcode/DerivedData/*

# Clean module cache
rm -rf ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex

# Clean Xcode caches
rm -rf ~/Library/Caches/com.apple.dt.Xcode

Common Workflows

Complete iOS Simulator Workflow

#!/bin/bash
WORKSPACE="MyApp.xcworkspace"
SCHEME="MyApp"
BUNDLE_ID="com.yourcompany.MyApp"
SIMULATOR="iPhone 15 Pro"

# 1. Boot simulator
xcrun simctl boot "$SIMULATOR" 2>/dev/null || true
open -a Simulator

# 2. Build
xcodebuild -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -sdk iphonesimulator \
  -derivedDataPath ./build \
  build || exit 1

# 3. Find and install
APP_PATH=$(find ./build -name "*.app" -path "*Debug-iphonesimulator*" -type d | head -1)
xcrun simctl install booted "$APP_PATH"

# 4. Launch with log capture
xcrun simctl spawn booted log stream --predicate "processImagePath contains \"$SCHEME\"" > app.log &
LOG_PID=$!
xcrun simctl launch booted "$BUNDLE_ID"

# 5. Take screenshot after delay
sleep 3
xcrun simctl io booted screenshot screenshot.png

# 6. Stop logging
kill $LOG_PID 2>/dev/null

Debug Session

# Start log capture
xcrun simctl spawn booted log stream --predicate 'processImagePath contains "MyApp"' | tee app.log &
LOG_PID=$!

# Launch app
xcrun simctl launch booted com.yourcompany.MyApp

# ... interact with app ...

# Stop and review
kill $LOG_PID
less app.log

Screenshot Automation

# Override status bar for clean screenshots
xcrun simctl status_bar booted override --time "9:41" --batteryState charged --batteryLevel 100

# Take screenshots
for device in "iPhone 15 Pro" "iPhone 15 Pro Max" "iPad Pro (12.9-inch)"; do
    xcrun simctl boot "$device" 2>/dev/null || true
    sleep 2
    xcrun simctl io booted screenshot "screenshot_${device// /_}.png"
    xcrun simctl shutdown "$device"
done

# Clear status bar override
xcrun simctl status_bar booted clear

Troubleshooting

Build Failures

# Show detailed build log
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp build 2>&1 | tee build.log

# Show build settings
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -showBuildSettings

# Clean and rebuild
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp clean build

Simulator Issues

# Restart CoreSimulator service
sudo killall -9 com.apple.CoreSimulator.CoreSimulatorService

# Reset all simulators
xcrun simctl shutdown all
xcrun simctl erase all

# Kill Simulator app
killall "Simulator"

# Check simulator status
xcrun simctl list devices booted

Code Signing

# List signing identities
security find-identity -v -p codesigning

# List provisioning profiles
ls -la ~/Library/MobileDevice/Provisioning\ Profiles/

# Decode provisioning profile
security cms -D -i ~/Library/MobileDevice/Provisioning\ Profiles/<UUID>.mobileprovision

Device Connection Issues

# List USB devices
system_profiler SPUSBDataType

# Trust device (must be done on device)
# Disconnect and reconnect device, tap "Trust" on device

# Check device pairing
xcrun devicectl list devices

Environment Info (Doctor)

# Xcode version
xcodebuild -version

# Available SDKs
xcodebuild -showsdks

# Xcode path
xcode-select -p

# Switch Xcode version
sudo xcode-select -s /Applications/Xcode.app

# Swift version
swift --version

# macOS version
sw_vers

# Available simulators summary
xcrun simctl list --json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Devices: {sum(len(v) for v in d[\"devices\"].values())}')"

Resources

• xcodebuild Man Page
• simctl Reference
• devicectl Documentation
• Swift Package Manager
• Apple Testing Documentation