Deep Analysis and Solutions for Xcode 12 iOS Simulator Build Error: arm64 Architecture Linking Issues

Problem Background and Error Analysis

With the release of Xcode 12, many developers encountered a specific build error when upgrading their projects: "building for iOS Simulator, but linking in object file built for iOS, for architecture arm64". This error commonly occurs in projects containing mixed Objective-C and Swift code, particularly large projects using CocoaPods for dependency management.

From a technical perspective, the root cause of this error lies in Xcode 12's introduction of support for Apple Silicon. In previous Xcode versions, iOS simulators primarily ran on x86_64 architecture, while real devices used arm64 architecture. Xcode 12 began treating arm64 as a valid architecture for simulators as well, preparing for future Apple Silicon Macs. However, when certain libraries or frameworks in the project are not properly configured, the build system may attempt to link arm64 object files compiled for real devices into simulator builds, causing architecture mismatch errors.

Core Solution: Excluding arm64 Architecture in Simulator

The most direct and effective solution is to explicitly exclude arm64 architecture in simulator environments through build settings. This can be achieved in several ways:

In Xcode project settings, navigate to Build Settings and locate the Excluded Architectures setting. Add the value "arm64" for Any iOS Simulator SDK. This configuration explicitly informs the build system not to consider arm64 architecture during simulator builds, thus avoiding linking errors.

For advanced configurations using XCConfig files, add the following line to the configuration file:

EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64

This configuration is more precise, specifying that arm64 architecture should be excluded only when the SDK is iOS simulator, ensuring that real device builds remain unaffected.

Special Handling for CocoaPods Projects

Since dependencies managed by CocoaPods have their own independent build configurations, the same architecture exclusion settings need to be applied to these Pod projects. Modifying Build Settings directly in Pod projects will be overwritten by pod install, so Podfile configuration is recommended:

post_install do |installer|
  installer.pods_project.build_configurations.each do |config|
    config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
  end
end

This post_install hook ensures that every time pod install is run, the correct architecture exclusion settings are configured for all Pod projects. From an implementation perspective, this configuration modifies the xcconfig files of each Pod target, adding -arm64 to the compiler's architecture exclusion list during simulator builds.

Alternative Approach: Build Active Architecture Only

Another viable solution is enabling the Build Active Architecture Only (ONLY_ACTIVE_ARCH) setting. The core idea of this approach is to make the build system construct only the active architecture of the current run destination, rather than all supported architectures.

In project settings, set ONLY_ACTIVE_ARCH to YES, even for Release configurations. The advantage of this method is that it fundamentally avoids conflicts that may arise from multi-architecture builds, but careful attention should be paid to selecting appropriate run destinations when archiving applications.

For Pod dependencies, configuration can be done in the podspec:

spec.pod_target_xcconfig = { 'ONLY_ACTIVE_ARCH' => 'YES' }

Or configured uniformly through Podfile's post_install hook:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings["ONLY_ACTIVE_ARCH"] = "YES"
    end
  end
end

Deep Understanding of Architectural Compatibility

To thoroughly understand this issue, deep knowledge of how the Xcode build system works is required. When selecting simulator as the run destination, Xcode 12+ attempts to build variants for both x86_64 and arm64 architectures, since simulators on future Apple Silicon Macs will run on arm64 architecture.

However, on Intel-based Macs, while the build system can generate arm64 code for simulators, the linker cannot correctly link arm64 object files compiled for iOS devices because these files use different ABIs and system call conventions. Arm64 in simulator environments requires simulator-specific runtime libraries and frameworks, which differ from the arm64 implementation for real devices.

When inspecting framework files using the lipo tool, you might see multiple architectures including armv7s, armv7, i386, x86_64, and arm64, indicating that the framework itself supports multiple architectures, but configuration during the build process leads to incorrect linking behavior.

Practical Recommendations and Best Practices

In actual development, a hierarchical solution approach is recommended: first configure architecture exclusion at the project level to ensure correct main project builds; then handle all dependencies through Podfile configuration; finally, for specific performance-sensitive scenarios, consider combining with ONLY_ACTIVE_ARCH settings.

It's important to note that these solutions are primarily transitional. As Apple Silicon Macs become more prevalent and development tools mature, future Xcode versions are expected to provide more intelligent architecture handling mechanisms. Currently, while the method of excluding arm64 architecture is effective, it may impact simulator performance on Apple Silicon Macs.

For long-term project planning, it's advisable to closely monitor updates from CocoaPods and various dependency libraries, ensuring they natively support Xcode 12+'s architectural requirements. Many popular libraries have already added appropriate configurations to their podspecs to handle this issue.