跪拜 Guibai
← All articles
iOS

Getting Legacy iOS Apps Bootable on the iPhone Duo Simulator in Xcode 27.1

By 90后晨仔 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Apple will ship more arm64-only simulator devices, and each new one re-triggers the same three failure modes: excluded architectures, device-only SDK slices, and hidden run destinations. This Podfile switch plus stub-library pattern keeps a simulator package running the UI without waiting for SDK vendors, with the clear caveat that true verification still requires a device.

Summary

The Xcode 27.1 iPhone Duo simulator runtime ships arm64 only, with no x86_64 slices. Legacy iOS projects fail on it for three stacked reasons: their simulator builds exclude arm64 via an EXCLUDED_ARCHS setting inherited from the x86_64 era, some audio/video, sharing, and crash-reporting SDKs ship only device slices, and the arm64-only runtime hides Duo from the destination list entirely until that exclusion is lifted.

The migration path handles each stage in order. Verify the runtime is arm64-only with simctl and lipo on dyld_sim, then strip the arm64 exclusion from simulator xcconfig files through a CocoaPods post_install hook so generated files do not get overwritten. Each dependency failure needs separate diagnosis: Swift module directories reveal missing simulator interfaces, vtool platform markers (IOS vs IOSSIMULATOR) decide link-stage ownership, and otool segment tables catch corrupt slices. The fix runs through a SIM_BUILD environment switch in the Podfile that swaps device-only SDK pods for local same-named stub libraries.

Call-site handling proceeds from fewest to most references: `#if !TARGET_OS_SIMULATOR` guards for light usage, a same-named stub library with identical headers and empty implementations for heavy usage. Stubs must log unimplemented selectors via `doesNotRecognizeSelector:` and implement every method that returns a value, because empty implementations pass linking but crash at runtime. Acceptance requires the simulator app to boot and navigate all main pages, the device build to remain unchanged, and the dependency lock file to stay untouched.

Takeaways
— The iOS 27.1 simulator runtime in Xcode 27.1 is arm64-only; it cannot load x86_64 simulator binaries at all.
— Legacy projects commonly set `EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64`, which removes every arm64 simulator device (including Duo) from the run destination list.
— Confirm the runtime's architecture with `lipo -info` on `dyld_sim` inside the runtime's Resources/RuntimeRoot/usr/lib directory.
— Generated xcconfig files get rewritten on every dependency install, so the EXCLUDED_ARCHS fix goes in a CocoaPods post_install hook, not in hand-edited files.
— Compile-stage dependency failures show up in the Swift module directory: only `arm64-apple-ios` exists, no `arm64-apple-ios-simulator`.
— `lipo -info` architecture output does not reveal platform; `vtool -show-build` platform fields `IOS` (device) and `IOSSIMULATOR` (simulator) determine link-stage ownership.
— Some old static library products carry arm64 as the device object and x86_64 as the simulator object, so enabling arm64 for simulator pulls in the wrong object.
— Corrupt simulator slices crash at launch with errno=22 memory mapping failures; check the segment table with `otool -l` for offset misalignment.
— Static libraries only link referenced symbols, so empty projects give false-positive link successes; verify with a real build or force full loading via `-force_load` / `-ObjC`.
— A `SIM_BUILD` env var in the Podfile swaps device-only SDK pods for local stub pods; `pod install` and `SIM_BUILD=1 pod install` produce the two configurations without editing the Podfile.
— Keep the dependency lock file for both configurations, or switching the switch will passively upgrade dependency versions.
— Fix call sites in order of count: `#if !TARGET_OS_SIMULATOR` guards for one or two referencing files, a same-named stub library for a dozen or more.
— Stub libraries need identical pod names, public header paths, and an empty implementation; header-declared properties auto-generate accessors, but ordinary methods must be hand-written.
— Empty stub implementations crash on any message declared in the header but not implemented; override `doesNotRecognizeSelector:` to log which methods real callers invoke.
— Return-value interfaces in stubs must be implemented one by one, or callers receive undefined values that crash on the next message send.
— Acceptance requires the simulator app to install and launch, all main pages to navigate without method-not-found crashes, the device build to pass unchanged, and lock file versions to match the pre-change state.
— Features depending on unavailable SDKs on the simulator (real-time calls, platform sharing, crash reporting) must be documented in the project usage doc, not just in commit messages.
— Simulator layout verification is approximate: size and split-screen form come close, but performance, account chains, and many system capabilities are missing.
Conclusions

The arm64-only simulator runtime does not just change which architectures compile; it changes which devices even appear in the destination list. An architecture exclusion setting can hide hardware entirely, making the problem look like a project configuration issue rather than a runtime reality.

The stub-library approach is a deliberate trade of functionality for progress: its contract is "don't crash, not don't work." Teams that fail to distinguish crashes from unresponsive features will chase phantom faults during adaptation.

The advice to verify with real builds rather than empty projects is a warning about false positives: static linking only pulls in referenced symbols, so a link test in a toy project proves nothing about a real one.

The author is honest about scope: simulator verification is "approximate," and no performance, account chains, or core system capabilities can be confirmed without a device. The workflow buys UI and interaction progress but never replaces a device test pass.

Concepts & terms
EXCLUDED_ARCHS
An Xcode build setting that excludes specified architectures from builds for a given SDK. Legacy projects excluded arm64 from iphonesimulator builds to support old x86_64-only simulator libraries, but on an arm64-only runtime it removes all arm64 simulator devices from the run destination list.
arm64-only runtime
A simulator runtime whose dyld_sim dynamic linker can only load arm64 binaries. x86_64 simulator binaries built for older runtimes will not launch on it.
vtool -show-build
A tool that prints a Mach-O binary's platform field. `IOS` means device, `IOSSIMULATOR` means simulator; the linker recognizes only this platform mark, not the architectures listed by lipo.
doesNotRecognizeSelector:
An Objective-C runtime hook that fires when an object receives a message it does not implement. Stub libraries override it to log which interfaces real callers actually invoke, so the missed call sites can be found without guessing.
same-named stub library
A local CocoaPods pod that reuses the original SDK's name, version, and public header layout with an empty implementation. It satisfies compile and link for simulator builds at the cost of the actual feature.
SIM_BUILD
An environment variable switch in the Podfile that toggles between device and simulator dependency configurations without editing the Podfile. `SIM_BUILD=1 pod install` produces the simulator config; an unset variable produces the device config.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗