Understanding CocoaPods Podspec: Structure, Parsing, and Practical Usage

Table of Contents

This guide explores the implementation details, principles, source code, and practical experience of CocoaPods' pod install and pod update commands.

Introduction

Building on the previous article about Podfile parsing logic , we now examine the Podspec file, which describes how a pod's source code and resources are packaged into a library or framework.

Podspec Basics

A .podspec file (or .json ) is essentially a Ruby DSL that defines a Specification (or Spec ) object. It maps attributes such as name , version , source , and source_files to a hash that CocoaPods consumes.

Simple Example

Pod::Spec.new do |spec|
  spec.name          = 'Reachability'
  spec.version       = '3.1.0'
  spec.license       = { :type => 'BSD' }
  spec.homepage      = 'https://github.com/tonymillion/Reachability'
  spec.authors       = { 'Tony Million' => '[email protected]' }
  spec.summary       = 'ARC and GCD Compatible Reachability Class for iOS and OS X.'
  spec.source        = { :git => 'https://github.com/tonymillion/Reachability.git', :tag => "v#{spec.version}" }
  spec.source_files  = 'Reachability.{h,m}'
  spec.framework     = 'SystemConfiguration'
end

Running pod lib create NAME generates a similar spec automatically.

Advanced Configuration

Pod::Spec.new do |spec|
  spec.name          = 'Reachability'
  # ... omitted ...
  spec.module_name   = 'Rich'
  spec.swift_version = '4.0'
  spec.ios.deployment_target = '9.0'
  spec.osx.deployment_target = '10.10'
  spec.source_files       = 'Reachability/common/*.swift'
  spec.ios.source_files   = 'Reachability/ios/*.swift', 'Reachability/extensions/*.swift'
  spec.osx.source_files   = 'Reachability/osx/*.swift'
  spec.framework          = 'SystemConfiguration'
  spec.ios.framework      = 'UIKit'
  spec.osx.framework      = 'AppKit'
  spec.dependency 'SomeOtherPod'
end

The full list of configurable attributes is illustrated in the accompanying diagram.

Convention Over Configuration (CoC)

CocoaPods follows the CoC principle, similar to Ruby on Rails, Maven, and npm, to reduce configuration overhead and improve developer experience.

Specification Core Data Structure

Specification Class

The Specification class mirrors the TargetDefinition structure as a multi‑branch tree. Key attributes include name , version , attributes_hash , and subspecs . The root method walks up the parent chain to locate the top‑level spec.

require 'active_support/core_ext/string/strip.rb'
require 'cocoapods-core/specification/consumer'
require 'cocoapods-core/specification/dsl'
require 'cocoapods-core/specification/linter'
require 'cocoapods-core/specification/root_attribute_accessors'
require 'cocoapods-core/specification/set'
require 'cocoapods-core/specification/json'
module Pod
  class Specification
    include Pod::Specification::DSL
    include Pod::Specification::DSL::Deprecations
    include Pod::Specification::RootAttributesAccessors
    include Pod::Specification::JSONSupport
    attr_reader :parent, :hash_value, :attributes_hash, :subspecs
    def root
      parent ? parent.root : self
    end
    def hash
      @hash_value ||= (name.hash * 53) ^ version.hash
    end
    # ... other methods ...
  end
end

Subspecs

Subspecs are child specifications that can be independently depended upon. They inherit attributes from their parent spec and may define their own source files, frameworks, and dependencies.

Pod::Spec.new do |s|
  s.subspec 'QMUICore' do |ss|
    ss.source_files = 'QMUIKit/QMUIKit.h', 'QMUIKit/QMUICore', 'QMUIKit/UIKitExtensions'
    ss.dependency 'QMUIKit/QMUIWeakObjectContainer'
    ss.dependency 'QMUIKit/QMUILog'
  end
  # ... other subspecs ...
end

QMUIKit defines 64 subspecs, illustrating large‑scale modularization.

Podspec from JSON

CocoaPods can load a podspec from a JSON file using Specification.from_json , which parses the JSON into a hash and then builds a Specification object recursively.

def self.from_file(path, subspec_name = nil)
  path = Pathname.new(path)
  raise Informative, "No Podspec exists at path `#{path}`." unless path.exist?
  string = File.open(path, 'r:utf-8', &:read)
  string.encode!('UTF-8') if string.respond_to?(:encoding) && string.encoding.name != 'UTF-8'
  from_string(string, path, subspec_name)
end

def self.from_string(spec_contents, path, subspec_name = nil)
  case path.extname
  when '.podspec'
    Dir.chdir(path.parent.directory? ? path.parent : Dir.pwd) do
      spec = ::Pod._eval_Podspec(spec_contents, path)
      raise Informative, "Invalid Podspec file at path `#{path}`." unless spec.is_a?(Specification)
    end
  when '.json'
    spec = Specification.from_json(spec_contents)
  else
    raise Informative, "Unsupported specification format `#{path.extname}` for spec at `#{path}`."
  end
  spec.defined_in_file = path
  spec.subspec_by_name(subspec_name, true)
end

Podspec from Ruby

The Ruby DSL uses attribute and root_attribute wrappers to dynamically generate setter methods that store values in attributes_hash . Example:

module Pod
  class Specification
    module DSL
      extend Pod::Specification::DSL::AttributeSupport
      attribute :name, required: true, inherited: false, multi_platform: false
      root_attribute :version, required: true
    end
  end
end

These wrappers ultimately call store_attribute to populate the hash.

Creating and Using Your Pod

Pod Creation

Run $ pod lib create NAME and follow the prompts to scaffold a new library. After adding source files and dependencies, you can lint the pod with $ pod lib lint PATH .

Publishing a Pod

For public distribution, use $ pod trunk push NAME.podspec after registering with CocoaPods. For private repos, use $ pod repo push REPO_NAME SPEC_NAME.podspec .

Using Subspecs in a Podfile

Subspecs can be referenced directly in a Podfile. When a single target depends on multiple subspecs, CocoaPods creates a single aggregated target; with multiple app targets, separate targets are generated for each subspec.

target 'Demo' do
  pod 'QMUIKit/QMUIComponents/QMUILabel', :path => '../QMUI_iOS'
  pod 'QMUIKit/QMUIComponents/QMUIButton', :path => '../QMUI_iOS'
end

target 'Demo2' do
  pod 'QMUIKit/QMUIComponents/QMUILog', :path => '../QMUI_iOS'
end

Conclusion

The article covered:

Initial exploration of Podspec capabilities and configuration categories.

Deep dive into the data structure, showing its similarity to Podfile as a tree of dependencies.

How Subspec enables fine‑grained management of large libraries.

The use of Ruby's decorator pattern to implement a clean DSL.

Knowledge Check

List the main configuration categories supported by Podspec and their functions.

Explain the relationship between Podspec and Subspec .

Describe the characteristics and purpose of a Subspec .

Compare the DSL parsing of Podspec with that of Podfile .

References

[1] Podfile parsing logic – 2020/09/16

[2] CocoaPods‑Core repository

[3] QMUIKit podspec on GitHub

[4] CocoaPods CDN Service

[5] Specs repository

[6] Podspec syntax guide

[7] Ruby on Rails documentation

[8] TargetDefinition reference

[9] Python decorator vs Ruby implementation

[10] Using pod lib create

[11] Setting up CocoaPods trunk

[12] Private CocoaPods guide