Add documentation for supporting flavors

[jmagman]

https://flutter.dev/docs/deployment/flavors currently links to some community articles, but it would be better if there were official documentation.

For example, https://github.com/flutter/flutter/issues/56507 is due to confusion about flavors and build configurations in Xcode. However there's no place to update and emphasize the correct fix for this issue, or even any documentation to link to. There have been some attempts to make flavors easier to use in iOS and those community articles can get out of date. There's a lot of bad advice on Stack Overflow that get people in a corrupted state.

[jmagman]

Also include instructions for different signing details per flavor, see https://github.com/flutter/flutter/issues/46879.

[sfshaza2]

We'd love better docs! Unfortunately it's not a high priority for Q2.

[bradyt]

@jmagman that example in the flutter integration tests is the best I've found, after a lot of time spent trying various documentation, blog articles, code examples, etc. I tried to copy that ios directory into my own project hoping to get it to work, but it didn't. Could you please add notes somewhere to reconstruct the example in the flavors integration test?

EDIT: My initial goal is just two distinct iOS bundle ids to encourage my usage of recent changes to a dogfood app, keeping a stable version installed on personal device, in parallel to the beta install.

EDIT EDIT: Copying over from the flutter/flutter flavors integration test has to work somehow, I'll just keep trying that.

[jmagman]

Could you please add notes somewhere to reconstruct the example in the flavors integration test?

That's what this issue is tracking: documenting that somewhere.

My initial goal is just two distinct iOS bundle ids to encourage my usage of recent changes to a dogfood app, keeping a stable version installed on personal device, in parallel to the beta install.

You can set different bundle identifiers per build configuration in Xcode:

That's not a Flutter thing, it's an Xcode thing. If you look up how to set different build settings by build configuration you'll have better luck.

I just haven't had time to write this doc... I once sent an email to someone asking a question about flavors and it was jokingly made into a documentation PR, but there may be some helpful nuggets in there https://github.com/flutter/website/pull/4203/files

[bradyt]

Here's what seemed to work for me:

1. Replace my own ios/ directory with the same from https://github.com/flutter/flutter/tree/master/dev/integration_tests/flavors.
2. Use tools to replace "free app", "free_app", "free" (ignoring case), in all file names and contents, with the terms I need in my app.
3. Similarly for "paid app", "paid_app", "paid".
4. Add missing items use_frameworks! and use_modular_headers! to Podfile, to both target blocks, like we see in result of flutter create.
5. flutter pub get && (cd ios && pod install).
6. flutter run -d ipod --flavor stable.

And everything seems to work now. I still have to smooth everything out, and hope that this all works with the rest of deployment process. This seemed like a smaller perceived effort than my previous attempts.

Apologies if this is not the correct repo and issue, but it seemed like a close fit since for me, this app example seems to be the closest fit to solve the issue. There's an issue to add documentation, and I saw what looked like a working example, so I imagined simply sketching notes on the origins of that example would solve.

Copying the ios directory is unfortunately not the same as, "here's how we created that example". The Podfile is modified with targets, there is a MethodChannel and AppDelegate, etc.

I think a drawback of the approach I'm taking, is there isn't a profiling configuration, and I may be using some stale flutter create parts, like something in the ios directory source code about "thin binary", etc.

[bradyt]

I wasn't satisfied with making small edits to the current state of the integration-test-as-example.

I used git filter-repo to extract that directory, if I limit history to match on ios directory, it gets the history down to fewer than 50 commits. Skimming through those, there's a few commits at the beginning by @mravn, then a few more starting at @jmagman's edits on May 11th, 2020.

I've managed to create a repo that starts from recent flutter create, and reproduces a close match to what @mravn created in August of 2017, and before changes on May 11, 2020. Each step is added to README, roughly describing what to do in Xcode, or what files to edit, and has a corresponding commit so the diff can be considered.

I'll next work on a few more steps for the relevant commits on or after May 11, 2020, and hopefully be able to share it as a repo. Potentially someone can use that repo to assist in writing up documentation for the website.

[bradyt]

I've created a repo at https://github.com/bradyt/flutter-flavor-reproduce-steps/, and pushed at tag 0.0.0, for the steps I describe above. Each step or steps of the README correspond with a commit in the history of said repo.

I'm having a little trouble with the next steps. I think I need to rename and duplicate the Target "Runner" to "Free App" and "Paid App", but I'm not sure how to end up with Info.plist being replaced with Info-Free.plist and Info-Paid.plist using the Xcode GUI.

[bradyt]

I think I got it, I right click in the navigation pane to add a file, select Property List, click on files to rename, and use "open as source code" to copy the text between them.

[jmagman]

I think I need to rename and duplicate the Target "Runner" to "Free App" and "Paid App", but I'm not sure how to end up with Info.plist being replaced with Info-Free.plist and Info-Paid.plist using the Xcode GUI.

There's probably not a good reason to do that in your case, you're just trying to have different bundle identifiers, right? You would just set that in the build settings PRODUCT_BUNDLE_IDENTIFIER as I pointed out in this screenshot:

The Info.plist will just reference that build setting as $(PRODUCT_BUNDLE_IDENTIFIER).

Anyway this issue is tracking making better docs. If I recall https://medium.com/@animeshjain/build-flavors-in-flutter-android-and-ios-with-different-firebase-projects-per-flavor-27c5c5dac10b was a pretty good start.

[bradyt]

I've had difficulty with every approach linked from the website. I'm guessing those blog articles are easier to follow if you already know what to do. Perhaps I was a little fixated to follow the integration test as an example, but it seemed to work and had at least a little bit of a git history to follow. I think I was able to reproduce the steps in your May 11 2020 commit and document that, at the repo I mentioned above, and a second tag 0.0.1.

The output is very close to what is found in the flavors integration test.

For me, the notes I've written are documentation that work from flutter create, alongside an example (with steps in git) as a sort of proof, that works with recent Flutter.

I'm sure they're not as polished as what you might prefer to post on Flutter website, but maybe their completeness will help someone create another writeup.

If I can clarify anything in my writeup, please don't hesitate to ask. It was a fast sketch.

[jmagman]

Thanks for your write-up, and sorry our docs aren't great for flavors, it's on the list of things to improve...