feat: iOS simulator (arm64) support

[Erkko68]

This PR completes iOS simulator (ARM64) support and the XCFramework migration, following up on feedback from Pull Request #7704 which appears to be inactive.

It removes remaining assumptions about build configurations, finalizes XCFramework usage across samples, and addresses a simulator-specific runtime issue.

Changes

Build configuration

• Introduced $(FILAMENT_OUT_NAME) in app-template.yml
• Resolves to ios-debug / ios-release based on the active Xcode configuration
• Removes hardcoded ios-release paths noted in feat: Add builds for iOS Silicon Simulator #7704

XCFramework migration

• Updated app-template.yml and all ios/samples/*/project.yml
• All samples now link against XCFrameworks
• Eliminates multi-arch ("fat") library handling

Metal (iOS simulator)

During testing, running sample apps on the simulator triggered the following assertion:

MTLValidateFeatureSupport: Depth Clip Mode is not supported on this device

To address this:

• Guarded supportsDepthClamp with #if !TARGET_OS_SIMULATOR in MetalDriver.mm

This avoids the crash on simulator builds. If there is a preferred configuration-based solution that avoids modifying source code, I’m happy to update accordingly.

Testing

• Built project in both Debug and Release configurations
• Generated all samples with xcodegen
• Ran gltf-viewer and other samples on ARM64 simulator

Notes

I’m not deeply familiar with the internals of Filament, but I’ve been using this setup over the past few weeks to run and test personal projects on ARM64 simulators.

This PR is mainly an attempt to address the gaps left in #7704 and get to a working, configuration-safe setup for simulator builds.

If there are better approaches or changes needed to match the project’s standards, I’m happy to iterate on this.

[bejado]

Thank you for the contribution! I'm a bit preoccupied at the moment, but this is on my radar and I will try my best to review this by the end of the week.

[bejado]

So far everything looks good!

I notice that when building, we leave intermediate .a static libraries inside out/ios-debug/filament/lib/arm64-iphoneos, out/ios-debug/filament/lib/arm64-iphonesimulator, out/ios-debug/filament/lib/universal, etc.

When we create an archive (running ./build.sh with the -a flag), these intermediate folders get packaged into the .tgz along with the final .xcframework outputs, which is unnecessary and will bloat the size of the archive. We should think of a way to either exclude them from the final archive or remove them after XCFramework creation.

Also, as a minor aside: libs/imagediff/CMakeLists.txt installs into a generic lib/arm64 folder because it references ${DIST_ARCH} rather than ${DIST_DIR}. This is another intermediate product that stays behind in the archive.

[Erkko68]

Thanks for the comments! I’ll be busy until Friday, but I’ll make sure to improve this by the end of the week. Thanks again!

[Erkko68]

Thanks for the review, both issues are fixed in the latest commit.

• Cleaned up intermediate iOS build dirs in build.sh to avoid bloating the .tgz.
• Updated imagediff CMake to use ${DIST_DIR} so it installs correctly.

Let me know if anything else needs tweaking.

[xseignard]

Hello @Erkko68 and @bejado

I can tell this is a more than welcome feature. Developing on a x86_64 simulator on a M-series Mac is real slow.

Having arm64 simulator support is a must have!

I tested on my side: Tahoe 26.2 on M2 Pro. Xcode 26.0.1. iPhone 16e, iPhone 17, iPhone SE (3rd gen) simulators running iOS 26.0. ✅ All good 👌

I also checked with vtools to confirm the platform tag in the static lib.

filament [feat/ios-simulator-support●] % lipo out/ios-release/filament/lib/libbackend.xcframework/ios-arm64_x86_64-simulator/libbackend.a \
    -thin arm64 -output /tmp/sim-arm64.a
filament [feat/ios-simulator-support●] % cd /tmp && ar -x sim-arm64.a BackendUtils.cpp.o
/tmp % vtool -show /tmp/BackendUtils.cpp.o | grep platform
 platform IOSSIMULATOR

All good 👌

Thanks a lot @Erkko68 for resuming this effort 🙏

@bejado do you see this landing soon? 🤞

Regards

[bejado]

Looks good to me 👍 Thanks @Erkko68 for the effort and @xseignard for helping verify!

[Erkko68]

The build-ios presubmit is failing because the regenerated sample project.pbxproj files use objectVersion = 77 (the format current XcodeGen 2.45.x emits), and the runner has Xcode_15.4 selected, which can't read it:

xcodebuild: error: ... project 'gltf-viewer' cannot be opened because it is in a future Xcode project file format (77).

XcodeGen 2.45.3 doesn't honor options.objectVersion or options.xcodeVersion, so the format can't be downgraded from the spec.

I'd suggest bumping the iOS CI jobs to Xcode 16.2 to unblock this — Xcode 16 shipped September 2024, Apple has required it for App Store submissions since April 2025, the macos-14/macos-15 runners already ship it preinstalled, and .github/actions/renderdiff-generate/action.yml is already pinned to Xcode_16.2, so this would align the iOS jobs with what the rest of the repo expects. Happy to revisit if you'd prefer a different Xcode version, or a different approach entirely (e.g. post-processing the generated pbxproj to pin an older objectVersion).

Proposed changes (pushed for review):

• Added a Select Xcode 16.2 step (sudo xcode-select -s /Applications/Xcode_16.2.app/Contents/Developer) to the build-ios jobs in .github/workflows/presubmit.yml, postsubmit.yml, and release.yml.
• Updated ios/samples/README.md:
  • Clarified that the iOS Simulator is supported on both Apple silicon (arm64) and Intel (x86_64) — the .xcframeworks carry both slices.
  • Noted that the sample Xcode projects now require Xcode 16+ to open.
• Added a release note line in NEW_RELEASE_NOTES.md covering the arm64 simulator support and the Xcode 16 bump.

Let me know if you'd like any of this adjusted before merging.

[xseignard]

I'd even bump to Xcode 26 (in another PR 😅) since it's required since yesterday to build with it to publish apps on the AppStore.

[xseignard]

praise: good catch 🦅 👁️ ARKit.framework was silently dropped because of the dependencies block redefinition

[Erkko68]

Of course there had to be one last bug! Now it looks good to go 😂

[xseignard]

Thanks for merging @bejado 🙏
Any plans for a release and publish it to the cocoapod repo?

[bejado]

Thanks for merging @bejado 🙏 Any plans for a release and publish it to the cocoapod repo?

Apologies for the delay, the CocoaPods publishing process has been giving us some trouble; even running it locally it occasionally times out. I just pushed Filament 1.71.2 to CocoaPods. Our releases are delayed 1-2 weeks, but looks like this arm64 simulator PR will make it into next week's release.