fix(flet pack): take the Linux identity from --bundle-id when given

The identity was the executable's name, which reads well in a dock but
disagrees with what `flet build` uses. After #2269 a built app's WM_CLASS,
StartupWMClass and Icon= are all its bundle_id, so an app published both ways
would have needed two different desktop entries -- and moving between the two
would silently stop matching, which is the trap the reporter of #5422 already
hit once.

`--bundle-id` now decides it, falling back to the executable name when it is
not given. That keeps the readable default for the many apps that never pass
one, converges with `flet build` for those that do, and finally makes
--bundle-id mean something outside macOS, where it only ever reached
--osx-bundle-identifier.

The id is chosen at pack time but applied at launch, so it is carried into
the bundle as a data file and read back by the runtime hook -- only when
--bundle-id was given, since the fallback needs nothing bundled. Exercised
all four resolution paths: bundled id, no bundled id, an empty bundled file,
and an executable with an extension.

Author: ndonkoHenri

CHANGELOG.md

@@ -35,7 +35,7 @@
 
 ### Bug fixes
 
-* Fix Linux apps packaged with `flet pack` appearing in the taskbar as "flet", grouped together with every other Flet app and unable to carry an icon. `flet pack` runs the shared prebuilt client binary, and the Linux desktop keys a window's identity on its X11 `WM_CLASS` or Wayland `app_id` — both of which GTK derives from the client's `argv[0]`, so every packed app inherited that binary's own name. The client is now launched under the app's own identity instead, taken from the new `FLET_APP_ID` environment variable that the PyInstaller runtime hook sets to the executable's name; the binary is unchanged, so this needs no client rebuild and works with clients already cached. Because the desktop resolves an app's display name and icon from an installed desktop entry matched through `StartupWMClass`, [Linux taskbar identity](https://flet.dev/docs/publish/using-pyinstaller#linux-taskbar-identity) documents how to install one — and `--icon`'s claim to work on Linux, which it never did, is corrected in both the docs and the CLI help ([#5422](https://github.com/flet-dev/flet/issues/5422)) by @ndonkoHenri.
+* Fix Linux apps packaged with `flet pack` appearing in the taskbar as "flet", grouped together with every other Flet app and unable to carry an icon. `flet pack` runs the shared prebuilt client binary, and the Linux desktop keys a window's identity on its X11 `WM_CLASS` or Wayland `app_id` — both of which GTK derives from the client's `argv[0]`, so every packed app inherited that binary's own name. The client is now launched under the app's own identity instead, taken from the new `FLET_APP_ID` environment variable that the PyInstaller runtime hook sets to `--bundle-id` when one is given and to the executable's name otherwise — so an app published both ways can carry one identity, and a single desktop entry matches whichever build a user installs; the binary is unchanged, so this needs no client rebuild and works with clients already cached. Because the desktop resolves an app's display name and icon from an installed desktop entry matched through `StartupWMClass`, [Linux taskbar identity](https://flet.dev/docs/publish/using-pyinstaller#linux-taskbar-identity) documents how to install one — and `--icon`'s claim to work on Linux, which it never did, is corrected in both the docs and the CLI help ([#5422](https://github.com/flet-dev/flet/issues/5422)) by @ndonkoHenri.
 * Fix Windows apps packaged with `flet pack` showing a second taskbar identity named "Flet description", whose right-click entry and pin launch a blank Flet client window instead of the app. Two defects stacked up: the PyInstaller runtime hook carrying the AppUserModelID fix from [#6403](https://github.com/flet-dev/flet/pull/6403) was never bundled into packed apps (its `rthooks.dat` manifest was missing from the `flet-cli` wheel, and PyInstaller skips a missing manifest silently), and a process-level AppUserModelID only fixes taskbar *grouping* anyway — the taskbar name, icon and pin target resolve through the shell's relaunch properties, which were never set, so they fell back to the cached `flet.exe`. The wheel now ships the manifest, and `flet_desktop` stamps `System.AppUserModel.ID`/`RelaunchCommand`/`RelaunchDisplayNameResource`/`RelaunchIconResource` on the client window right after launch (new `flet_desktop.win_taskbar` module, pure ctypes), driven by environment variables the runtime hook sets — and settable manually when packaging by other means, such as Nuitka. Apps started hidden (`AppView.FLET_APP_HIDDEN`) get their taskbar identity as well, and executable paths containing spaces or longer than 128 characters are supported ([#6767](https://github.com/flet-dev/flet/discussions/6767), [#6793](https://github.com/flet-dev/flet/pull/6793)) by @ndonkoHenri.
 * Fix `flet pack`-patched desktop clients and the vanilla client shadowing each other through the shared `~/.flet/client/` cache. The cache was keyed by flavor and version only, so a packaged app whose bundled client was patched with a custom icon and metadata could silently run whatever same-version client happened to be cached first — and vice versa. Bundled client archives are now content-fingerprinted and each distinct client gets its own cache directory. Client archives are built deterministically so rebuilds with unchanged content reuse the same cache entry, superseded entries unused for 30 days are garbage-collected (never touching a running app's client), and concurrent first-run extractions of the same archive no longer crash the losing process ([#6793](https://github.com/flet-dev/flet/pull/6793)) by @ndonkoHenri.
 * Fix `flet create --template extension` generating an example app whose `pyproject.toml` cannot be parsed on Windows. The `[tool.flet.dev_packages]` and `[tool.uv.sources]` entries that point back at the extension package interpolated the host's `os.sep` into a TOML basic string, so on Windows they rendered as `"..\.."` and `"..\..\"`: the first is an invalid escape sequence, and in the second the trailing `\"` escapes the closing quote and leaves the string unterminated — the "unbalanced quotes" error reporters hit before they could build or run the generated example. Both paths are now written with forward slashes, which need no escaping in TOML and which `pathlib` and `uv` accept on Windows just as they do elsewhere ([#5507](https://github.com/flet-dev/flet/issues/5507), [#6775](https://github.com/flet-dev/flet/pulls/6775)) by @ndonkoHenri.

sdk/python/packages/flet-cli/src/flet_cli/__pyinstaller/rthooks/pyi_rth_localhost_fletd.py

@@ -32,6 +32,18 @@
 # own name -- so the app groups and labels as itself, and can be matched by
 # a desktop entry carrying StartupWMClass.
 if sys.platform.startswith("linux") and "FLET_APP_ID" not in os.environ:
-    os.environ["FLET_APP_ID"] = os.path.splitext(
+    # --bundle-id when it was given, so the identity matches what `flet build`
+    # uses and what a desktop entry's StartupWMClass would name. Otherwise the
+    # executable's own name, which reads better bare than a reverse-DNS id and
+    # follows the binary if it is renamed.
+    app_id = ""
+    meipass = getattr(sys, "_MEIPASS", None)
+    if meipass:
+        try:
+            with open(os.path.join(meipass, "flet_app_id"), encoding="utf-8") as f:
+                app_id = f.read().strip()
+        except OSError:
+            pass
+    os.environ["FLET_APP_ID"] = app_id or os.path.splitext(
         os.path.basename(os.path.abspath(sys.executable))
     )[0]

sdk/python/packages/flet-cli/src/flet_cli/commands/pack.py

@@ -5,6 +5,7 @@
 import shutil
 import sys
 import tarfile
+import tempfile
 import zipfile
 from pathlib import Path
 
@@ -128,7 +129,10 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None:
         parser.add_argument(
             "--bundle-id",
             dest="bundle_id",
-            help="Bundle identifier used for macOS app packaging",
+            help="Bundle identifier for the app. Used for macOS app "
+            "packaging, and on Linux as the app's taskbar identity — match it "
+            "with the `StartupWMClass` key of your desktop entry. Defaults on "
+            "Linux to the executable's name.",
         )
         parser.add_argument(
             "--debug-console",
@@ -293,6 +297,18 @@ def handle(self, options: argparse.Namespace) -> None:
                 for add_data_arr in options.add_data:
                     for add_data_item in add_data_arr:
                         pyi_args.extend(["--add-data", add_data_item])
+
+            # The Linux taskbar identity is chosen here but applied at launch,
+            # so carry it into the bundle for the runtime hook to read. Only
+            # when asked for: without it the hook falls back to the
+            # executable's name, which needs nothing bundled.
+            if is_linux() and options.bundle_id:
+                identity_dir = Path(tempfile.mkdtemp())
+                identity_file = identity_dir.joinpath("flet_app_id")
+                identity_file.write_text(options.bundle_id, encoding="utf-8")
+                pyi_args.extend(
+                    ["--add-data", f"{identity_file}{os.pathsep}."]
+                )
             if options.add_binary:
                 for add_binary_arr in options.add_binary:
                     for add_binary_item in add_binary_arr:

website/docs/publish/using-pyinstaller.md

@@ -110,8 +110,13 @@ from an installed [desktop entry](#linux-taskbar-identity) instead, so passing
 `flet pack` launches the shared, prebuilt Flet client, so without help every
 packed app reaches the taskbar under that binary's name — grouped together and
 labelled `flet`. To avoid that, the app is relaunched under its own identity
-(see [`FLET_APP_ID`](../reference/environment-variables.md#flet_app_id)),
-which defaults to the executable's name.
+(see [`FLET_APP_ID`](../reference/environment-variables.md#flet_app_id)):
+[`--bundle-id`](../cli/flet-pack.md#--bundle-id) when you pass one, and
+otherwise the executable's name.
+
+Pass `--bundle-id` if you also publish the app with
+[`flet build linux`](linux.md), so both give the window the same identity and
+one desktop entry matches either.
 
 That gives the app its own taskbar group and label. To also give it a **name of
 your choosing and an icon**, install a desktop entry — the desktop takes both
@@ -128,7 +133,8 @@ Categories=Utility;
 StartupWMClass=my-app
 ```
 
-`StartupWMClass` must match the executable's name, and `Icon=` names a PNG
+`StartupWMClass` must match the app's identity — the `--bundle-id` you passed,
+or the executable's name if you did not — and `Icon=` names a PNG
 installed into the icon theme, for example
 `~/.local/share/icons/hicolor/256x256/apps/my-app.png`. Refresh the caches
 afterwards:
@@ -138,7 +144,7 @@ update-desktop-database ~/.local/share/applications
 gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
 ```
 
-:::note[Or let `flet build` package it]
+:::tip[Or let `flet build` package it]
 [`flet build linux`](linux.md) compiles a runner per app, so the identity is
 built in rather than applied at launch. Reach for it if you would rather have
 packaging handled than assemble it yourself.

website/docs/reference/environment-variables.md

@@ -76,7 +76,8 @@ and icon from it — see
 [Linux taskbar identity](../publish/using-pyinstaller.md#linux-taskbar-identity).
 
 Linux desktop apps only; set automatically by [`flet pack`](../cli/flet-pack.md)
-to the executable's name.
+to [`--bundle-id`](../cli/flet-pack.md#--bundle-id) when given, and otherwise to
+the executable's name.
 
 ### `FLET_APP_RELAUNCH_COMMAND`