Skip to content

docs: troubleshoot the Xcode FLUTTER_ build setting override warning - #700

Merged
AbhishekDoshi26 merged 3 commits into
mainfrom
docs/troubleshooting-xcode-flutter-overrides
Sep 28, 2026
Merged

AbhishekDoshi26 merged 3 commits into
mainfrom
docs/troubleshooting-xcode-flutter-overrides

Conversation

@AbhishekDoshi26

Copy link
Copy Markdown
Member

Since CLI 1.6.94, Shorebird warns when an Xcode project hard-codes FLUTTER_* build settings. The docs never explained that warning, so this adds a troubleshooting entry.

What it covers

  • When it shows up: shorebird doctor, shorebird init, and iOS / iOS-framework release and patch. It's a warning, not an error, so builds aren't blocked. Taken from iosCommandValidators and initAndDoctorValidators in doctor.dart, and from validatePreconditions, which only fails on errors.
  • The message: matches the ValidationIssue text in xcodeproj_flutter_override_validator.dart.
  • Why it matters: Flutter sets these in Generated.xcconfig, and a value in the Xcode project overrides that file. A hard-coded FLUTTER_ROOT, for example, can make Xcode build part of the app with a different Flutter than Shorebird's. That's the failure the validator's doc comment describes.
  • How to fix: remove the settings under Build Settings in Xcode.
  • Exceptions: FLUTTER_TARGET is allowed (flavor entry points), and Flutter modules are checked under .ios/ instead of ios/.

Also adds pbxproj to the shared cspell word list.

shorebird doctor and iOS release/patch warn when project.pbxproj
hard-codes FLUTTER_* build settings. Explain why and how to remove
them, and that FLUTTER_TARGET is allowed.

@AbhishekDoshi26 AbhishekDoshi26 left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed against xcodeproj_flutter_override_validator.dart and doctor.dart on shorebird main. One finding:

The intro leaves out shorebird init. The validator is in initAndDoctorValidators, and init_command.dart runs that list at the end of shorebird init. So a new user sees this warning first from init, not doctor. The PR description already lists init. Only the page is missing it.

The rest checks out: the message text matches the ValidationIssue, it's a warning (ValidationIssueSeverity.warning), FLUTTER_TARGET is the only exemption, and modules are scanned under .ios/. The validator also runs for iOS-framework release and patch (ios_framework_releaser.dart, ios_framework_patcher.dart), which "for iOS" covers well enough.

@AbhishekDoshi26

Copy link
Copy Markdown
Member Author

Pushed cacbb13. The intro now names shorebird init alongside shorebird doctor.

@AbhishekDoshi26
AbhishekDoshi26 merged commit 65ae263 into main Sep 28, 2026
4 checks passed
@AbhishekDoshi26
AbhishekDoshi26 deleted the docs/troubleshooting-xcode-flutter-overrides branch September 28, 2026 07:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant