Skip to content

Docs: stop telling Flutter developers to exclude arm64 from the iOS simulator build - #596

Open
amitthacker-maker wants to merge 2 commits into
cometchat:mainfrom
amitthacker-maker:fix/ios-simulator-arm64
Open

amitthacker-maker wants to merge 2 commits into
cometchat:mainfrom
amitthacker-maker:fix/ios-simulator-arm64

Conversation

@amitthacker-maker

Copy link
Copy Markdown

What these pages told developers to do

Four Flutter setup pages asked readers to add this to their Podfile:

build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64 i386'

Why that breaks the build

On an Apple Silicon Mac the iPhone simulator runs on arm64. Excluding arm64 from the simulator
build therefore removes the only architecture the simulator can use, and the app stops building for
it. Apple Silicon arrived in late 2020 and is the whole current Mac lineup, so this affects
essentially every new developer machine. These are setup pages, so it is among the first
instructions a new Flutter developer follows.

Each page already carried a <Warning> further down telling Apple Silicon users to exclude only
i386 instead. So the page contained both the wrong instruction and its correction, with the wrong
one in the copyable code block and the correction below it. A developer who copied the block and
moved on got a broken build.

How I know the arm64 exclusion is not needed

Rather than check whichever version is newest, I followed the dependency each page tells the
reader to install
, down to the iOS framework it resolves to, and read that XCFramework's own
Info.plist. These four pages span three different generations:

Page What the page installs Resolves to Simulator library Architectures
sdk/flutter/setup.mdx cometchat_sdk: ^5.0.8 (5.0.9) CometChatSDK 4.1.0 ios-arm64_x86_64-simulator arm64, x86_64
sdk/flutter/v4/setup.mdx cometchat_sdk: ^4.0.33 CometChatSDK 4.0.73 ios-arm64_x86_64-simulator arm64, x86_64
sdk/flutter/3.0/setup.mdx, sdk/flutter/3.0/overview.mdx cometchat: any (3.0.13) CometChatPro 3.0.920 ios-arm64_x86_64-simulator arm64, x86_64

All three declare SupportedPlatformVariant: simulator with arm64 among the supported
architectures. So on every path these pages cover, the simulator build has an arm64 slice available
and the exclusion only takes it away.

Why the line is deleted rather than narrowed

Narrowing to i386 would not be right either, for two reasons.

The i386 half is inert. i386 is 32-bit Intel, and no supported Xcode builds an i386 simulator
slice, so the exclusion has nothing to act on. For completeness: the one i386 slice I found on these
paths is in the CometChatStarscream framework bundled with CometChatPro 3.0.920, whose simulator
library is ios-arm64_i386_x86_64-simulator. arm64 and i386 sit in the same library there, so
excluding i386 neither helps nor harms arm64.

The reader never needed to write it. Each of the three plugin versions above already sets this
in its own podspec:

s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
  • cometchat_sdk 5.0.9, ios/cometchat_sdk.podspec line 24
  • cometchat_sdk 4.0.33, ios/cometchat_sdk.podspec line 24
  • cometchat 3.0.13, ios/cometchat.podspec line 22

With the arm64 half actively harmful and the i386 half both inert and already handled by the
plugin, nothing in the setting is worth keeping, so the whole Podfile block goes.

What changed on each page

  • The Podfile post_install block is removed, and the numbered steps that followed it are
    renumbered. The block contained nothing but the EXCLUDED_ARCHS line and Flutter's own default
    post_install boilerplate, so no working instruction is lost.
  • The old <Warning> is replaced with a <Note> aimed at readers who already followed the old
    page, telling them to remove the arm64 exclusion from their Podfile. Deleting the warning
    silently would leave those readers with a broken project and no explanation. Each note names the
    package that page actually installs, so the 3.0 pages refer to cometchat and the others to
    cometchat_sdk.

Pages: sdk/flutter/setup.mdx, sdk/flutter/v4/setup.mdx, sdk/flutter/3.0/setup.mdx,
sdk/flutter/3.0/overview.mdx.

sdk/flutter/3.0/setup.mdx also had its <Warning> sitting inside <Tabs> after the closing
</Tab>. Removing it fixes that malformation too.

Deliberately not in scope

  • iOS calling pages. The arm64 exclusion on the calling side may be intentional and is under
    separate review, so no calling page is touched here.
  • Five pages that give the same advice in prose, which a grep for EXCLUDED_ARCHS alone does
    not find: sdk/ios/2.0/overview.mdx, sdk/ios/2.0/setup.mdx, sdk/ios/3.0/overview.mdx and
    sdk/ios/3.0/setup.mdx each have an "Excluded Architecture" section, and
    sdk/flutter/v4/troubleshooting.mdx has a table row offering the exclusion as the fix for a
    failing simulator build. They need the same separate review and are not included.

calls/platform/compatibility.mdx also mentions arm64, but only to state the supported
architecture, which is correct and left alone.

How the scope was established

git grep EXCLUDED_ARCHS -- '*.mdx' returns exactly seven files on main. Three are calling pages,
held back as above, leaving the four here. The prose search was run separately, because the
build-setting grep misses pages that give the same advice in words.

Note for the reviewer

A Mintlify preview will not build for a pull request from a fork until someone with write access
approves the commit, so the preview links show nothing until that approval.

🤖 Generated with Claude Code

@mintlify

mintlify Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 275231c.

Approve preview

AmitAtomChat and others added 2 commits November 17, 2026 16:17
…imulator build

Four Flutter setup pages carried a Podfile line setting EXCLUDED_ARCHS for the
iPhone simulator to 'arm64 i386', and a Warning below it telling Apple Silicon
readers to narrow that to 'i386'. So each page held both the wrong instruction
and its correction, with the wrong one in the copyable code block. On an Apple
Silicon Mac the simulator runs on arm64, so a reader who copied the block
removed the only architecture the simulator can use and the build stopped
working.

Narrowing to 'i386' would not have been right either, so the line is removed
and the Podfile step with it.

For each page I followed the dependency the page itself tells the reader to
install, down to the iOS framework it resolves to, and read that XCFramework's
own Info.plist. All three generations ship an arm64 simulator library:

  sdk/flutter/setup.mdx
    cometchat_sdk ^5.0.8 (5.0.9) -> CometChatSDK 4.1.0
    ios-arm64_x86_64-simulator, archs [arm64, x86_64]

  sdk/flutter/v4/setup.mdx
    cometchat_sdk ^4.0.33 -> CometChatSDK 4.0.73
    ios-arm64_x86_64-simulator, archs [arm64, x86_64]

  sdk/flutter/3.0/overview.mdx, sdk/flutter/3.0/setup.mdx
    cometchat: any (3.0.13) -> CometChatPro 3.0.920
    ios-arm64_x86_64-simulator, archs [arm64, x86_64]

The i386 half of the setting is inert. No supported Xcode builds an i386
simulator slice, and each of these three plugin versions already sets
EXCLUDED_ARCHS to 'i386' in its own podspec, so the reader never needed to write
it.

The Podfile block held nothing but that line plus Flutter's own default
post_install boilerplate, so the whole step goes and the steps after it are
renumbered. Each Warning is replaced by a Note telling anyone who already
followed the old page to take the exclusion out of their Podfile, since they are
the readers who are actually broken.

iOS calling pages are deliberately untouched and under separate review.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…l page

The last page still setting EXCLUDED_ARCHS to 'arm64 i386' in a build
snippet. On an Apple Silicon Mac the iPhone simulator runs arm64, so
the setting stops the app building for the simulator.

The exclusion line is gone and the Apple Silicon warning underneath it,
which told the reader to exclude only i386, is replaced by a note for
anyone upgrading an existing app. The note does not repeat the claim
about the plugin excluding i386 on its own, which is unverified.

The two other React Native pages that carried this line, calling-integration
and call-features, were rewritten on main and no longer have it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@amitthacker-maker

Copy link
Copy Markdown
Author

Rebased onto main and extended to React Native. Five files now.

What this fixes

These pages told developers to put this in their Podfile:

build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64 i386'

Every Mac sold since late 2020 is Apple Silicon, and the iPhone simulator on those machines runs arm64. Excluding arm64 leaves no slice to build for the simulator, so a developer who follows the setup guide line by line hits a failed simulator build on the step right after install. That is the happiest path we have.

It also removes a contradiction. main already carried a warning block, directly beneath the snippet, telling Apple Silicon users to exclude only i386. The page argued with itself, which is worse than either version alone, because a careful reader cannot tell which half to trust.

i386 is dropped rather than kept. It is 32-bit Intel, the simulator has carried no i386 slice since Xcode 10, and these pages set a deployment floor of iOS 12 or 13, so excluding it matches nothing. Trimming the line to 'i386' would leave a half-true setting that invites someone to add arm64 back later.

What changed

  • The Podfile block is gone from the four Flutter pages, replaced by a note for anyone upgrading an existing app, whose own Podfile still carries the exclusion.
  • ui-kit/react-native/v4/call-features.mdx was the one remaining page setting the same value in a build snippet. The exclusion line is gone and the now-redundant Apple Silicon warning is replaced by the same upgrade note.
  • ui-kit/react-native/calling-integration.mdx and ui-kit/react-native/call-features.mdx carried this line too, but were rewritten on main since and no longer need it.

After this, grep -rn "EXCLUDED_ARCHS" --include="*.mdx" . returns only prose inside those notes, never a build_settings line.

Rebase detail

The conflict was in sdk/flutter/setup.mdx, where main had moved the iOS deployment target from 11 to 13 and renumbered the steps. Resolved by keeping this branch's structure and main's newer figure of 13.

One thing for the reviewer

The note on all four Flutter pages says the plugin "already excludes i386 on its own, so no Podfile change is needed here". I could not verify that claim from a published source, and it tells developers to do nothing. It is worth either sourcing or cutting before merge. The React Native note deliberately leaves the claim out.

The behaviour described here is reasoned from how EXCLUDED_ARCHS works and from the warning block already on these pages. It has not been confirmed by building a sample app on an Apple Silicon machine.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants