# Xcode Setup

Guide for configuring Xcode for OrchardGo development.

## Required Version

OrchardGo requires a specific Xcode version. Check [.xcode-version](../../.xcode-version) for the required version.

## Installation

1. **Download Xcode**
   - [Mac App Store](https://apps.apple.com/us/app/xcode/id497799835)
   - Or from [Apple Developer Downloads](https://developer.apple.com/download/more/)
   - For specific versions: [Xcode Releases](https://xcodereleases.com/)

2. **Install Command Line Tools**
   - Open Xcode
   - Xcode → Preferences → Locations
   - Select Command Line Tools version

3. **Accept License**
   ```bash
   sudo xcodebuild -license accept
   ```

## Project Setup

### Opening the Project

Always open the **workspace**, not the project:

```bash
# Correct
open ios/orchardgo.xcworkspace

# Or use the script
yarn xcode

# Incorrect - don't use
open ios/orchardgo.xcodeproj
```

### Workspace Structure

```
ios/orchardgo.xcworkspace/
├── orchardgo.xcodeproj    # Main app project
└── Pods/                  # CocoaPods dependencies
```

## Configuration

### Signing & Capabilities

1. **Select Project**
   - Open workspace
   - Click "orchardgo" in project navigator

2. **Select Target**
   - Click "orchardgo" target

3. **Signing & Capabilities Tab**
   - Team: Select your team
   - Bundle Identifier: Should match environment
     - Prod: `com.theorchard.OrchardGo`
     - QA: `com.theorchard.OrchardGo.qa`
     - Dev: `com.theorchard.OrchardGo.dev`

4. **Capabilities**
   - ✅ Push Notifications
   - ✅ Associated Domains
   - ✅ Background Modes

### Build Settings

Key build settings (automatically configured):

| Setting | Value |
|---------|-------|
| **Swift Language Version** | Swift 5 |
| **Deployment Target** | iOS 13.0+ |
| **Build Active Architecture Only** | Debug: Yes, Release: No |
| **Enable Bitcode** | No (React Native requirement) |

### Schemes

Available schemes:
- **orchardgo** - Main app scheme
- **orchardgo-tvOS** - TV app (if applicable)

To edit schemes:
- Product → Scheme → Edit Scheme
- Configure build configuration (Debug/Release)

## CocoaPods

### Installing Pods

```bash
cd ios
pod install
```

### Updating Pods

```bash
cd ios
pod update
```

### Troubleshooting Pods

```bash
# Clean and reinstall
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update
```

## Building

### Debug Build

```bash
# From project root
yarn start:ios

# Or via Xcode
# Product → Build (Cmd+B)
```

### Release Build

```bash
# Via Xcode
# Product → Archive
# Then distribute via organizer
```

## Common Issues

### "No such module" Error

**Solution:**
```bash
cd ios
pod install
```
Then clean build folder in Xcode (Shift+Cmd+K).

### Signing Error

**Solutions:**
1. Check Team is selected in Signing & Capabilities
2. Verify bundle ID matches provisioning profile
3. Download provisioning profiles:
   - Xcode → Preferences → Accounts
   - Select team → Download Manual Profiles

### Build Failed with Pod Error

**Solution:**
```bash
cd ios
rm -rf Pods Podfile.lock ~/Library/Caches/CocoaPods
pod install --repo-update
```

### Derived Data Issues

**Solution:**
```bash
# Clean derived data
rm -rf ~/Library/Developer/Xcode/DerivedData

# Or via Xcode
# Product → Clean Build Folder (Shift+Cmd+K)
```

### Xcode Version Mismatch

**Solution:**
1. Install correct version (see [.xcode-version](../../.xcode-version))
2. Switch Xcode:
   ```bash
   sudo xcode-select -s /Applications/Xcode.app
   ```
3. Verify:
   ```bash
   xcode-select -p
   xcodebuild -version
   ```

## Simulator Management

### List Simulators

```bash
yarn ios:simulators

# Or
xcrun simctl list devices
```

### Create New Simulator

1. Xcode → Window → Devices and Simulators
2. Click "+" to add new simulator
3. Select device type and iOS version

### Delete Unavailable Simulators

```bash
xcrun simctl delete unavailable
```

### Reset Simulator

```bash
# Reset specific simulator
xcrun simctl erase [SIMULATOR_ID]

# Or via UI
# Device → Erase All Content and Settings
```

## Debugging in Xcode

### View Logs

1. Run app on simulator/device
2. View → Debug Area → Activate Console (Cmd+Shift+Y)
3. Filter logs in search bar

### Breakpoints

1. Click line number to add breakpoint
2. Run app with debugger attached
3. When hit, inspect variables in debug area

### LLDB Commands

```bash
# Print variable
po variableName

# Continue execution
continue

# Step over
next

# Step into
step
```

## Performance Tools

### Instruments

1. Product → Profile (Cmd+I)
2. Select profiling template:
   - Time Profiler
   - Allocations
   - Leaks
   - Network

### Memory Graph

1. Debug → View Memory Graph (Cmd+Shift+M)
2. Identify retain cycles
3. View object relationships

## Xcode Settings

### Recommended Settings

**Text Editing:**
- ✅ Line numbers
- ✅ Code folding ribbon
- ✅ Automatically trim trailing whitespace

**Locations:**
- Derived Data: Default location
- Archives: Default location

**Behaviors:**
- On build → Show navigator (Project)
- On build succeeds → Hide navigator
- On build fails → Show issue navigator

## Version Management

### Multiple Xcode Versions

To install and manage multiple Xcode versions:

1. **Download Xcode**
   - Visit [xcodereleases.com](https://xcodereleases.com)
   - Download the required version
   - Extract the archive file

2. **Rename and Install**
   ```bash
   # Rename the extracted Xcode app to include version
   # Example: Xcode.app → Xcode_15.0.app

   # Move to Applications directory
   mv Xcode.app /Applications/Xcode_15.0.app
   ```

3. **Run Xcode**
   ```bash
   # Open the specific Xcode version
   open /Applications/Xcode_15.0.app

   # Xcode will prompt to install additional tools - accept
   ```

4. **Switch Active Version**
   ```bash
   # Check current version
   xcode-select -p
   # Output: /Applications/Xcode.app/Contents/Developer

   # Switch to specific version
   sudo xcode-select -s /Applications/Xcode_15.0.app

   # Verify the switch
   xcodebuild -version
   ```

5. **Manage Multiple Versions**
   ```bash
   # List all installed Xcode versions
   ls /Applications/ | grep Xcode

   # Example output:
   # Xcode_14.3.app
   # Xcode_15.0.app
   # Xcode_15.2.app
   ```

### Command Line Tools

```bash
# List installed command line tools
ls /Library/Developer/CommandLineTools

# Install if missing
xcode-select --install
```

## Resources

- [Xcode Documentation](https://developer.apple.com/documentation/xcode)
- [Xcode Release Notes](https://developer.apple.com/documentation/xcode-release-notes)
- [CocoaPods Guides](https://guides.cocoapods.org/)

## Next Steps

- [Prerequisites](../getting-started/prerequisites.md)
- [Installation](../getting-started/installation.md)
- [Running the App](../development/running-the-app.md)
- [macOS Maintenance](./macos-maintenance.md)