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
This commit is contained in:
Matthew Raymer
244
docs/COCOAPODS_INSTALLATION.md
Normal file
244
docs/COCOAPODS_INSTALLATION.md
Normal file
@@ -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)
|
||||||
|
|
||||||
157
docs/IOS_SETUP_REQUIREMENTS.md
Normal file
157
docs/IOS_SETUP_REQUIREMENTS.md
Normal file
@@ -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.
|
||||||
|
|
||||||
Reference in New Issue
Block a user