Skip to content

Add --flavor support for Linux desktop builds#187029

Merged
mattkae merged 16 commits into
flutter:masterfrom
AngeloAvv:add-linux-flavors-support
Jul 7, 2026
Merged

Add --flavor support for Linux desktop builds#187029
mattkae merged 16 commits into
flutter:masterfrom
AngeloAvv:add-linux-flavors-support

Conversation

@AngeloAvv

Copy link
Copy Markdown
Contributor

Flutter desktop on Linux currently has no equivalent of the --flavor plumbing that already exists for Android, iOS, and macOS: flutter build linux --flavor X is rejected at the command-parser level, flutter run -d linux --flavor X emits a "flavor only supported on Android, iOS, macOS" warning, and there is no convention for producing per-flavor binaries or build directories. This PR wires the existing flavor infrastructure end-to-end on Linux so that multiple flavors can coexist in the same project without colliding on disk or in the runner.

What changes

  • flutter build linux accepts --flavor via the shared usesFlavorOption() helper.
  • LinuxDevice.supportsFlavors returns true, so flutter run -d linux --flavor X no longer warns and now drives the flavored build pipeline.
  • Build directory is namespaced per flavor: build/linux/<arch>/<flavor>/<mode>/ (parity with Android/iOS/macOS). Projects that don't pass --flavor keep the legacy build/linux/<arch>/<mode>/ layout — no migration required.
  • CMake configure receives -DFLUTTER_APP_FLAVOR=<flavor> so the generated project can react to the flavor at configure time.
  • Generated CMake template suffixes BINARY_NAME with -<flavor> and APPLICATION_ID with .<flavor> when FLUTTER_APP_FLAVOR is defined, matching the Android applicationIdSuffix convention. The branch is guarded by if(DEFINED FLUTTER_APP_FLAVOR AND NOT FLUTTER_APP_FLAVOR STREQUAL ""), so existing projects regenerated from this template behave identically when no flavor is passed.
  • Runner template (linux.tmpl/runner/CMakeLists.txt + my_application.cc.tmpl) exposes FLUTTER_APP_FLAVOR as a compile-time preprocessor define (same mechanism already used for APPLICATION_ID) and uses it to suffix the GTK window title, giving projects a one-line entry point for flavor-aware native behavior without any additional Flutter tool surface area.
  • Dart-side continues to use the existing appFlavor getter from package:flutter/services.dart, which reads FLUTTER_APP_FLAVOR from the dart-defines that toEnvironmentConfig() already produces. No framework changes required.

Design choices

  • APPLICATION_ID suffix mirrors Android (it.example.appit.example.app.free) so packaging tooling and .desktop files have a stable convention to key off.
  • Per-flavor build directory matches the layout the other platforms already use, so users can ls build/linux/x64/ and see each flavor side-by-side.
  • Flavor-specific assets, icons, .desktop files, and snap/deb packaging remain the project's responsibility — this PR intentionally keeps the tool agnostic and only standardizes the plumbing.

Tests

  • New test/general.shard/linux/build_linux_flavor_test.dart covers:
    • flutter build linux --flavor apple invokes CMake with -DFLUTTER_APP_FLAVOR=apple and a flavored working directory, and the success log references build/linux/x64/apple/release/bundle.
    • getCmakeExecutableName returns the base binary name without a flavor, and name-flavor when a flavor is provided (empty string treated as no flavor).
  • Existing test/commands.shard/hermetic/build_linux_test.dart (25 cases) continues to pass with no changes, confirming the legacy no-flavor path is unaffected.

Manual verification

Generated an example project, then ran the full matrix:

flutter build linux --flavor apple   # → build/linux/x64/apple/release/bundle/example-apple
flutter build linux --flavor banana  # → build/linux/x64/banana/release/bundle/example-banana
flutter build linux                  # → build/linux/x64/release/bundle/example (unchanged)
flutter run -d linux --flavor apple  # launches, no "unsupported flavor" warning

All three builds coexist in build/linux/x64/ without overwriting each other, and the Dart UI reads appFlavor correctly at runtime in each binary.

Backward compatibility

  • Projects that never pass --flavor see no change: same build directory, same binary name, same APPLICATION_ID, same generated CMake.
  • Existing projects do not need to regenerate linux/CMakeLists.txt to keep working; they only need to regenerate (or hand-patch the if(DEFINED FLUTTER_APP_FLAVOR) branch) to opt into flavor support.

Fixes #162373

Pre-launch Checklist

@AngeloAvv
AngeloAvv requested a review from a team as a code owner May 24, 2026 09:23
@github-actions github-actions Bot added tool Affects the "flutter" command-line tool. See also t: labels. platform-linux Building on or for Linux specifically a: desktop Running on desktop team-linux Owned by the Linux platform team labels May 24, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Code Review

This pull request adds support for the --flavor option to Flutter Linux builds, modifying build directory logic, binary naming, and application IDs. The flavor is passed to CMake and the C++ runner to enable flavor-aware behavior, such as dynamic window titles. Review feedback suggests mitigating a potential format string vulnerability in the C++ template and implementing a check for missing binary names to prevent invalid file path construction.

Comment thread packages/flutter_tools/templates/app/linux.tmpl/runner/my_application.cc.tmpl Outdated
Comment thread packages/flutter_tools/lib/src/linux/build_linux.dart Outdated
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
robert-ancell
robert-ancell previously approved these changes May 24, 2026

@robert-ancell robert-ancell left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nice work!

In this review I was particularly thinking about the application ID naming and any side effects that might have, the means of passing this to the application via CMake and consistency with other platforms. The choices all seem appropriate to me. I can see a very similar solution working for Windows.

I would like a second review from someone who has used the flavor system in Flutter (I have not) - @loic-sharma can you suggest someone for that?

@robert-ancell
robert-ancell requested a review from mattkae May 24, 2026 22:18
@kjxbyz

kjxbyz commented May 25, 2026

Copy link
Copy Markdown

I published an application on Flathub; the original application ID was com.kjxbyz.PicGuard.Pro, but the reviewers suggested com.kjxbyz.PicGuardPro instead.

mattkae
mattkae previously approved these changes May 27, 2026

@mattkae mattkae left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good to me!

@robert-ancell
robert-ancell enabled auto-merge May 29, 2026 04:04
@bkonyi bkonyi added the CICD Run CI/CD label Jun 1, 2026
AngeloAvv and others added 3 commits June 1, 2026 21:55
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@loic-sharma

Copy link
Copy Markdown
Member

FYI, I left feedback on the Windows PR, #187034, that should also be addressed on this PR as well :)

@github-actions github-actions Bot removed CICD Run CI/CD labels Jun 6, 2026
auto-merge was automatically disabled June 6, 2026 15:57

Head branch was pushed to by a user without write access

@AngeloAvv
AngeloAvv dismissed stale reviews from robert-ancell and mattkae via 949aac4 June 6, 2026 15:57
robert-ancell
robert-ancell previously approved these changes Jun 17, 2026

@robert-ancell robert-ancell left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'm happy with this - @loic-sharma was there anything left to match the Windows PR?

@flutter-dashboard flutter-dashboard Bot removed the CICD Run CI/CD label Jul 1, 2026

@loic-sharma loic-sharma left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Re-LGTM!

@loic-sharma loic-sharma added the CICD Run CI/CD label Jul 1, 2026
@kjxbyz

kjxbyz commented Jul 7, 2026

Copy link
Copy Markdown

The branch cutoff date of 3.47 is July 7th, so this feature will not appear in 3.47?

@AngeloAvv

Copy link
Copy Markdown
Contributor Author

@kjxbyz maybe they want to keep them separate on purpose. Who knows

@mattkae
mattkae added this pull request to the merge queue Jul 7, 2026
Merged via the queue into flutter:master with commit 3e48f7a Jul 7, 2026
174 checks passed
@kjxbyz

kjxbyz commented Jul 7, 2026

Copy link
Copy Markdown

@AngeloAvv It sounds quite frustrating.

@loic-sharma

Copy link
Copy Markdown
Member

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a: desktop Running on desktop CICD Run CI/CD platform-linux Building on or for Linux specifically team-linux Owned by the Linux platform team tool Affects the "flutter" command-line tool. See also t: labels.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support flavors for Linux

6 participants