Flavors documentation omits important section for `appFlavor` when building from XCode

[navaronbracke]

Page URL

https://docs.flutter.dev/deployment/flavors

Page source

No response

Describe the problem

The flavors documentation does not include a step to set the FLUTTER_APP_FLAVOR Dart define for the appFlavor constant. This is important to include when building from XCode, as otherwise the appFlavor is null.

Expected fix

When setting up Schemes in XCode, we should also add the following to the documentation: 1) Navigate to the Build Settings of the target(s) 2) If DART_DEFINES does not exist yet 2a) Click the + button in the top left 2b) Click Add User-Defined Setting 2c) For the name enter DART_DEFINES 2d) For the value take the base64 encoded version of FLUTTER_APP_FLAVOR=<value>, where <value> is the name of the flavor that is expected to be the appFlavor in Dart 3) If DART_DEFINES does exist, the values are delimited by a comma (this should be verified, I am not sure) But it is important to encode the entire string as base64 4) If DART_DEFINES is already defined in Generated.xcconfig, delete the Generated.xcconfig and enter the Dart defines in XCode, before trying again.

Additional context

I confirmed that this is not a tool bug, as the Flutter tool already picks up existing DART_DEFINES from the iOS/MacOS Scheme when present.

I would like to fix this problem.

• [ ] I will try and fix this problem on docs.flutter.dev.

[sfshaza2]

Excellent bug report. Thx!

[jmagman]

This means the DART_DEFINES would have to be kept in sync with the Xcode configurations and schemes, which already encodes which flavor is being used. And it also conflicts with the existing only-half-implemented FLAVORS environment variable. https://github.com/flutter/flutter/blob/9441f9d48fce1d0b425628731dd6ecab8c8b0826/packages/flutter_tools/bin/xcode_backend.dart#L489 https://github.com/flutter/flutter/blob/9441f9d48fce1d0b425628731dd6ecab8c8b0826/packages/flutter_tools/lib/src/build_system/targets/ios.dart#L554

It would be better to push the flavor BuildInfo logic down into the flutter assemble iOS target logic, since it has all the context it needs from the Xcode build settings to parse the right flavor. I filed https://github.com/flutter/flutter/issues/155951. cc @andrewkolos

[sfshaza2]

Thanks so much, @navaronbracke, for surfacing a bug in the s/w that we didn't know about! I'm closing this issue as its superseded by the s/w bug. (Most importantly, I'm closing this docs bug because @jmagman pointed out that your solution could cause real problems for some developers, depending on their configuration.)

[navaronbracke]

I do agree that https://github.com/flutter/flutter/issues/155951 is a better solution to the underlying problem. Thanks for following up!