docs(ios): document CocoaPods installation requirements and current status

Documented CocoaPods installation process and current system status: Installation Documentation: - Created COCOAPODS_INSTALLATION.md with installation methods - Documented Ruby version requirements (>= 2.7.0) - Provided Homebrew, rbenv, and system Ruby options - Included troubleshooting guide for common issues Current Status Documentation: - Created IOS_SETUP_REQUIREMENTS.md with setup status - Documented completed command-line setup - Identified manual step required (CocoaPods installation) - Provided verification checklist System Status: - Ruby 2.6.10 (too old, needs >= 2.7.0) - Homebrew not installed - CocoaPods not installed - All test app structures ready for pod install Next Steps: - Install Ruby >= 2.7.0 (via Homebrew recommended) - Install CocoaPods gem - Run pod install in both test app directories
2025-11-11 01:42:44 -08:00
parent a2e4517518
commit 9790f2d01c
2 changed files with 401 additions and 0 deletions
--- a/docs/COCOAPODS_INSTALLATION.md
+++ b/docs/COCOAPODS_INSTALLATION.md
@@ -0,0 +1,244 @@
+# 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)
+
--- a/docs/IOS_SETUP_REQUIREMENTS.md
+++ b/docs/IOS_SETUP_REQUIREMENTS.md
@@ -0,0 +1,157 @@
+# iOS Setup Requirements and Current Status
+
+**Author**: Matthew Raymer  
+**Date**: 2025-11-04  
+**Status**: ⚠️ **MANUAL STEP REQUIRED**
+
+## Current Status
+
+### ✅ Completed (Command-Line Setup)
+
+1. **Vue 3 Test App iOS Platform**
+   - iOS platform added via `npx cap add ios`
+   - Xcode project structure created
+   - Podfile created with plugin dependency
+   - All files in place
+
+2. **Standalone iOS Test App**
+   - App structure created
+   - Capacitor config created
+   - Podfile created with plugin dependency
+   - Test HTML interface copied
+   - All files in place
+
+3. **Plugin Integration**
+   - Both Podfiles configured correctly
+   - Plugin paths verified
+   - Ready for CocoaPods installation
+
+### ⚠️ Manual Step Required
+
+**CocoaPods Installation** - Cannot be automated due to:
+- Ruby version requirement (>= 2.7.0, system has 2.6.10)
+- Requires sudo password or Homebrew installation
+- User interaction needed
+
+## System Information
+
+**Current Ruby Version**: 2.6.10p210 (too old)  
+**Required Ruby Version**: >= 2.7.0  
+**Homebrew**: Not installed  
+**CocoaPods**: Not installed
+
+## Required Actions
+
+### Option 1: Install Homebrew and Ruby (Recommended)
+
+```bash
+# Install Homebrew
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Ruby
+brew install ruby
+
+# Add to PATH (add to ~/.zshrc)
+echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# Verify Ruby version
+ruby --version  # Should be >= 2.7.0
+
+# Install CocoaPods
+gem install cocoapods
+
+# Verify installation
+pod --version
+```
+
+### Option 2: Use System Ruby with sudo (Not Recommended)
+
+```bash
+# Install drb dependency (already done)
+# sudo gem install drb -v 2.0.6
+
+# Install CocoaPods (requires password)
+sudo gem install cocoapods
+
+# Note: This may still fail due to Ruby version incompatibility
+```
+
+### Option 3: Use rbenv for Ruby Version Management
+
+```bash
+# Install rbenv
+brew install rbenv ruby-build
+
+# Install Ruby 3.2.0
+rbenv install 3.2.0
+rbenv global 3.2.0
+
+# Install CocoaPods
+gem install cocoapods
+
+# Verify
+pod --version
+```
+
+## After CocoaPods Installation
+
+### For Vue 3 Test App
+
+```bash
+cd test-apps/daily-notification-test/ios/App
+pod install
+```
+
+### For Standalone iOS Test App
+
+```bash
+cd test-apps/ios-test-app/App
+pod install
+```
+
+## Verification Checklist
+
+- [ ] Ruby version >= 2.7.0 installed
+- [ ] CocoaPods installed (`pod --version` works)
+- [ ] Vue test app: `pod install` completed successfully
+- [ ] Standalone test app: `pod install` completed successfully
+- [ ] Xcode workspaces created (App.xcworkspace exists)
+- [ ] Can open projects in Xcode
+
+## Next Steps After CocoaPods
+
+1. **Install CocoaPods dependencies** (see above)
+2. **Build Vue test app web assets**:
+   ```bash
+   cd test-apps/daily-notification-test
+   npm install  # If not done
+   npm run build
+   npx cap sync ios
+   ```
+3. **Open in Xcode and build**:
+   ```bash
+   # Vue test app
+   cd test-apps/daily-notification-test/ios/App
+   open App.xcworkspace
+   
+   # Standalone test app
+   cd test-apps/ios-test-app/App
+   open App.xcworkspace  # After pod install creates it
+   ```
+
+## Documentation
+
+- [CocoaPods Installation Guide](COCOAPODS_INSTALLATION.md) - Detailed installation instructions
+- [iOS Test Apps Setup Complete](IOS_TEST_APPS_SETUP_COMPLETE.md) - What was completed
+- [iOS Sync Status](IOS_SYNC_STATUS.md) - API comparison and status
+
+## Summary
+
+**All command-line setup is complete.** The only remaining step is manual CocoaPods installation, which requires:
+1. Ruby version upgrade (>= 2.7.0)
+2. CocoaPods gem installation
+3. Running `pod install` in both test app directories
+
+Once CocoaPods is installed, both iOS test apps will be ready for building and testing in Xcode.
+