Improving iOS Build Speed with cocoapods-hmap-prebuilt Plugin

This article introduces cocoapods-hmap-prebuilt , a Meituan‑developed CocoaPods plugin that significantly speeds up iOS project compilation by leveraging Header Map technology.

Header Map is a binary mapping table that lets the compiler resolve header files via a fast in‑memory lookup instead of scanning the file system. Although Xcode provides a built‑in Header Map option, it does not work well with large CocoaPods‑based projects because of the way CocoaPods creates soft links and populates Header Search Paths.

Typical problems in a massive project (400+ pods) include:

Excessive -I options that can overflow the compiler command line.

Millions of header files causing heavy I/O during search and symlink creation.

Compilation time growing linearly with the number of components (often >1 hour for a full build).

Potential header name collisions that make later headers invisible.

Private headers becoming reachable through ${PODS_ROOT}/Headers/Private, breaking encapsulation.

The cocoapods-hmap-prebuilt plugin addresses these issues by:

Generating n+1 hmap files (one per pod plus a shared public hmap) that index all private and public headers.

Replacing the original Header Search Path entries in the xcconfig with references to the generated hmap files.

Handling duplicate public headers by storing them as PodName/Header.h keys.

Disabling the native Xcode Header Map to avoid redundant file creation.

Using the plugin only requires two steps:

/// part of Gemfile
source 'http://sakgems.sankuai.com/' do
  gem 'cocoapods-hmap-prebuilt'
  gem 'XXX'
  ...
end

// part of Podfile
target 'XXX' do
  plugin 'cocoapods-hmap-prebuilt'
  pod 'XXX'
  ...
end

In Meituan’s own iOS codebase, the plugin improves the overall build pipeline by more than 45% and reduces Xcode packaging time by over 50%.

Overall, the article demonstrates how a custom hmap generation strategy can overcome the limitations of the default CocoaPods header handling and deliver substantial build‑time gains.