[v3/Linux] Use one application ID across packaging, runtime and services

[manuelschoene]

Summary

On Linux, the identity of a Wails v3 app is derived in several places that do not know about each other. Packaging names the .desktop file after BinaryName. wails3 generate .desktop uses a lowercased Name. The GTK/Wayland runtime uses Linux.ApplicationID (or a derived org.wails.<name>). Services like notifications use the raw Name. Nothing keeps these in sync, so an app can end up with a .desktop file, a Wayland app_id, and a config directory that all use different names.

I'd like to agree on one application ID that packaging, runtime, and services all use before I open some smaller Linux PRs that depend on it (see "Related work" below).

Current state (v3.1.0)

Build time

Where	Identity used
wails.yaml project.identifier / config.yml productIdentifier	Used for the macOS bundle ID and Android applicationId (internal/commands/manifest_pipeline.go), not on Linux. The template default is com.mycompany.myproduct.
Packaged .desktop file	<BinaryName>.desktop (internal/commands/manifest_pipeline.go, manifest_void.go)
wails3 generate .desktop	normaliseName(Name) = lowercase, spaces → - (internal/commands/dot_desktop.go, build-assets.go)
StartupWMClass in the .desktop template	{{.BinaryName}} (internal/commands/updatable_build_assets/linux/desktop.tmpl)

Runtime

Where	Identity used
GtkApplication ID / D-Bus name	Linux.ApplicationID, or org.wails.<sanitizeAppName(Name)> (pkg/application/application_linux_appid.go)
Wayland app_id (via g_set_prgname)	Linux.ProgramName, else Linux.ApplicationID if set, else the executable name
Notifications: D-Bus app_name and category storage	Raw Name; categories are saved to $XDG_CONFIG_HOME/<Name>/notification-categories.json (pkg/services/notifications/notifications_linux.go)

Also, the effective application ID is computed in newPlatformApp and then dropped. App.Config().Linux.ApplicationID only returns what the developer set explicitly, so services cannot get the derived fallback.

There might be other places where the application ID might be useful, and I may have missed them.

Why this is a problem

• Window and icon matching. Desktop shells match a Wayland window to its .desktop file using app_id. If a developer sets Linux.ApplicationID = "com.example.MyApp", the app_id becomes com.example.MyApp, but the packaged file is still <BinaryName>.desktop with StartupWMClass=<BinaryName>. The window then shows a generic icon and is not grouped with its launcher.
• Flatpak. Flatpak requires <app-id>.desktop, and the app_id must match it. Today that only works if the developer sets Linux.ApplicationID, renames the .desktop file themselves, and keeps the two in step by hand.
• Notifications. The freedesktop desktop-entry hint, which shells use for per-app notification settings and icons, cannot be set reliably because it's unclear which name is the "real" desktop ID.
• Config paths. Raw Name produces paths like ~/.config/My Cool App/. An empty Name writes directly into ~/.config/, and a Name containing / or .. creates nested directories or paths outside ~/.config/.
• Two defaults that disagree. Out of the box, the build side defaults to com.mycompany.myproduct and the runtime side defaults to org.wails.<name>.

Proposal

Make one application ID the source of truth on Linux, and derive the other names from it.

1. Expose the effective ID at runtime. Add a getter (e.g., App.ApplicationID()) or store the resolved value back in the config, so services can use the same ID that GTK uses, including the fallback. This is small and backward compatible.

2. Connect build time and runtime. Options to discuss:

   • A. Have the build inject project.identifier as the default for Linux.ApplicationID (e.g. via -ldflags -X or generated code). An explicit Linux.ApplicationID in code still wins.
   • B. Treat Linux.ApplicationID in code as the source and have packaging read it. This is harder, because the pipeline has no access to runtime Options.
   • C. Keep them separate, but have wails3 doctor or the build warn when they differ.

   I'd lean towards A: project.identifier already exists, is used on macOS and Android, and is visible to packaging.

3. Name Linux artifacts after the ID. Packaging produces <app-id>.desktop with StartupWMClass=<app-id>. Services use the ID for the desktop-entry hint and for per-app paths such as $XDG_CONFIG_HOME/<app-id>/.

Compatibility

Changing any of these names affects existing installs:

• Saved files under ~/.config/<Name>/ need a fallback that reads the legacy path.
• Renaming the .desktop file changes the desktop ID that GNOME and KDE use for per-app settings (notifications, autostart, favorites). That can be acceptable for packaged releases, but it should be called out in the release notes.
• Apps that never set an identifier would move from org.wails.<name> / com.mycompany.myproduct to whatever the unified default becomes, so the default needs care.

Phasing it in (step 1 first, then the opt-in behavior, then changing defaults) would keep each step reviewable.

Related work

I'm planning these Linux PRs. They'd use the ID from step 1:

• Set the desktop-entry hint on notifications.
• Move the notification category store away from $XDG_CONFIG_HOME/<Name>/, tighten permissions to 0700/0600, and fall back to the legacy path.
• Allow setting a custom icon for notifications.

Windows has a similar pattern (registry path HKCU\SOFTWARE\<Name>\…, the toast AUMID, and the %TEMP% icon file all use the raw Name). I've left it out of scope here, but the same ID could apply there later.

Questions for maintainers

1. Is one application ID across packaging and runtime the direction you want for v3?
2. Which option for step 2 do you prefer (A/B/C)?
3. Is it acceptable to rename the packaged .desktop file in a minor/nightly release, or does that need to wait for a specific milestone?
4. If the discussion ends with a successful proposal, how would you like to have it implemented? I am willing to do any related implementation work.