Cocoapods‑sled: A Simple CocoaPods Plugin for Caching and Reusing Xcode Build Results

Cocoapods‑sled is a lightweight CocoaPods plugin that caches Xcode compilation results and automatically converts reusable pods into binary form, aiming to become a primary tool for iOS build optimization.

Features

Low integration cost : plug‑and‑play, no pre‑compilation or private source requirements.

Local cache : caches compiled results under ~/Caches/CocoaPods/Frameworks , separating device and simulator caches.

Binary conversion : automatically switches between source and binary pods.

All pods reusable : even Development Pods can reuse compiled results.

Implementation Idea

The plugin mirrors Xcode’s DerivedData cache, stores compiled artifacts, and during pod install [device|simulator] replaces matching source specs with the cached binary, avoiding redundant builds.

Intercept the original pod install flow after dependencies are downloaded and inject binary logic.

Generate a cache path for each pod.

Check the cache directory for a matching binary. If found, replace the source with the binary and optionally generate Header Search Paths. If not found, insert a sync script into the pod target’s Build Phases to extract the build result to ~/Caches/CocoaPods/Frameworks for future reuse.

Continue the normal pod install process from the Generating Pods project step.

Installation

You can install the plugin via one of two methods:

Add to your Gemfile : gem 'cocoapods-sled' then run bundle install .

Install directly from the terminal: gem install cocoapods-sled

Usage

Help Documentation

bundle exec pod install --help
bundle exec pod install device --help
bundle exec pod install simulator --help

Enable Binary Mode

The plugin adds two sub‑commands to pod install : device for real‑device builds and simulator for simulator builds.

bundle exec pod install device

bundle exec pod install simulator

Running pod install without a sub‑command uses the original source‑only flow.

Command‑Line Options

--no-binary-pods=pod1,pod2 : disable binary caching for specified pods (overrides --all-binary ).

--binary-pods=pod1,pod2 : whitelist only the listed pods for binary caching.

--all-binary : force binary caching for all pods, ignoring :binary => false in the Podfile.

--configuration=[Debug|Release|custom] : separate cache directories per build configuration.

--header-search-path : generate Header Search Paths for Objective‑C imports.

--project=name : differentiate caches for multiple Xcode projects.

--no-dev-pod : disable binary caching for Development Pods.

--force-sync-dev-pod : force caching of Development Pods even when local changes exist.

--inhibit-all-warnings : suppress all pod compilation warnings.

--cache-limit=num : set the maximum number of cached versions per pod (minimum 3).

--dep-check=[single|all] : verify dependency version changes (useful for ARC alignment issues).

--check-xcode-version : include Xcode version in cache key to avoid cross‑version reuse.

Podfile Configuration

After adding the plugin to the Podfile, you can enable binary mode with the device or simulator sub‑commands. Additional helper methods simplify command‑line options:

# Declare the plugin
plugin 'cocoapods-sled'

# Generate Header Search Paths
sled_enable_generate_header_search_paths!

# Disable Development Pod binary cache (default is enabled)
sled_disable_binary_cache_for_dev_pod!

# Whitelist specific pods for binary caching
sled_enable_binary_pods 'RxSwift'

# Example pod declarations
pod 'RxSwift', :binary => false   # disable binary for this pod
pod 'RxCocoa', :binary => true    # enable binary (default)
pod 'Bugly',   :binary => :ignore # ignore binary handling for this pod

Examples

Case 1 – Develop SledLogin and SledRoute, use real‑device debugging

Option 1 (modify Podfile):

pod 'SledLogin', :path => '../SledLogin', :binary => false
pod 'SledRoute', :git => "#{BASE}/SledRoute", :commit => 'f02079ae', :binary => false
pod 'RxSwift', '6.7.0', :binary => false

Then run:

bundle exec pod install device

Option 2 (recommended) – use command‑line flags to avoid Podfile changes:

bundle exec pod install device --all-binary --no-binary-pods=SledLogin,SledRoute

Case 2 – Switch to simulator debugging

bundle exec pod install simulator --all-binary --no-binary-pods=SledLogin,SledRoute

Case 3 – CI build on a build machine

# Ensure consistent environment
bundle exec pod install device \
  --all-binary \
  --configuration=Release \
  --force-sync-dev-pod \
  --dep-check=single \
  --check-xcode-version \
  --cache-limit=12 \
  [--header-search-path] [--project=MyApp]

Common Issues

1. ARC misalignment

Use --dep-check=single to check direct dependencies; this often resolves occasional ARC alignment crashes.

2. Missing headers imported with #import ""

Enable Header Search Path generation via the command‑line flag --header-search-path or add sled_enable_generate_header_search_paths! to the Podfile. Individual pods can also be configured with pod 'xxx', :hsp => true .

3. Static‑linking errors in transitive dependencies

Correct the @build_type attribute or use use_frameworks! :linkage => :static to ensure static and dynamic frameworks are properly declared.

Supplement

If you find the plugin useful, consider starring the repository at https://github.com/git179979506/cocoapods-sled .