Desktop files, icons and D-Bus activation

desktop integration for app developers for users for snapd developers

When a snap is linked snapd copies its D-Bus activation files and desktop files and icons into host directories that the desktop reads. Desktop files are renamed with the snap name and filtered through an allow-list and their Exec and Icon lines are rewritten. A desktop plug with desktop-file-ids keeps chosen names and an app can ask to be started at login.

On the map: desktop district

▶ Watch this deck — 8 scenes, ~6 min

02 The launcher appears for users in place of the general version

YOUR LAUNCHER $ snap install photo-editorapplicationsPhoto Editor Photo Editorpinned or copied $ snap refresh photo-editorboth still start the new version $ snap remove photo-editorgone from the menu your copy stays,with nothing to start an app that starts when you log in is started by the snap command, because the app asked for it
Three commands and an applications menu: after snap install photo-editor a Photo Editor launcher appears, and you can pin or copy it; after snap refresh both still start the new version; after snap remove the launcher is gone from the menu; an app that starts at login is started by the snap command at the app's request

A snap's launcher is installed with the snap and removed with it. A launcher you pinned or copied keeps working after a refresh.

You install photo-editor, and a moment later it's in your applications menu. You didn't put it there, so what happens to it when the snap changes? The launcher arrives with the snap; you can pin it to your dock or copy it to your desktop. After a refresh, both still start the new version, because the launcher doesn't point at one particular revision. Removing the snap takes the launcher out of the menu. A copy you made yourself stays, with nothing left to start. And if an app starts when you log in, that's because the app asked for it, and the snap command starts it when your session begins.

03 What survives the rewrite for app developers for snapd developers

BEFORE AND AFTER in the snap[Desktop Entry]Name=Photo EditorExec=photo-editor %FIcon=${SNAP}/meta/gui/icon.pngTryExec=photo-editorDBusActivatable=true on the host[Desktop Entry]Name=Photo Editor not on the allow-list: dropped Exec=/snap/bin/photo-editor %F Icon=/snap/photo-editor/current/meta/gui/icon.png${SNAP} becomes the path through current, not revision 42 X-SnapInstanceName=photo-editorX-SnapAppName=photo-editorand X-SnapCommonID when the app has a common-idrewritten for every snap each time snapd starts, so newer rules apply
The desktop file in the snap beside the one installed on the host: TryExec and DBusActivatable are dropped because they are not on the allow-list, Exec points at /snap/bin/photo-editor, the ${SNAP} icon path goes through current, and X-SnapInstanceName and X-SnapAppName are added

Only allow-listed keys are kept. Exec= becomes the app's launcher path, ${SNAP} becomes the path through current, and snapd adds X-SnapInstanceName, X-SnapAppName and, if set, X-SnapCommonID. The path shown is the one on Ubuntu.

Put the file you shipped next to the installed one and you'll spot the differences at once. Snapd keeps a line only if it's blank, a comment, a known group header or one of about twenty known keys. Everything else is quietly dropped, TryExec and DBusActivatable included. Exec now points at your app's launcher under /snap/bin, arguments kept. $SNAP becomes the path through current, not the revision, so a copied launcher keeps its icon after a refresh. Then snapd adds the instance name, the app name and any common-id. It redoes all this each time snapd starts, so newer rules apply.

04 Exec must name your own app for app developers for snapd developers

ONE Exec LINE Exec=<command> [arguments] is the command photo-editor or photo-editor.<app>?yesExec=/snap/bin/photo-editor.<app> … if that app is a serviceExec=/usr/bin/falsephoto-editor.indexer (invented) nodoes the installed file name equal an app name?yesthat app's launcher, no arguments installed names carry the photo-editor_ prefix,so only an unprefixed desktop-file-ids file matches line dropped and logged: the entry has no Exec
A decision flow for one Exec line: if the command is photo-editor or photo-editor.app it becomes that app's launcher with the arguments; if that app is a service the line becomes Exec=/usr/bin/false; otherwise only an installed file name equal to an app name rescues it, which the snap prefix makes rare; else the line is dropped

Exec= must name <snap> or <snap>.<app>. A service becomes Exec=/usr/bin/false. Any other command is dropped, unless the installed file name, prefix included, equals an app name. The indexer service is invented.

Of everything in a desktop file, one line decides what actually runs when you click. So what does snapd do if that line names something that isn't yours? The command has to be photo-editor, or photo-editor dot one of its apps. Then it becomes that app's launcher, and your arguments stay. If the app is a service, the line becomes /usr/bin/false, because a menu shouldn't start a service. Anything else gets one fallback: an installed file name that equals an app name. Installed names carry the snap prefix, though, so in practice only an unprefixed file can match. Otherwise the line is dropped, with a log line.

05 Keeping your own file name for app developers for snapd developers

desktop-file-ids meta/gui/photo-editor.desktop→ photo-editor_photo-editor.desktopstill prefixed snap.yamlplugs:desktop:desktop-file-ids:- org.example.PhotoEditor meta/gui/org.example.PhotoEditor.desktop→ org.example.PhotoEditor.desktopinstalled as it is; an id with no file creates nothing needs a snap-declaration: the base declaration allows the plug only without this attribute parallel install refused: "desktop-file-ids" attribute must not be set name owned by another snap: cannot install … already exists for another snap org.example.PhotoEditor is invented for this deck
A desktop plug lists desktop-file-ids with org.example.PhotoEditor; meta/gui/photo-editor.desktop is still installed with the photo-editor_ prefix while meta/gui/org.example.PhotoEditor.desktop is installed as it is; the snap needs a snap-declaration, cannot be installed in parallel, and linking fails if another snap owns the name

A desktop plug with desktop-file-ids installs <id>.desktop without the snap prefix. It needs a snap-declaration, is refused for parallel installs and fails if another snap owns the name. A snapd bug: linking or removing snap foo also deletes another snap's unprefixed foo_*.desktop. The id shown is invented.

The prefix keeps snaps apart, but some desktops match a window or a bus name to a desktop file by its exact name. So you list the ids you need on the desktop plug, as desktop-file-ids. A file in meta/gui named after one is installed as it is; listing an id alone creates nothing. An unprefixed name could pass for another application, so the base declaration allows this plug only without the attribute, and the store has to grant it in a snap-declaration. Such a snap can't be installed in parallel. And if another snap owns the name, linking fails rather than overwrite it.

06 Icons and bus names for app developers for snapd developers

THE OTHER TWO iconsmeta/gui/icons/hicolor/256x256/apps/snap.photo-editor.icon.png/var/lib/snapd/desktop/icons/hicolor/256x256/apps/snap.photo-editor.icon.png only snap.photo-editor.* files, .png or .svg Icon=snap.photo-editor.iconin a desktop file: a theme name, not a path bus namesgenerated .service file[D-BUS Service]Name=org.example.PhotoEditorSystemdService=snap.photo-editor.indexer.serviceUser=rootX-Snap=photo-editorand Comment, Exec, AssumedAppArmorLabelsystem scope: /var/lib/snapd/dbus-1/system-servicesuser scope: /var/lib/snapd/dbus-1/services, no User= removal finds the file by its X-Snap= line a bus name another snap already activates on:the install fails the bus name and the indexer service are invented
Left: icons named snap.photo-editor.* under meta/gui/icons are mirrored into /var/lib/snapd/desktop/icons, and a desktop file can use Icon=snap.photo-editor.icon as a theme name. Right: a service with activates-on gets a D-Bus .service file naming its systemd unit and tagged X-Snap=photo-editor; a bus name another snap activates on fails the install

Icons named snap.<snap>.* under meta/gui/icons are mirrored to the host. A service with activates-on gets a D-Bus .service file naming its systemd unit. The bus name and the indexer app are invented.

Desktop files aren't all the desktop needs from photo-editor. Icons under meta/gui/icons are mirrored, directory tree and all, into the host's icon directory. Only png or svg files named snap.photo-editor.* are copied, so only the snap's own icon names are installed, and a desktop file can use that theme name instead of a path. A service that declares activates-on gets one activation file per bus name, naming its systemd unit, so the bus starts it through systemd on first use. The file carries the snap's name, which is how removal finds it. A bus name another snap already activates-on stops the install.

07 Starting at login for app developers for snapd developers

AT LOGIN snap.yamlapps:tray:autostart: tray.desktop photo-editor.tray, running~/snap/photo-editor/current/.config/autostart/tray.desktopthe app writes it; snapd does not $ snap userd --autostartrun at login by an entry in/etc/xdg/autostart 1. the file name equals an app'sautostart value2. Hidden, OnlyShowIn, NotShowInagainst XDG_CURRENT_DESKTOP hidden for this desktop: not started/snap/bin/photo-editor.tray <arguments from Exec>the command named in Exec is replaced; output goes to the journal the tray app is invented
Three stages: snap.yaml gives the tray app autostart: tray.desktop; the running app writes ~/snap/photo-editor/current/.config/autostart/tray.desktop itself; at login snap userd --autostart, started from an /etc/xdg/autostart entry, checks the file name and the Hidden, OnlyShowIn and NotShowIn keys and runs /snap/bin/photo-editor.tray with the arguments from Exec

The app key autostart names a desktop file that the app writes to $SNAP_USER_DATA/.config/autostart/. At login snap userd --autostart starts each matching file through the app's launcher. A snapd bug: a file skipped for this desktop makes the run end with autostart failed:. The tray app is invented.

photo-editor has a tray helper you'd like running at login. Inside the sandbox it can't reach the desktop's autostart folder, so how does it ask? The tray app's autostart key names a desktop file, and the app writes that file to its own config directory when you turn the option on. At login, a system autostart entry runs snap userd with the --autostart flag. It starts a file from a snap's current data directory only if an app declared that exact name, and not if it's hidden for this desktop. The command becomes the app's launcher, arguments kept. It also sets your snap directory to mode 0700.

08 Where to go from here

ROADS Interfaces: desktop and sessionwhat the desktop plug grantsSnap packagingwhere launcher files sit in a snap; the current link Snap-declaration ruleshow the store grants desktop-file-idsParallel installsthe instance key in the file name prefix Serviceswhat an activation file startssnap userd: opening links and fileslaunching these files from another snap What snapd tells desktop serviceswho reads the desktop file name backAppArmor promptingthe start of the desktop district
Roads from Desktop files, icons and D-Bus activation: the desktop interfaces, snap packaging, snap-declaration rules, parallel installs, services, snap userd, what snapd tells desktop services, and AppArmor prompting

Roads: the desktop interfaces, packaging, snap-declaration rules, parallel installs, services and the other desktop decks.

That's how a launcher, an icon and a bus name leave the snap. Here's where the neighbouring pieces are. The desktop interfaces deck covers what the desktop plug grants. Snap packaging shows where launcher files sit in a snap and what current is. snap-declaration rules explain how the store grants desktop-file-ids. Parallel installs covers the instance key in the prefix. Services covers what an activation file starts. The snap userd deck covers launching these files from another snap. What snapd tells desktop services shows who reads the desktop file name back. And AppArmor prompting opens this district.

Read more

for app developers for snapd developers for administrators

What is copied, and where

From the snapTo the hostWhen
services with activates-on, user scope/var/lib/snapd/dbus-1/services/<bus name>.servicefirst
services with activates-on, system scope/var/lib/snapd/dbus-1/system-services/<bus name>.servicefirst
meta/gui/*.desktop/var/lib/snapd/desktop/applications/second
meta/gui/icons/**/snap.<snap>.* (.png, .svg)/var/lib/snapd/desktop/icons/**third

Unlinking removes them. A failure part way removes what was already written. The desktop finds /var/lib/snapd/desktop because the login profile script /etc/profile.d/snapd.sh appends it to XDG_DATA_DIRS.

for app developers for snapd developers for administrators

File names

Source nameInstalled name
photo-editor.desktopphoto-editor_photo-editor.desktop
the same, instance photo-editor_workphoto-editor+work_photo-editor.desktop
my app!.desktopphoto-editor_my_app_.desktop
<id>.desktop, with <id> in desktop-file-ids<id>.desktop
  • Every character outside A-Z a-z 0-9 - _ . becomes _.
  • If two source files end up with the same name the second is skipped and logged.
  • Files are written with mode 0644; update-desktop-database runs afterwards if installed.
  • snapd rewrites the desktop files of every snap once per start, after seeding.

for app developers for snapd developers

Lines that are kept

  • Blank lines and comments.
  • Headers [Desktop Entry], [Desktop Action …], [… Shortcut Group].
  • Keys: Type, Version, Name, GenericName, NoDisplay, Comment, Icon, Hidden, OnlyShowIn, NotShowIn, Exec, Terminal, Actions, MimeType, Categories, Keywords, StartupNotify, StartupWMClass, PrefersNonDefaultGPU, SingleMainWindow, X-Ayatana-Desktop-Shortcuts, TargetEnvironment.
  • Localized forms such as Name[de] for Name, GenericName, Comment, Keywords.

Every other line is dropped, including TryExec, DBusActivatable, Implements, Path and URL.

for app developers for snapd developers

Lines that are rewritten or added

LineResult
Exec=<snap>[.<app>] argsExec=<launcher path> args
Exec= naming a service appExec=/usr/bin/false
Exec= naming nothing in the snapthe launcher of the app whose name equals the installed file name without .desktop, without arguments; else the line is dropped and logged
Icon=${SNAP}/…path through current; other paths, and paths that are not clean, are dropped
Icon=snap.<snap>.<x>Icon=snap.<instance>.<x>; other snap. names are dropped
Icon=<theme name>unchanged
${SNAP} anywhere<mount directory>/../current, for example /snap/photo-editor/current
after [Desktop Entry]X-SnapInstanceName=<instance> added
before each Exec=X-SnapAppName=<app> and, if set, X-SnapCommonID=<common-id> added

The fallback for an unknown Exec= compares the installed file name, prefix included. App names cannot contain _ or +, so a prefixed file such as photo-editor_tray.desktop does not match the app tray; only an unprefixed desktop-file-ids file can. The unit tests call the rewrite with an unprefixed name.

for app developers for snapd developers

desktop-file-ids

  • A list of strings on a desktop plug. Each must match ^([A-Za-z_-][\w-]*)(\.[A-Za-z_-][\w-]*)*$, else desktop-file-ids entry "<id>" is not a valid D-Bus well-known name. .desktop is appended when missing.
  • Listing an id does not create a file; only existing meta/gui files are installed.
  • The base declaration allows installing a desktop plug only when the attribute is absent, so a snap-declaration has to allow it.
  • Parallel installs are refused: "desktop-file-ids" attribute must not be set.
  • cannot install "<name>": "<path>" already exists for another snap when the target's X-SnapInstanceName names a different snap.
  • GET /v2/snaps/<name> reports common-id and desktop-file for each app.
  • A snapd bug: old files are removed by the pattern <prefix>_*.desktop, and an unprefixed file of another snap whose id begins with that prefix matches it too. Linking or removing snap foo deletes another snap's foo_bar.desktop. It needs a store-granted id of that shape.

for app developers for snapd developers

D-Bus activation files

KeyValue
Name=the bus name of the slot
Comment=Bus name for snap application <instance>.<app>
SystemdService=the app's systemd unit
Exec=the app's launcher command
AssumedAppArmorLabel=the app's security tag
User=rootsystem scope only
X-Snap=the instance name; removal selects files by this line
  • activates-on is valid only on services; the slot must use the dbus interface, its bus must match the daemon scope, and one slot cannot activate two apps.
  • snap "<a>" requesting to activate on session bus name "<name>" conflicts with snap "<b>" use fails the installation; the system bus has the same check.
  • A service with daemon-scope: user needs experimental.user-daemons, except for a few snaps that snapd lets through by snap id.

for app developers for snapd developers

Autostart

  • App key autostart: <name>.desktop. No validation of the value was found.
  • The app writes $SNAP_USER_DATA/.config/autostart/<name>.desktop.
  • /etc/xdg/autostart/snap-userd-autostart.desktop runs snap userd --autostart at login.
  • It reads ~/snap/*/current/.config/autostart/*.desktop, keeps files whose name equals an app's autostart value, applies Hidden, OnlyShowIn and NotShowIn against XDG_CURRENT_DESKTOP, replaces the command with the app's launcher and keeps the arguments. Output goes to the journal under the desktop file's name.
  • It first sets ~/snap to mode 0700.
  • A snapd bug: a file that is skipped for the current desktop is reported as a failure, so the command ends with autostart failed: and a non-zero status although every other entry started.

for snapd developers

Code and spread tests

  • Link order: overlord/snapstate/backend/link.go. Desktop files: wrappers/desktop.go. Icons: wrappers/icons.go. Activation files: wrappers/dbus.go, conflicts in overlord/snapstate/dbus.go. Autostart: usersession/autostart/autostart.go.
  • The once-per-start rewrite: ensureDesktopFilesUpdatedAfterSeed in overlord/snapstate/snapmgr.go.
  • tests/main/desktop-file-ids, with tests/lib/snaps/test-snapd-desktop-file-ids.
  • tests/main/snap-userd-desktop-app-autostart, with tests/lib/snaps/test-snapd-xdg-autostart.

Further reading

Roads from here

GETTING SNAPS

  • Snap packaging — where meta/gui sits in a snap and what the current link is

RUNNING SNAPS

  • Services — the services that a D-Bus activation file starts

INTERFACE FAMILIES · every interface, grouped by what it touches

POLICY · who may install and connect what

ADMINISTRATION · managing a system of snaps

DESKTOP · snaps in a user session