Mastering Swift/ObjC Binary Mixed Compilation: Practical Tips for Mobile Teams

Background

Swift has become the primary language for macOS and iOS, gradually replacing Objective‑C. The Kuaishou overseas client team accumulated extensive Swift/ObjC mixed‑code experience in projects such as Kwai‑Pro, MV Master, and Zynn. To boost compilation efficiency they explored binary‑based mixed compilation and resolved many practical problems.

Single‑Target Mixed Compilation

In a single target, a bridging header is set in Build Settings so Swift can access ObjC and Swift generates a -Swift.h for ObjC calls. However, this method disables Swift version‑compatibility flags, so the recommended approach is to use OTHER_SWIFT_FLAGS with -import-underlying-module together with HEADER_SEARCH_PATHS to let Swift access ObjC interfaces.

Multi‑Target Mixed Compilation

When componentizing the codebase, each Pod component is compiled in an independent target, requiring Swift/ObjC mixed compilation across multiple targets. The team faced several obstacles:

First obstacle – OC component Clang module

OC components must be modularized using Clang modules. Setting modular_header => true in the Podfile generates a modulemap and umbrella.h . However, mixing modular and non‑modular OC components introduces import issues; modules require #import <Framework/FrameworkHeader.h> or @import Framework.FrameworkHeader instead of traditional header‑search paths.

Second obstacle – Hard‑to‑module Pod components

Some legacy OC Pods cannot be modularized. The team solved this by either removing the dependency declaration and using “implicit” header search paths, or adding a thin OC adapter layer between C++ and Swift components.

Third obstacle – Swift binary compatibility

Swift lacks header files; it produces swiftmodule binaries that are compiler‑specific. Since Swift 5.1, the BUILD_LIBRARY_FOR_DISTRIBUTION flag generates a textual swiftinterface file, which is compatible across compiler versions, solving binary compatibility issues.

Fourth obstacle – Binary mixed compilation

Pre‑compiled static libraries are packaged as XCFrameworks with module information (modulemap, swiftinterface). To support mixed compilation of binary and source Pods, the team ensures all dependent components are packaged as frameworks and that module paths are correctly added to FRAMEWORK_SEARCH_PATHS , OTHER_CFLAGS , and OTHER_SWIFT_FLAGS .

Additional Practical Solutions

Flatten header hierarchies in XCFrameworks to a single Headers directory, simplifying import statements.

During pod install , automatically replace legacy import paths with module‑style imports using regex scripts.

Disable the VendoredFrameworkSearchPath service to force header lookup through modulemaps only.

Provide a fake framework structure during pod installation to satisfy build‑order constraints when actual framework targets are compiled later.

Future Outlook

The team plans to improve library‑level standardization, publish public headers, increase the proportion of modularized components, and monitor C++ module support progress to further accelerate compilation and packaging.