Skip to content

docs: clarify xcconfig file usage and simplify notes in iOS flavors guide #13748

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lamek merged 4 commits into from
Aug 20, 2026
+42 −44
Merged

docs: clarify xcconfig file usage and simplify notes in iOS flavors guide #13748

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1689482
Fix for ticket 542694934 (GitHub issue #12225)
lamek Aug 4, 2026
0126fa1
Combine xcconfig and flavor naming notes into single note block
lamek Aug 18, 2026
9e2265b
Inline scheme lowercase naming and xcconfig details in iOS flavors guide
lamek Aug 18, 2026
9bbb8eb
docs: replace 'see' and 'check out' with sensory-neutral cross-refere…
lamek Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 42 additions & 44 deletions sites/docs/src/content/deployment/flavors-ios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,14 +64,14 @@ For a seamless workflow, we've started with a
new Flutter project called `flavors_example`, but you can
always start with an existing project.

1. Create a new Flutter project called `flavors_example`.
1. Create a new Flutter project called `flavors_example`:

```console title="console"
$ flutter create flavors_example
```

1. Open the default Xcode workspace for the iOS version of
the `flavors_example` project.
the `flavors_example` project:

```console title="console"
$ cd flavors_example && open ios/Runner.xcworkspace
Expand Down Expand Up @@ -125,7 +125,9 @@ always start with an existing project.
* Open the **Info tab** if it isn’t open.

* Go to the **Configurations** section and add new
`Debug` configurations.
`Debug` configurations. Always use lowercase for the
appended flavor name (such as `staging` or `production`)
so the Flutter CLI recognizes it:

* Click **+**, select
**Duplicate "Debug" configuration**, and name the
Expand All @@ -143,19 +145,12 @@ always start with an existing project.

![Scheme configurations for Flutter flavors](/assets/images/docs/flavors/flavors-ios-scheme-configurations.png){:width="100%"}

:::note
The scheme name (example: `staging`) that is appended to
a configuration name must be lowercase if you want to
use it with the Flutter CLI command.
:::

:::note
Your configurations should be based on your
`Debug.xcconfig`, `Profile.xcconfig`,
and `Release.xcconfig` files, not the
`Pods-Runner.xcconfig` file. You can check this by
expanding the configuration names in Xcode.
:::
Your configurations should be based on `Debug.xcconfig`
and `Release.xcconfig` (not `Pods-Runner.xcconfig`).
By default, both Profile and Release configurations
use `Release.xcconfig`.
You can check this by expanding the configuration
names in Xcode.

1. Assign the configurations to the schemes in Xcode:

Expand All @@ -178,14 +173,14 @@ always start with an existing project.
* Repeat the previous steps for the `production` scheme.

1. If you are working with a pre-existing Flutter project
that has at least one Podfile, update it. For more
information, see [Update Podfiles][].
that has at least one Podfile, update it.
For details, refer to [Update Podfiles][].

1. To make sure that you've set up everything correctly,
run your app on the new schemes in Xcode. You won't see
any differences because the configuration settings
haven't changed, but you do want to make sure that the
app can run.
run your app on the new schemes in Xcode. The app won't
have any visual differences yet because the configuration
settings haven't changed, but you should verify that
it runs without errors.

* Select the `staging` scheme
(**Product > Schemes > staging**).
Expand All @@ -201,8 +196,8 @@ always start with an existing project.
* Repeat the previous steps for the `production` scheme.

1. If everything runs, you're ready to customize your
configurations. For more information, see
[Customize configurations][].
configurations.
For details, refer to [Customize configurations][].

[Update Podfiles]: #update-podfiles
[Customize configurations]: #customize-configurations
Expand Down Expand Up @@ -241,14 +236,16 @@ Flutter CLI using the following steps:

### Access the current flavor

1. **Import the services library:**
To access the `appFlavor` constant, add the following import to your Dart file:
1. **Import the services library.**
To access the `appFlavor` constant,
add the following import to your Dart file:
```dart
import 'package:flutter/services.dart';
```

1. **Check the flavor value:**
Use the `appFlavor` constant in your application logic (often in `main()`) to handle flavor-specific configurations:
1. **Check the flavor value.**
Use the `appFlavor` constant in your application logic
(often in `main()`) to handle flavor-specific configurations:

```dart
void main() {
Expand Down Expand Up @@ -344,8 +341,8 @@ names in Xcode for two schemes called `staging` and

1. Launch the app for each scheme (`staging`, `production`)
and check to make sure that the app display name has
changed for each. To launch a scheme, see the steps in
[Launch an Xcode scheme][].
changed for each. To learn how to launch a scheme,
refer to [Launch an Xcode scheme][].

[Launch an Xcode scheme]: #launch-an-xcode-scheme

Expand Down Expand Up @@ -420,8 +417,8 @@ an iOS project called `flavors_example`.

1. Launch the app for each scheme (`staging`, `production`)
and check to make sure that the app icon has
changed for each. To launch a scheme, see the steps in
[Launch an Xcode scheme][].
changed for each. To learn how to launch a scheme,
refer to [Launch an Xcode scheme][].

[Launch an Xcode scheme]: #launch-an-xcode-scheme
[App Icon Generator]: https://www.appicon.co/
Expand Down Expand Up @@ -452,7 +449,7 @@ and `production` in an iOS project called `flavors_example`.
1. Navigate to the **Packaging** section.

1. Expand the **Product Bundle Identifier** setting to
see the different build configurations.
view the different build configurations.

1. For each scheme's build configuration, set the
desired bundle identifier. For example:
Expand All @@ -478,8 +475,8 @@ in your app, you can configure them to only be bundled into
your app when launching that flavor. This prevents your
app bundle size from being bloated by unused assets. To
bundle assets for each flavor, add the `flavors` subfield
to the `assets` field in your project's pubspec. To learn
more, see the [`assets` field][] in
to the `assets` field in your project's pubspec.
For details, refer to the [`assets` field][] in
[Flutter pubspec options][].

[`assets` field]: /tools/pubspec#assets
Expand All @@ -499,7 +496,7 @@ You can also use these steps to update a macOS
project by replacing any reference to `iOS` with `macOS`.

1. In your IDE, open the `ios/Podfile` file.
1. Make the following updates and save your changes.
1. Make the following updates and save your changes:

```ruby title="flavors_example/ios/Podfile"
project 'Runner', {
Expand All @@ -522,9 +519,10 @@ You can use [build settings][] to govern your iOS build
process from compilation and linking to debugging and
distribution. One way that you can use build settings
with Flutter flavors is to assign those build settings
to Xcode build configurations. For example, you might want
to assign different API URLs to `Debug-staging` and
`Debug-production`. For example:
to Xcode build configurations.
For example, you might want to assign different API URLs
to `Debug-staging` and `Debug-production`.
The following configurations show example build settings:

```plaintext title="debug-staging-settings.xcconfig"
# Debug-staging build settings
Expand All @@ -536,8 +534,8 @@ API_BASE_URL = staging.flavors.com/api
API_BASE_URL = flavors.com/api
```

If you would like to add additional build settings for
a specific build configuration, see Apple's
To learn how to add additional build settings for a
specific build configuration, consult Apple's
[Adding a build configuration file to your project][].

[build settings]: {{site.apple-dev}}/documentation/xcode/build-settings-reference/
Expand All @@ -547,15 +545,15 @@ a specific build configuration, see Apple's

This document contains a few common Xcode scheme
configurations, but there are many more that you can apply.
To learn about them, see
To learn about them, consult
[Customizing the build schemes for a project][].

[Customizing the build schemes for a project]: {{site.apple-dev}}/documentation/xcode/customizing-the-build-schemes-for-a-project

## More information

For more information on creating and using flavors, check
out the following resources:
To learn about creating and using flavors, consult
the following resources:

* [How to set up Flutter & Firebase with Multiple Flavors
using the FlutterFire CLI][flutterfire-cli]
Expand Down
Loading