# CocoaPods Installation Guide

**Author**: Matthew Raymer  
**Date**: 2025-11-04

## Overview

CocoaPods is required for iOS development with Capacitor plugins. This guide documents the installation process and common issues.

## Prerequisites

- macOS (required for iOS development)
- Ruby (version >= 2.7.0 recommended)
- Xcode Command Line Tools

## Installation Methods

### Method 1: System Ruby (Not Recommended)

**Issue**: System Ruby on macOS is often outdated (2.6.x) and requires sudo, which can cause permission issues.

```bash
# Check Ruby version
ruby --version

# If Ruby < 2.7.0, CocoaPods may fail
# Install drb dependency first (if needed)
sudo gem install drb -v 2.0.6

# Then install CocoaPods
sudo gem install cocoapods
```

**Problems with this method:**
- Requires sudo (permission issues)
- System Ruby is outdated
- Can conflict with system updates
- Not recommended for development

### Method 2: Homebrew (Recommended)

**Best practice**: Use Homebrew to install a newer Ruby version, then install CocoaPods.

```bash
# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Ruby via Homebrew
brew install ruby

# Update PATH to use Homebrew Ruby (add to ~/.zshrc or ~/.bash_profile)
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify Ruby version (should be >= 2.7.0)
ruby --version

# Install CocoaPods (no sudo needed)
gem install cocoapods

# Setup CocoaPods
pod setup
```

### Method 3: rbenv or rvm (Alternative)

For Ruby version management:

```bash
# Using rbenv
brew install rbenv ruby-build
rbenv install 3.2.0
rbenv global 3.2.0
gem install cocoapods

# Or using rvm
curl -sSL https://get.rvm.io | bash -s stable
rvm install 3.2.0
rvm use 3.2.0 --default
gem install cocoapods
```

## Verification

After installation, verify CocoaPods:

```bash
pod --version
```

Expected output: `1.x.x` (version number)

## Common Issues

### Issue 1: Ruby Version Too Old

**Error**: `drb requires Ruby version >= 2.7.0. The current ruby version is 2.6.10.210.`

**Solution**: 
- Use Homebrew to install newer Ruby (Method 2)
- Or use rbenv/rvm for Ruby version management (Method 3)

### Issue 2: Permission Errors

**Error**: `You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.`

**Solution**:
- Don't use `sudo` with gem install
- Use Homebrew Ruby or rbenv/rvm (installs to user directory)
- Or use `sudo` only if necessary (not recommended)

### Issue 3: CocoaPods Not Found After Installation

**Error**: `pod: command not found`

**Solution**:
```bash
# Check if gem bin directory is in PATH
echo $PATH | grep gem

# Add to PATH if needed (add to ~/.zshrc)
echo 'export PATH="$HOME/.gem/ruby/3.x.x/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Or use full path
~/.gem/ruby/3.x.x/bin/pod --version
```

## Using CocoaPods

### Install Dependencies

```bash
cd test-apps/daily-notification-test/ios/App
pod install

# Or for standalone test app
cd test-apps/ios-test-app/App
pod install
```

### Update Dependencies

```bash
pod update
```

### Clean Install

```bash
pod deintegrate
pod install
```

## Project-Specific Setup

### Vue 3 Test App

```bash
cd test-apps/daily-notification-test/ios/App
pod install
```

### Standalone iOS Test App

```bash
cd test-apps/ios-test-app/App
pod install
```

## Troubleshooting

### Pod Install Fails

1. **Check Ruby version**:
   ```bash
   ruby --version
   ```

2. **Update CocoaPods**:
   ```bash
   gem update cocoapods
   ```

3. **Clear CocoaPods cache**:
   ```bash
   pod cache clean --all
   ```

4. **Clean and reinstall**:
   ```bash
   rm -rf Pods Podfile.lock
   pod install
   ```

### Xcode Workspace Not Created

After `pod install`, ensure `App.xcworkspace` exists:

```bash
ls -la App.xcworkspace
```

If missing, run `pod install` again.

### Plugin Not Found

If plugin path is incorrect in Podfile:

1. Verify plugin exists:
   ```bash
   ls -la ../../../ios/DailyNotificationPlugin.podspec
   ```

2. Check Podfile path:
   ```ruby
   pod 'DailyNotificationPlugin', :path => '../../../ios'
   ```

3. Update pod repo:
   ```bash
   pod repo update
   ```

## Best Practices

1. **Use Homebrew Ruby**: Avoids permission issues and provides latest Ruby
2. **Don't use sudo**: Install gems to user directory
3. **Version management**: Use rbenv or rvm for multiple Ruby versions
4. **Keep CocoaPods updated**: `gem update cocoapods` regularly
5. **Commit Podfile.lock**: Ensures consistent dependency versions

## References

- [CocoaPods Installation Guide](https://guides.cocoapods.org/using/getting-started.html)
- [Homebrew Ruby Installation](https://formulae.brew.sh/formula/ruby)
- [rbenv Documentation](https://github.com/rbenv/rbenv)

## Current Status

**System Ruby**: 2.6.10.210 (too old for CocoaPods)  
**Recommended**: Install Ruby >= 2.7.0 via Homebrew  
**CocoaPods**: Not yet installed (requires Ruby upgrade)