diff --git a/sites/docs/src/content/deployment/flavors-ios.md b/sites/docs/src/content/deployment/flavors-ios.md index f12dc08fb71..d6ed962e0c3 100644 --- a/sites/docs/src/content/deployment/flavors-ios.md +++ b/sites/docs/src/content/deployment/flavors-ios.md @@ -557,10 +557,14 @@ To learn about them, see For more information on creating and using flavors, check out the following resources: +* [Set up Flutter flavors for Android][] +* [Set up Flutter flavors for Windows and Linux][] * [How to set up Flutter & Firebase with Multiple Flavors using the FlutterFire CLI][flutterfire-cli] * [Build flavors in Flutter (Android and iOS) with different Firebase projects per flavor Flutter Ready to Go][flavors-firebase] +[Set up Flutter flavors for Android]: /deployment/flavors +[Set up Flutter flavors for Windows and Linux]: /deployment/flavors-windows-linux [flutterfire-cli]: https://codewithandrea.com/articles/flutter-firebase-multiple-flavors-flutterfire-cli/ [flavors-firebase]: https://medium.com/@animeshjain/build-flavors-in-flutter-android-and-ios-with-different-firebase-projects-per-flavor-27c5c5dac10b diff --git a/sites/docs/src/content/deployment/flavors-windows-linux.md b/sites/docs/src/content/deployment/flavors-windows-linux.md new file mode 100644 index 00000000000..0232a99653b --- /dev/null +++ b/sites/docs/src/content/deployment/flavors-windows-linux.md @@ -0,0 +1,429 @@ +--- +title: Set up Flutter flavors for Windows and Linux +shortTitle: Flavors (Windows and Linux) +description: > + How to create Flutter flavors for Windows and Linux desktop apps. +--- + +This guide shows you how to create Flutter flavors for +Windows and Linux desktop apps. + +:::note +To create flavors for Android apps, +see [Set up Flutter flavors for Android][]. +To create flavors for iOS and macOS apps, +see [Set up Flutter flavors for iOS and macOS][]. +::: + +## Overview {: #overview } + +A Flutter flavor represents a collection of settings that define +how a specific version of your app builds and runs. +For example, a flavor can determine which window title, binary name, +application ID, API endpoint, asset set, and logging configuration +applies to a build. + +On Windows and Linux, Flutter uses [CMake][] to configure and build +the native desktop runner. +When you run `flutter run` or `flutter build` with the `--flavor` flag, +Flutter provides the flavor name to CMake as the `FLUTTER_APP_FLAVOR` +variable and isolates the build outputs in a flavor-specific directory. + +The following table illustrates the build directories that Flutter creates +when a project defines two flavors (`staging`, `production`) +and two build modes (`debug`, `release`): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformFlavorBuild modeOutput directory
Windowsstagingreleasebuild/windows/<arch>/staging/runner/Release/
productionreleasebuild/windows/<arch>/production/runner/Release/
Linuxstagingreleasebuild/linux/<arch>/staging/release/bundle/
productionreleasebuild/linux/<arch>/production/release/bundle/
+ +[CMake]: https://cmake.org/ +[Set up Flutter flavors for Android]: /deployment/flavors +[Set up Flutter flavors for iOS and macOS]: /deployment/flavors-ios + +## Configure CMake for flavors {: #configure-cmake } + +Complete the following steps to configure two flavors called +`staging` and `production` for a new or existing Flutter project. + +1. Create a new Flutter project called `flavors_example`: + + ```console title="console" + $ flutter create flavors_example + $ cd flavors_example + ``` + +1. Configure the CMake build files for your target platform: + + + + +Open `windows/CMakeLists.txt` and locate the `set(BINARY_NAME ...)` line. +Update the configuration to append the flavor name to the binary name +when a flavor is specified: + +```cmake title="windows/CMakeLists.txt" +# The name of the executable created for the application. +set(BINARY_NAME "flavors_example") +if(DEFINED FLUTTER_APP_FLAVOR AND NOT FLUTTER_APP_FLAVOR STREQUAL "") + set(BINARY_NAME "${BINARY_NAME}_${FLUTTER_APP_FLAVOR}") +endif() +``` + + + +Open `linux/CMakeLists.txt` and locate the `set(BINARY_NAME ...)` and +`set(APPLICATION_ID ...)` lines. +Update the configuration to append the flavor name to the binary name +and application ID when a flavor is specified: + +```cmake title="linux/CMakeLists.txt" +# The name of the executable created for the application. +set(BINARY_NAME "flavors_example") +# The unique GTK application identifier for this application. +set(APPLICATION_ID "com.example.flavors_example") + +if(DEFINED FLUTTER_APP_FLAVOR AND NOT FLUTTER_APP_FLAVOR STREQUAL "") + set(BINARY_NAME "${BINARY_NAME}_${FLUTTER_APP_FLAVOR}") + set(APPLICATION_ID "${APPLICATION_ID}.${FLUTTER_APP_FLAVOR}") +endif() +``` + + + + +1. Verify that your flavors run correctly: + + + + +Run the `staging` flavor: + +```console title="console" +$ flutter run -d windows --flavor staging +``` + +Run the `production` flavor: + +```console title="console" +$ flutter run -d windows --flavor production +``` + + + +Run the `staging` flavor: + +```console title="console" +$ flutter run -d linux --flavor staging +``` + +Run the `production` flavor: + +```console title="console" +$ flutter run -d linux --flavor production +``` + + + +## Launch a flavor {: #launch-a-flavor } + +After you configure flavors for your Windows or Linux app, +launch or build a specific flavor using the `--flavor` flag +with the Flutter CLI. + +### Run a flavor in debug mode {: #run-a-flavor } + +To run a specific flavor during development, +pass the `--flavor` option to `flutter run`: + + + + +```console title="console" +$ flutter run -d windows --flavor +``` + + + +```console title="console" +$ flutter run -d linux --flavor +``` + +Replace `` with the name of your flavor +(for example, `staging` or `production`). + + + + +### Build a release binary {: #build-a-flavor } + +To build a release executable for a specific flavor, +pass the `--flavor` option to `flutter build`: + + + + +```console title="console" +$ flutter build windows --flavor +``` + +Flutter outputs the compiled executable to +`build/windows///runner/Release/`. + + + + +```console title="console" +$ flutter build linux --flavor +``` + +Flutter outputs the compiled bundle to +`build/linux///release/bundle/`. + + + + +## Use flavors in Flutter code {: #use-flavors-in-code } + +After you configure your flavors, +you can adjust app behavior—such as selecting API endpoints, +toggling features, or setting analytics keys—based on the active flavor. + +The Flutter framework provides the `appFlavor` constant in the `services` +library, which retrieves the flavor name passed to the `--flavor` flag +during `flutter run` or `flutter build`. + +1. **Import the services library:** + + Add the following import to your Dart file: + + ```dart + import 'package:flutter/services.dart'; + ``` + +1. **Read the flavor value:** + + Use the `appFlavor` constant in your application logic + (often in `main()`) to handle flavor-specific configuration: + + ```dart + void main() { + if (appFlavor == 'production') { + Config.apiUrl = 'https://api.example.com'; + } else if (appFlavor == 'staging') { + Config.apiUrl = 'https://staging.api.example.com'; + } + + runApp(const MyApp()); + } + ``` + + :::note + The value of `appFlavor` matches the string passed to the `--flavor` flag. + If you run or build without specifying a flavor, + `appFlavor` returns `null`. + ::: + +## Customize configurations {: #customize-configurations } + +After adding flavors, +you can customize native settings and assets for each configuration. + +### Create distinct window titles {: #create-distinct-window-titles } + +To help distinguish between different flavors at runtime, +you can customize the native window title for each flavor. + + + + +1. Open `windows/runner/CMakeLists.txt` and pass `FLUTTER_APP_FLAVOR` + as a preprocessor definition: + +```cmake title="windows/runner/CMakeLists.txt" +if(DEFINED FLUTTER_APP_FLAVOR AND NOT FLUTTER_APP_FLAVOR STREQUAL "") + target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_APP_FLAVOR=\"${FLUTTER_APP_FLAVOR}\"") +endif() +``` + +1. Open `windows/runner/main.cpp` and update the window title + to include the flavor name when defined: + +```cpp title="windows/runner/main.cpp" +#if defined(FLUTTER_APP_FLAVOR) + std::wstring title = L"flavors_example (" + std::wstring(L"" FLUTTER_APP_FLAVOR) + L")"; + if (!window.Create(title.c_str(), origin, size)) { + return EXIT_FAILURE; + } + #else + if (!window.Create(L"flavors_example", origin, size)) { + return EXIT_FAILURE; + } + #endif +``` + + + + +1. Open `linux/runner/CMakeLists.txt` and pass `FLUTTER_APP_FLAVOR` + as a preprocessor definition: + +```cmake title="linux/runner/CMakeLists.txt" +if(DEFINED FLUTTER_APP_FLAVOR AND NOT FLUTTER_APP_FLAVOR STREQUAL "") + target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_APP_FLAVOR=\"${FLUTTER_APP_FLAVOR}\"") +endif() +``` + +1. Open `linux/runner/my_application.cc` and update the window title + in the `my_application_activate` function: + +```c title="linux/runner/my_application.cc" +#if defined(FLUTTER_APP_FLAVOR) + const char* title = "flavors_example (" FLUTTER_APP_FLAVOR ")"; +#else + const char* title = "flavors_example"; +#endif + +if (use_header_bar) { + GtkHeaderBar* header_bar = GTK_HEADER_BAR(gtk_header_bar_new()); + gtk_widget_show(GTK_WIDGET(header_bar)); + gtk_header_bar_set_title(header_bar, title); + gtk_header_bar_set_show_close_button(header_bar, TRUE); + gtk_window_set_titlebar(window, GTK_WIDGET(header_bar)); +} else { + gtk_window_set_title(window, title); +} +``` + + + + +### Create distinct app icons {: #create-distinct-app-icons } + +You can provide unique icons for each flavor. + + + + +1. Prepare your icon files in `.ico` format + (for example, `app_icon_staging.ico` and `app_icon_production.ico`) + and place them in `windows/runner/resources/`. + +1. In `windows/CMakeLists.txt`, select the appropriate icon file + based on `FLUTTER_APP_FLAVOR`: + +```cmake title="windows/CMakeLists.txt" +if(FLUTTER_APP_FLAVOR STREQUAL "staging") + set(APP_ICON_NAME "app_icon_staging.ico") +elseif(FLUTTER_APP_FLAVOR STREQUAL "production") + set(APP_ICON_NAME "app_icon_production.ico") +else() + set(APP_ICON_NAME "app_icon.ico") +endif() +``` + +1. Configure `windows/runner/Runner.rc` or your CMake target + to use `APP_ICON_NAME` for the application icon resource. + + + + +1. Prepare PNG icons for each flavor + (for example, `app_icon_staging.png` and `app_icon_production.png`). + +1. Create corresponding `.desktop` files for each flavor + (for example, `flavors_example_staging.desktop` and + `flavors_example_production.desktop`) + that reference the respective icon and executable binary name. + +1. Update `linux/CMakeLists.txt` to install the correct `.desktop` file + and icon based on `FLUTTER_APP_FLAVOR`. + + + + +### Bundle assets by flavor {: #bundle-assets } + +If you have assets that only apply to a specific flavor, +configure Flutter to only bundle those assets when building that flavor. +This prevents unused assets from increasing your application bundle size. + +To bundle assets conditionally, +add the `flavors` list to an asset entry in `pubspec.yaml`: + +```yaml title="pubspec.yaml" +flutter: + assets: + - assets/common/ + - path: assets/staging/ + flavors: + - staging + - path: assets/production/ + flavors: + - production +``` + +To learn more, see the [`assets` field][] in [Flutter pubspec options][]. + +[`assets` field]: /tools/pubspec#assets +[Flutter pubspec options]: /tools/pubspec + +### Set a default flavor {: #set-default-flavor } + +To specify a flavor to use when running or building +without the `--flavor` flag, +add the `default-flavor` property to `pubspec.yaml`: + +```yaml title="pubspec.yaml" +flutter: + default-flavor: staging +``` + +To learn more, see the [`default-flavor` field][] in +[Flutter pubspec options][]. + +[`default-flavor` field]: /tools/pubspec#default-flavor-field + +## More information {: #more-information } + +For more information on flavors and desktop deployment, +consult the following resources: + +* [Set up Flutter flavors for Android][] +* [Set up Flutter flavors for iOS and macOS][] +* [Build and release a Windows desktop app][] +* [Build and release a Linux app to the Snap Store][] + +[Build and release a Windows desktop app]: /deployment/windows +[Build and release a Linux app to the Snap Store]: /deployment/linux diff --git a/sites/docs/src/content/deployment/flavors.md b/sites/docs/src/content/deployment/flavors.md index 7f67d66efca..dfaa9f3c1b6 100644 --- a/sites/docs/src/content/deployment/flavors.md +++ b/sites/docs/src/content/deployment/flavors.md @@ -399,8 +399,12 @@ When setting `abiFilters` in product flavors, pass For more information on creating and using flavors, check out the following resources: +* [Set up Flutter flavors for iOS and macOS][] +* [Set up Flutter flavors for Windows and Linux][] * [Build flavors in Flutter (Android and iOS) with Firebase][] * [How to Setup Flutter & Firebase with Multiple Flavors using the FlutterFire CLI][flutterfireCLI] +[Set up Flutter flavors for iOS and macOS]: /deployment/flavors-ios +[Set up Flutter flavors for Windows and Linux]: /deployment/flavors-windows-linux [Build flavors in Flutter (Android and iOS) with Firebase]: https://medium.com/@animeshjain/build-flavors-in-flutter-android-and-ios-with-different-firebase-projects-per-flavor-27c5c5dac10b [flutterfireCLI]: https://codewithandrea.com/articles/flutter-firebase-multiple-flavors-flutterfire-cli/ diff --git a/sites/docs/src/content/platform-integration/linux/setup.md b/sites/docs/src/content/platform-integration/linux/setup.md index ac462e89e9a..b67a084fe9f 100644 --- a/sites/docs/src/content/platform-integration/linux/setup.md +++ b/sites/docs/src/content/platform-integration/linux/setup.md @@ -127,6 +127,9 @@ or begin expanding integration with Linux.
  • Release a Linux app
    • +
  • + Set up app flavors +
  • Write Linux-specific code
    • diff --git a/sites/docs/src/content/platform-integration/windows/setup.md b/sites/docs/src/content/platform-integration/windows/setup.md index dfbfa284a9f..65c9195ffc6 100644 --- a/sites/docs/src/content/platform-integration/windows/setup.md +++ b/sites/docs/src/content/platform-integration/windows/setup.md @@ -147,6 +147,9 @@ or begin expanding integration with Windows.
  • Deploy to windows
    • +
  • + Set up app flavors +
  • Write Windows-specific code
    • diff --git a/sites/docs/src/content/tools/pubspec.md b/sites/docs/src/content/tools/pubspec.md index 6e0194889a6..83d06e6dc5d 100644 --- a/sites/docs/src/content/tools/pubspec.md +++ b/sites/docs/src/content/tools/pubspec.md @@ -243,6 +243,7 @@ flutter: [Set up flavors for iOS and macOS]: /deployment/flavors-ios [Set up flavors for Android]: /deployment/flavors +[Set up flavors for Windows and Linux]: /deployment/flavors-windows-linux [Assets and images]: /ui/assets/assets-and-images [asset images in package dependencies]: /ui/assets/assets-and-images#from-packages [resolution aware]: /ui/assets/assets-and-images#resolution-aware @@ -323,11 +324,13 @@ flutter run --flavor staging ``` To learn how to create Flutter flavors, -see [Set up Flutter flavors for Android][] and -[Set up Flutter flavors for iOS and macOS][]. +see [Set up Flutter flavors for Android][], +[Set up Flutter flavors for iOS and macOS][], and +[Set up Flutter flavors for Windows and Linux][]. [Set up Flutter flavors for Android]: /deployment/flavors [Set up Flutter flavors for iOS and macOS]: /deployment/flavors-ios +[Set up Flutter flavors for Windows and Linux]: /deployment/flavors-windows-linux ### deferred-components field diff --git a/sites/docs/src/data/sidenav/default.yml b/sites/docs/src/data/sidenav/default.yml index c1b2fe4ce36..b586fc002ce 100644 --- a/sites/docs/src/data/sidenav/default.yml +++ b/sites/docs/src/data/sidenav/default.yml @@ -577,6 +577,8 @@ permalink: /deployment/flavors - title: Create app flavors for iOS and macOS permalink: /deployment/flavors-ios + - title: Create app flavors for Windows and Linux + permalink: /deployment/flavors-windows-linux - title: Build and release an Android app permalink: /deployment/android - title: Build and release an iOS app