Accelerate iOS Builds: Binary Pods Strategy with Switchable Source Mode

Current State of iOS Build Solutions

Many iOS teams have modularized their projects with CocoaPods. The typical structure includes a main (host) project that contains the application entry point and a Pods project that holds third‑party libraries (e.g., Alamofire) and modular business components (e.g., ModuleA, ModuleB).

Building iOS code involves preprocessing, compilation, assembly, and linking. Although the Pods project consists of stable third‑party binaries, each build still recompiles these pods, wasting time. Binary‑ization solves this by pre‑compiling stable code into binary frameworks and linking them at the final stage, dramatically speeding up the overall build.

Binary‑ization Schemes

After binary‑izing the Pods project, the main project can link directly to the pre‑built binaries, eliminating the need to re‑compile Pods each time.

Two practical schemes are commonly used:

Scheme 1 : Manually compile the Pods into binaries and drag the binaries into the main project.

Scheme 2 : Compile Pods into binaries, generate a private podspec for each binary, and let CocoaPods manage the dependency.

Scheme Comparison

Both schemes achieve build‑time reduction, but Scheme 1 requires manual management of binary dependencies and is only suitable when binaries are immutable. Scheme 2 leverages CocoaPods for automated management and is the more feasible practice.

Unresolved Pain Points

The major drawback of binary‑ization is poor development and debugging experience. Since third‑party components and business modules are packaged as binaries, source code is unavailable for inspection when crashes occur, making debugging difficult.

Meituan’s zsource tool mitigates this by restoring source files to their original paths during debugging, allowing breakpoints to work as if the code were not binary‑ized. However, it still cannot place breakpoints on arbitrary lines or modify Pods source on the fly.

Exploration of Solutions

We considered hijacking Xcode’s debug communication to map source breakpoints to binary code, but the complexity was prohibitive. We also explored recompiling changed Pods on demand, but this introduced fragile build‑configuration changes.

Ultimately, we decided to design a switchable build system that toggles between source mode (for development) and binary mode (for CI/release) with minimal overhead.

Solution Practice

Generating Binary Files

We compile Pods into binaries during the post_install hook of pod install/update. The script rebuilds user schemes, identifies updated pods, and runs xcodebuild for each target:

post_install do |installer|
  # Recreate Pods project schemes
  installer.pods_project.recreate_user_schemes(:visible => true)
  installer.pods_project.save

  podsProjectPath = File.dirname(Pathname(installer.sandbox.project_path))
  updatedPodsNames = []
  installer.installed_specs.each { |spec| updatedPodsNames.push(spec.name) }

  installer.aggregate_targets.each do |aggregateTarget|
    aggregateTarget.pod_targets.each do |target|
      if updatedPodsNames.include?(target.name)
        system('xcodebuild -project ' + podsProjectPath + '/Pods.xcodeproj -scheme ' + target.name + ' -configuration Release -quiet build')
      end
    end
    break
  end
end

After running the command, a Build folder appears at the project root containing the compiled frameworks.

Switching Between Source and Binary Modes

We define an environment variable USE_LIB in the Podfile to select the mode:

$USE_LIB = ENV['USE_LIB']

target 'MainProject' do
  use_frameworks!
  if $USE_LIB
    # Binary mode: use a temporary Development Pod that points to the pre‑built binaries
    pod 'Binaries', :path => './'
  else
    # Source mode: depend on the original Pods
    pod 'ModuleA'
    pod 'ModuleB'
    pod 'Alamofire'
    pod 'RxSwift'
    pod 'SwiftyJSON'
  end
end

post_install do |installer|
  unless $USE_LIB
    # Compile updated Pods into binaries (same script as above)
    ...
  end
end

Running USE_LIB=true pod install/update switches the project to binary mode, while a plain pod install/update keeps it in source mode.

Creating the Binary Podspec

The binary podspec lists the compiled frameworks via the vendored_frameworks attribute:

Pod::Spec.new do |s|
  s.name = "Binaries"
  s.version = "1.0.0"
  s.vendored_frameworks = [
    'build/Release-iphoneos/Alamofire/Alamofire.framework',
    'build/Release-iphoneos/ModuleA/ModuleA.framework',
    'build/Release-iphoneos/RxSwift/RxSwift.framework',
    'build/Release-iphoneos/ModuleB/ModuleB.framework',
    'build/Release-iphoneos/SwiftyJSON/SwiftyJSON.framework'
  ]
end

Dynamic generation of vendored_frameworks can be achieved by reading a frameworks.json file produced during the binary build.

Handling Closed‑Source Pods

Closed‑source SDKs (e.g., Bugly, Reveal‑SDK) are always linked regardless of the mode. A helper method binaryPods adds these dependencies in both source and binary branches.

Best Practices

During development, use the default source mode to enjoy full debugging capabilities. Incremental compilation ensures only changed Pods are rebuilt. In CI or release builds, set USE_LIB=true to enable binary mode and achieve fast compilation.

Additional environment flags such as NO_COMPILE (skip binary generation) and COMPILE_ALL (force full rebuild) can fine‑tune the workflow.

Conclusion

The presented approach reconciles the trade‑off between build speed and debugging convenience by providing a switchable binary‑source system. It has been applied in numerous iOS projects at our company, integrating smoothly with continuous‑integration pipelines while maintaining a good developer experience.

“上帝基Christ化人，超凡入圣，返璞归真。”