跪拜 Guibai
← Back to the summary

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

How to Run a Legacy Project on the iPhone Duo Simulator under Xcode 27.1

1. The Conclusion First

A legacy project failing to run on the iPhone Duo simulator is usually not a code problem, nor a broken Xcode installation, but three things stacked together:

  1. The iOS 27.1 simulator runtime bundled with Xcode 27.1 is arm64-only and cannot run x86_64 simulator binaries;
  2. Legacy projects, for compatibility with old third-party libraries, commonly set "exclude arm64 for simulator builds" — this setting makes Duo disappear entirely from the run destination list;
  3. Several audio/video, sharing, and crash-reporting SDKs in the dependency chain only ship device slices, and become link failures the moment arm64 is enabled.

The corresponding solution comes in three stages: first make Duo a usable run destination, then remove device-slice-only dependencies from the simulator build, and finally use same-named stub libraries to cover the large number of call sites. The device build is unaffected.

Note: The project and SDK names below are fictional examples (MyApp, VideoKit, ShareKit). Replace them with your own actual names; the approach is identical.

2. Typical Symptoms, Check Yours First

When opening a legacy project in Xcode 27.1, you typically hit the following four situations in order, each with a completely different cause:

Listing the run destinations first is more reliable than repeatedly clicking around in the Xcode interface:

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -showdestinations

If this is the only arm64-only device and it is not in the list, the architecture exclusion problem in the next section is essentially confirmed.

3. Step One: Confirm This Is an arm64-Only Runtime

The deciding factor is the runtime itself, not the project configuration:

xcrun simctl list runtimes

After locating the runtime directory, look directly at its dynamic linker:

lipo -info "/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 27.1.simruntime/Contents/Resources/RuntimeRoot/usr/lib/dyld_sim"

If the output only shows arm64, the runtime can only load arm64 simulator programs. No matter how an x86_64 binary is configured, it will not start.

Therefore every previous "run old libraries with x86_64 simulator binaries" approach fails on Duo. After this confirmation, all subsequent configuration revolves around arm64 simulator builds.

4. Step Two: Make Duo Reappear in the Run Destination List

The root cause of symptom one is almost always the architecture exclusion setting. Legacy projects commonly contain this line:

EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64

It originally solved the "some old libraries lack arm64 simulator slices" problem. But on an arm64-only runtime, this line effectively removes all arm64 simulator devices from the list.

Two modification points:

# Podfile
SIM_BUILD = ENV['SIM_BUILD'] == '1'

post_install do |installer|
  Dir.glob(File.join(installer.sandbox.root, 'Target Support Files',
                     'Pods-MyApp', 'Pods-MyApp.*.xcconfig')).each do |path|
    content = File.read(path)
    # First clear the old rule, then write back per configuration, avoiding duplication and residue
    content = content.gsub(/^EXCLUDED_ARCHS\[sdk=iphonesimulator\*\] = .*\n/, '')
    content += "EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64\n" unless SIM_BUILD
    File.write(path, content)
  end
end

Run -showdestinations again after the change; Duo should appear. Do not rush to run yet, because symptom two or three will likely be hit.

5. Step Three: Distinguish Which Dependency Is Blocked at Which Layer

This is the most time-consuming part of the whole process. Do not guess from experience; confirm each one with three criteria.

1. Compile-stage failure: look at the Swift module directory

SDKs with Swift interfaces have module directories organized by "architecture-platform" in their products:

ls Pods/VideoKit/VideoKit.framework/Modules/VideoKit.swiftmodule

If only arm64-apple-ios (device) is present, without arm64-apple-ios-simulator (simulator), the Swift side reports "cannot find the type declaration," while the Objective-C side may behave normally, easily misdiagnosed as a business code problem.

2. Link-stage failure: do not look at the architecture list, look at the platform mark

lipo -info Pods/ShareKit/ShareKit.framework/ShareKit
vtool -show-build Pods/ShareKit/ShareKit.framework/ShareKit

arm64 being listed among architectures does not mean the binary can be used on the simulator. The platform field in vtool determines ownership: IOS is device, IOSSIMULATOR is simulator, and the linker only recognizes the platform.

The trap in legacy projects: in some old libraries' static products, arm64 is actually the device object, while x86_64 is the simulator object. Once the simulator build enables arm64, the linker pulls in the device object and errors out.

3. Load-stage failure: confirm whether the slice is corrupt

A more hidden case: the vendor does provide a simulator slice, but the binary itself is broken. Comparing the segment tables reveals it:

otool -l Pods/VideoKit/VideoKit.framework/VideoKit | grep -A4 LC_SEGMENT_64

Normally, fileoff and vmaddr between segments satisfy page alignment, and file ranges of adjacent segments are contiguous. If "the next segment's starting offset is a few bytes past the previous segment's end" — that kind of misalignment — memory mapping fails at load time (errno=22).

This kind of problem errors out on any runtime and any device; it is unrelated to the OS version. The only correct handling is to declare that slice unusable.

A false positive to avoid

Static libraries and static frameworks are only pulled into the link when their symbols are actually referenced. Trying to link with an empty project often "succeeds," but a real project fails immediately at link time.

Validate conclusions with a real build, or add -force_load / -ObjC to force full loading before testing.

6. Step Four: Add a Switch on the Dependency Manifest

After confirming the blockers, start working. Add an environment variable switch in the Podfile:

# No env var = device configuration; SIM_BUILD=1 = simulator configuration
SIM_BUILD = ENV['SIM_BUILD'] == '1'

target 'MyApp' do
  use_frameworks!

  # Normal dependencies are unaffected
  pod 'NetworkKit', '4.0.1'

  if SIM_BUILD
    # SDKs with only device slices are replaced with same-named local stubs
    pod 'VideoKit', :path => './Stubs/VideoKit'
    pod 'ShareKit', :path => './Stubs/ShareKit'
  else
    pod 'VideoKit', '~> 7.6'
    pod 'ShareKit', '~> 6.11'
  end
end

Usage is two commands, and the Podfile does not change:

pod install               # device configuration
SIM_BUILD=1 pod install   # simulator configuration

This keeps things cleanly separated: no matter how the simulator package changes, the device chain is unaffected.

One more detail: switching the switch rewrites the dependency lock file, so you must be able to return to the device baseline at any time. Either check the lock file into version control, or keep a separate device version, and restore it before reinstalling after switching back, to avoid versions being passively upgraded.

7. Step Five: Sort Call Sites by Count, Easy Ones First

After the dependency is removed, the code that calls it will not compile. The ordering principle is plain: sort by call-site count, fewest first.

For capabilities referenced by only one or two files, add compile conditions directly in the file:

#if !TARGET_OS_SIMULATOR
#import <VideoKit/VideoKit.h>
#endif

Provide a clear placeholder at the entry point rather than failing silently:

#if TARGET_OS_SIMULATOR
    UILabel *tip = [[UILabel alloc] init];
    tip.text = @"当前环境不支持该功能";
    tip.textColor = UIColor.secondaryLabelColor;
    [tip sizeToFit];
    tip.center = CGPointMake(CGRectGetMidX(self.view.bounds),
                             CGRectGetMidY(self.view.bounds));
    [self.view addSubview:tip];
#else
    [self setupPlayer];
#endif

Three bottom lines: the device branch code stays as-is, no opportunistic refactoring; the simulator branch must have visible feedback; compile conditions only wrap code that actually depends on that SDK.

If the SDK's capability has a clear entry point (like crash reporting), short-circuit at the entry point directly; even a placeholder is unnecessary.

8. Step Six: Use a Same-Named Stub Library to Hold Up a Large Number of Call Sites

For an SDK referenced by a dozen-plus files, adding compile conditions one by one is prohibitively expensive and litters business code with platform checks.

The cheaper approach is a stub at the dependency boundary: same name as the original library, same header file paths, all-empty implementation.

Start by copying the original library's public headers to the stub directory. The directory structure looks roughly like:

Stubs/VideoKit/
├── VideoKit.podspec
├── VideoKitStub.m
└── include/VideoKit/*.h

The podspec is just a few lines:

Pod::Spec.new do |s|
  s.name         = 'VideoKit'
  s.version      = '7.6.0-sim'
  s.source_files = 'VideoKitStub.m', 'include/VideoKit/*.h'
  s.public_header_files = 'include/VideoKit/*.h'
  s.header_mappings_dir = 'include'   # keep the <VideoKit/xxx.h> reference path unchanged
  s.frameworks   = 'AVFoundation', 'UIKit'
end

The implementation starts from empty methods:

#import <VideoKit/VideoKit.h>

@implementation VideoPlayer

+ (instancetype)player {
    return [[self alloc] init];
}

- (void)prepare {}
- (void)play {}
- (void)pause {}
- (void)stop {}
- (void)destroy {}
- (void)seekToTime:(int64_t)time {}

@end

An empty implementation is not runtime safety

An empty implementation passes compilation and linking, but at runtime, as long as business code sends the stub object a message that "exists in the header but not in the implementation," it crashes on method-not-implemented. Objects like players and share utilities that are called everywhere are especially obvious: the home screen starts up, then entering a detail page crashes immediately.

So first use logging to fish out the missed call sites:

- (void)doesNotRecognizeSelector:(SEL)aSelector {
    NSLog(@"[VideoKitStub] 未实现的接口:%@", NSStringFromSelector(aSelector));
}

There is a labor-saving pattern when filling in interfaces: properties declared in the header automatically generate accessors; what actually needs hand-writing are ordinary methods — construction, playback control, configuration read/write, previous/next track, and the like.

One more thing to remember: fallbacks only fit calls that "have no return value." If an interface with a return value is missed, the caller gets an undefined value, and when an object is returned, the next message sent to it crashes. So interfaces with return values must be implemented one by one, like configuration reading:

- (PlayerConfig *)getConfig {
    if (!_config) {
        _config = [[PlayerConfig alloc] init];
    }
    return _config;
}

The principle in one sentence: the stub is responsible for not crashing, not for being usable. Crashes and "the feature just does not respond" must be distinguishable from each other, otherwise adaptation work keeps chasing phantom faults.

9. Step Seven: Write Down the Capabilities That Are "Temporarily Absent"

The stub approach is fundamentally trading functionality for progress, and the boundaries must be stated in advance:

Writing this in the project usage documentation is far more effective than writing it in commit messages.

10. Acceptance: All Four Gates Must Pass Before It Counts as Done

# 1. The simulator package installs and starts
xcrun simctl install <UDID> build/Debug-iphonesimulator/MyApp.app
xcrun simctl launch <UDID> com.example.myapp
  1. Enter each main page one by one; no crashes caused by "method not found";
  2. Switch back to device configuration, reinstall dependencies, device build passes, functionality identical to before the change;
  3. Versions in the dependency lock file match before the change; nothing was passively upgraded.

Items 3 and 4 are the most easily overlooked. If the stub and compile conditions miss the device branch, the problem often does not surface until just before release.

11. Applicability Boundaries

Applies when: a new device's simulator just launched, core SDKs will not provide corresponding slices in the short term, but the team needs to run the interface and interactions on the new size and form factor first.

Does not apply when: you need to verify real audio/video chains, payments, push delivery rates, or other scenarios that strongly depend on vendor SDKs; those can only be verified on a device.

If you do not have a device yet, using the simulator for layout adaptation is workable, but know this is "approximate verification": size and split-screen form are close, but performance, account chains, and many system capabilities are still missing. Final confirmation still needs to happen on a device.

12. One-sentence Summary

Old configuration kept Duo out of the run destinations; old dependencies kept arm64 simulator builds stuck at the link stage.

The solution is not to wait for vendors, but: control the architecture exclusion rule in a script, add a switch on the dependency manifest, put minimal stubs in code, and use same-named stub libraries at dependency boundaries. Make the simulator package able to run the UI, and keep the device package as-is.