Xcode Command Line Debugging Guide

xcode-cli-debugging-guide.txt

# Xcode Command Line Debugging Guide, by Todd S. Hopkinson (June 2025)

## 🔧 Overview

This guide provides a systematic process for debugging Xcode build errors using command-line tools. This approach is faster than opening Xcode, works in any terminal environment, and is especially useful for automated processes, CI/CD pipelines, or when working with LLMs that have command-line access.

## 🚀 The Core Process

### Step 1: Initial Build Command
Start with the simplest possible build command:

```bash
xcodebuild -scheme [your_scheme_name] build
```

**Why this works:**
- Avoids destination complications
- Uses default settings
- Provides immediate feedback

### Step 2: Error Filtering Strategy
When builds fail, filter the massive output to find actual errors:

```bash
xcodebuild -scheme momentum build 2>&1 | grep -E "(error|Error|BUILD FAILED|BUILD SUCCEEDED)"
```

**Key components:**
- `2>&1` - Captures both stdout and stderr
- `grep -E` - Extended regex for pattern matching
- Multiple patterns - Catches various error formats

### Step 3: Progressive Error Analysis

**Get error context:**
```bash
xcodebuild -scheme momentum build 2>&1 | grep -A 3 -B 3 "error:"
```
- `-A 3` - Shows 3 lines after each match
- `-B 3` - Shows 3 lines before each match

**Check build status only:**
```bash
xcodebuild -scheme momentum build 2>&1 | tail -5 | grep -E "(BUILD|error)"
```

### Step 4: Specific Error Type Detection

**Swift compilation errors:**
```bash
xcodebuild ... 2>&1 | grep -E "(Cannot find|Use of undeclared|Type.*does not conform)"
```

**Linker errors:**
```bash
xcodebuild ... 2>&1 | grep -E "(Undefined symbol|duplicate symbol|library not found)"
```

**Build setting errors:**
```bash
xcodebuild ... 2>&1 | grep -E "(No such file|Permission denied|Code signing)"
```

### Step 5: Output Management
When output is overwhelming:

```bash
# First 50 lines (usually contains important setup info)
xcodebuild ... 2>&1 | head -50

# Last 20 lines (usually contains final errors)
xcodebuild ... 2>&1 | tail -20

# Save full output for detailed analysis
xcodebuild ... > build_log.txt 2>&1
```

### Step 6: Iterative Debugging
1. Fix the first error found
2. Re-run the build
3. Repeat until BUILD SUCCEEDED

### Step 7: Advanced Filtering
For complex projects with lots of warnings:

```bash
# Errors only, no warnings
xcodebuild ... 2>&1 | grep -v "warning:" | grep -E "(error|Error)"

# Critical errors only
xcodebuild ... 2>&1 | grep -E "(fatal error|error:|BUILD FAILED)"
```

## 📋 Command Reference

### Basic Commands

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `xcodebuild -list` | Show available schemes/targets | First time with a project |
| `xcodebuild -scheme X build` | Basic build | Initial testing |
| `xcodebuild -scheme X clean build` | Clean then build | After major changes |
| `xcodebuild -scheme X test` | Run tests | Verify functionality |

### Filtering Commands

| Pattern | Catches | Example |
|---------|---------|---------|
| `grep -E "(error\|Error)"` | All errors | Compilation failures |
| `grep "BUILD"` | Build status | Success/failure summary |
| `grep -i "fail"` | All failures | Broad failure detection |
| `grep -v "warning"` | Exclude warnings | Focus on errors only |

### Destination Options
```bash
# iOS Simulator (when needed)
xcodebuild -scheme momentum -destination 'platform=iOS Simulator,name=iPhone 15' build

# Any available device
xcodebuild -scheme momentum build
```

## ⚠️ Common Error Patterns

### Swift Compilation Errors
```
error: cannot find 'SomeClass' in scope
error: use of undeclared type 'SomeProtocol'
error: type 'MyClass' does not conform to protocol 'SomeProtocol'
```
**Solution:** Check imports, typos, and protocol conformance

### SwiftData Errors
```
error: @Model class must be final
error: Cannot use stored property 'x' within @Model
```
**Solution:** Review SwiftData model requirements

### Build Setting Errors
```
error: could not find included file 'SomeFile.h'
error: linker command failed with exit code 1
```
**Solution:** Check file paths, build settings, and dependencies

### CloudKit/Signing Errors
```
error: Automatic signing is unable to resolve an issue
error: CloudKit container not found
```
**Solution:** Check signing settings and CloudKit configuration

## 💡 Practical Examples

### Example 1: Missing Import
**Error Output:**
```
error: cannot find 'SwiftData' in scope
```

**Debug Process:**
```bash
# 1. Identify the error
xcodebuild -scheme momentum build 2>&1 | grep "cannot find"

# 2. Find the problematic file
xcodebuild -scheme momentum build 2>&1 | grep -B 5 "cannot find"

# 3. Fix: Add `import SwiftData` to the file
```

### Example 2: Build Configuration Issue
**Error Output:**
```
BUILD FAILED
error: Build input file cannot be found
```

**Debug Process:**
```bash
# 1. Check for missing files
xcodebuild -scheme momentum build 2>&1 | grep -A 3 "cannot be found"

# 2. Verify file exists in project
# 3. Check if file is added to target membership
```

### Example 3: SwiftData Model Error
**Error Output:**
```
error: @Model class 'Goal' must be final
```

**Debug Process:**
```bash
# 1. Identify model errors
xcodebuild -scheme momentum build 2>&1 | grep -E "(@Model|final)"

# 2. Fix: Add 'final' keyword to class declaration
```

## 🛠️ Troubleshooting

### When Standard Process Doesn't Work

**Problem:** No clear error in filtered output
```bash
# Solution: Look at broader context
xcodebuild ... 2>&1 | grep -A 10 -B 10 "BUILD FAILED"
```

**Problem:** Too much output, hitting limits
```bash
# Solution: Save to file and analyze
xcodebuild ... > full_build.log 2>&1
grep -E "(error|Error)" full_build.log
```

**Problem:** Intermittent failures
```bash
# Solution: Clean build
xcodebuild -scheme momentum clean build 2>&1 | grep -E "(error|BUILD)"
```

### Performance Tips

1. **Start simple:** Always try basic build first
2. **Filter early:** Don't read full output manually
3. **Save complex outputs:** Use files for large logs
4. **Context is key:** Error location often matters more than error message
5. **Iterate quickly:** Fix one error at a time

## 🔄 Integration with IDEs

### When to Use CLI vs Xcode
- **Use CLI when:** Fast feedback needed, scripting, CI/CD, remote development
- **Use Xcode when:** Complex debugging, interface builder issues, advanced profiling

### Hybrid Workflow
1. Use CLI for rapid error detection
2. Switch to Xcode for complex fixes
3. Return to CLI for verification

## 📚 Best Practices

### ✅ Do
- Always check build status first
- Use progressive filtering (start broad, get specific)
- Save complex outputs to files
- Focus on first error, not all errors
- Learn common error patterns for your tech stack

### ❌ Don't
- Try to read entire xcodebuild output manually
- Ignore context lines around errors
- Skip the clean build when in doubt
- Mix multiple changes when debugging
- Assume first error is most important (sometimes it's the last)

---

## 📖 Quick Reference Card

```bash
# Basic debugging sequence
xcodebuild -scheme PROJECT build 2>&1 | grep -E "(error|BUILD)"
xcodebuild -scheme PROJECT build 2>&1 | grep -A 3 -B 3 "error:"
xcodebuild -scheme PROJECT clean build 2>&1 | tail -10

# Save for analysis
xcodebuild -scheme PROJECT build > debug.log 2>&1

# Find specific issues
grep -E "(SwiftData|@Model)" debug.log
grep -E "(Cannot find|Use of undeclared)" debug.log
```

*This guide was developed through iterative debugging of real Xcode projects and represents proven command-line debugging strategies.*