• A library dependency management tool (iOS & OS X)
  • Manage dependencies (called Pods) and their versions
  • Why?
    1. It’s a error-prone process that should be automated. CocoaPods link the library for you and configures the compiler settings automatically
    2. CocoaPods make it easy to discover libraries.
  • Components:
    1. Written in Ruby, has several Ruby Gems
    2. Most important Gems: CocoaPods/CocoaPod, CocoaPods/Core & CocoaPods/Xcodeproj
    3. CocoaPod: activated when calling pod command.
    4. Core: provides support for working with Podfile & Podspecs
      1. Podfile: defines the pods to be used
      2. Podspec: defines how the pod is added (compiler flags ..)
    5.  XcodeProj: create and modify .xcodeproj and .xcworkspace files


  1. sudo gem install cocoapods    // Install cocoapods
  2. pod init    // create Podfile (on project directory) – and edit
    platform :ios, '7.0'
    pod 'AFNetworking', '~> 2.0'
  3. pod install –verbose     //  (on project directory) – it will create the xcworkspace
  4. #import <AFNetworking/AFNetworking.h> in the project

Sometimes there is a need to remove a pod version (pod –version //see current version)

To remove current version:

sudo gem uninstall cocoapods

Install a specific version of cocoa pods:

sudo gem install cocoapods -v 0.25.0

Understanding (pod install) process

  1. First step, (pod install) will go through the list and load all .podspecs !!!
  2. Then, for each .podspec, it will load the source files ! (the source files are usually resolved to be of a specific commit SHA, loaded to ~/Library/Caches/CocoaPods)
  3. Every time (pod install) and changes detected -> Pods.xcodeproj will be updated by the Xcodeproj gem.
  4. For each pod target, the source files and other files are added:
    1. .xcconfig (build settings)
    2. Private .xcconfig (merge of settings and default Cocoapods)
    3. prefix.pch & dummy.m (required for building)
  5. : instructions how to add resource bundles of each pod to the project
  6. Pods-environment.h : a macro to check if component is from pod
  7. Write Pods.xcodeproj , Podfile.lock and Manifest.lock to disk !
    1. Podfile.lock: all version of pod that have been resolved (this file is recommended to add into source control)
    2. Manifest.lock: a copy of Podfile.lock, this file is for developers, it ensures that the pods that developer is using match the resolved pods.
    3. Pods.xcodeproj: Xcode is still using the old plist file format to save these xcodeproj, while the writing of those files is not supported any more so Pods.xcodeproj is written as XML plist. This will cause large difference in source control. The way to resolve it is using xcproj.
  8. The Cocoapods have 2 strengths:
    1. It automatically does linking the correct version of pods for you. It saves a lot of time and manual work and allows you to use automated CI.
  9. Automated CI
    1. Make sure (pod install) is run before every build (as a build step)
    2. Podfile must be in source control, .xcworkspace and Podfile.lock also.

Pod-file syntax (actually Ruby)

  1. Specify a pod – using latest version
    pod 'AFNetworking' - this will get the latest version
  2. Fix a version
    pod 'AFNetworking', '1.0' - this will fix the version, replace '1.0' with '> 1.0', '>= 1.0', '< 1.0', '<= 0.1','~> 0.1.2' (Version 0.1.2 and the versions up to 0.2, not including 0.2)
  3. Choose a branch
    pod 'Objection', :head
  4. Choose a specific commit:
    pod 'AFNetworking', :git => '' , :commit => '082f8319af'
  5. Choose a specific podspec:
    pod 'JSONKit', :podspec => '' 
  6. Choose a location that we already have downloaded (on our computer)
    pod 'JSONKit', :path => '../../jsonkit-local'
    // This is important to update development pods !!!


A specification describing a version of the pod – do |spec| = 'Reachability' - name of the pod
spec.version = '3.1.0' - version of the pod
spec.license = :type => 'BSD' - see link
spec.homepage = ''
spec.authors = 'Tony Million' => ''
spec.summary = 'ARC and GCD Compatible Reachability Class for iOS and OS X.'
spec.source = :git => '', :tag => 'v3.1.0' - location to retrieve
spec.source_files = 'Classes/*.{h,m}'
spec.framework = 'SystemConfiguration' - list of system frameworks that needed to link against.
 spec.dependency 'AFNetworking', '~> 1.0' - dependency on other pods
 spec.requires_arc = true
 spec.xcconfig = { 'OTHER_LDFLAGS' => '-lObjC' } - flag to add to the xcconfig file
 spec.ios.vendored_library = 'Libraries/libPayPalEC.a' // attach a static library to our Pods