diff --git a/docs/COCOAPODS_INSTALLATION.md b/docs/COCOAPODS_INSTALLATION.md new file mode 100644 index 0000000..77cd1e9 --- /dev/null +++ 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) + diff --git a/docs/IOS_SETUP_REQUIREMENTS.md b/docs/IOS_SETUP_REQUIREMENTS.md new file mode 100644 index 0000000..312308c --- /dev/null +++ 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. +