daily-notification-plugin/docs/COCOAPODS_INSTALLATION.md

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.

# 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.

# 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:

# 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:

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:

# 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

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

pod update

Clean Install

pod deintegrate
pod install

Project-Specific Setup

Vue 3 Test App

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

Standalone iOS Test App

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

Troubleshooting

Pod Install Fails

1. Check Ruby version:

   ruby --version
   

2. Update CocoaPods:

   gem update cocoapods
   

3. Clear CocoaPods cache:

   pod cache clean --all
   

4. Clean and reinstall:

   rm -rf Pods Podfile.lock
   pod install
   

Xcode Workspace Not Created

After pod install, ensure App.xcworkspace exists:

ls -la App.xcworkspace

If missing, run pod install again.

Plugin Not Found

If plugin path is incorrect in Podfile:

1. Verify plugin exists:

   ls -la ../../../ios/DailyNotificationPlugin.podspec
   

2. Check Podfile path:

   pod 'DailyNotificationPlugin', :path => '../../../ios'
   

3. Update pod repo:

   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
• Homebrew Ruby Installation
• rbenv Documentation

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)