Desktop files for menu integration

doc
1

Desktop entry files are used to add an application to the desktop menu. These files specify the name and icon of your application, the categories it belongs to, related search keywords and more. These files have the extension .desktop and follow the XDG Desktop Entry Specification version 1.1.

ⓘ Note: The application icon specified in the desktop entry will be used in the desktop menu and the dock, but not in the snap store and other graphical store frontends. The snap store uses the icon specified in the icon: field in snapcraft.yaml

This documentation explains how to add these desktop files to your snap so that your application is automatically added to the desktop menu during installation.

There are three methods to tell snapcraft which desktop entry files to use.

Desktop entry files in the `snap/gui` directory⚓

The desktop file and icon should be in the folder snap/gui/ in the source folder for your snap. They should be named snap-name.desktop and snap-name.png where snap-name matches the name: entry in the snapcraft.yaml.

ⓘ Note: When you run snapcraft, the entire contents of snap/gui will be copied into the meta/gui/ folder of the resulting snap.

The Exec= line is used to specify which application to run when the user clicks on this desktop entry. It should point to the application in the apps: section of snapcraft.yaml.

Exec=app-name

Where app-name matches the name of the program in the apps: section of snapcraft.yaml or an approved alias. Note that this is the same (case sensitive) name used to run the snapped application from the commandline.

The Icon= line specifies the absolute path of the icon of the application. This icon will represent the application in the desktop menu and the dock. This path should point to the location of the icon after the snap is installed.

Icon=${SNAP}/meta/gui/snapname.png

Since snapcraft copies all the contents of the snap/gui/ folder to meta/gui, the absolute path of the icon in the installed snap will be ${SNAP}/meta/gui/snapname.png.

Use the `desktop` key to point to the entry file⚓

Some applications already generate desktop files as part of the build process. In that case, it might be easier to use the desktop key of the application because this takes a path relative to the prime directory, so you can insert a path to the generated desktop entry file.

Using this method, the desktop entry file can have any name. During a build, snapcraft will properly rename the desktop launcher, based on which app definition the desktop key is part of.

In this example, the desktop file is generated by the build system and placed in the folder usr/share/applications/, relative from the root of the resulting snap. Since the prime folder is what eventually becomes the snap, we specify usr/share/applications/com.github.johnfactotum.Foliate.desktop as the path to the desktop file.

apps:
  foliate:
    command: desktop-launch $SNAP/usr/bin/com.github.johnfactotum.Foliate
    desktop: usr/share/applications/com.github.johnfactotum.Foliate.desktop
    plugs:
      - desktop
      - desktop-legacy
    ...

During a build, snapcraft will also try to change the Icon= path in the desktop entry file. However, you need to make sure that the Icon= path is accessible from the prime folder. This example replaces the icon path after pulling the source.

parts:
  foliate:
    plugin: meson
    meson-parameters: [--prefix=/snap/foliate/current/usr]
    override-pull: |
      snapcraftctl pull

      # Point icon to the correct location
      sed -i.bak -e 's|Icon=com.github.johnfactotum.Foliate|Icon=/usr/share/icons/hicolor/scalable/apps/com.github.johnfactotum.Foliate.svg|g' data/com.github.johnfactotum.Foliate.desktop.in
    ...

What happens during installation of your snap

During installation, snapd copies the desktop files of the snap to /var/lib/snapd/desktop/applications/. The keys DBusActivatable, TryExec and Implements are currently not supported and will be silently removed from the desktop file on install. Lines with unknown keys will also be silently removed.

Further reading

4 Likes
2

I was successfully able to make a .desktop file that launched a Chromium web app by placing a .desktop file in ~/.local/share/applications/. However it didn’t work to to include /snap/chromium/current in the Exec= line of the .desktop file. What worked was target a specific version with /snap/chromium/821 as a prefix on the Exec= line. This worked fine until Chromium automatically got upgraded. This broke the ~10 web apps I had created. It will be a real pain if I have to manually update the Exec= lines each time that Chromium upgrades. Is there a way I can get a stable Exec= line for .desktop files that reference my chromium snap?

3

Please note that if the Exec line is pointing directly into /snap/chromium/…, then you are launching that snap without confinement when this desktop file is used. To launch with confinement, you should use ‘snap run …’ or point to something in /snap/bin/…

4

Thanks. This is a bug in the Chromium snap then. To reproduce run the snap and then in Chromium go to More Tools > Create Shortcut. The result for me is a file in my ~/Desktop folder with an Exec line as follows:

Exec=/snap/chromium/861/usr/lib/chromium-browser/chrome "--profile-directory=Profile 1" --app-id=fkdicmhnifiabiocmjagmfcbdhcokhno

Is this an “confinement escape bug” since enticing the user to user to use such a shortcut would result in escaping confinement?

1 Like
5

This is indeed a confinement escape bug. Details in bug #1732482.

6

It’s possibly worth adding “and is case sensitive” so idiots like me realise they’ve pushed up a file with the wrong Exec value.

1 Like
7

Logo and Icon are being used interchangeably in this part. I think it makes more sense to use icon everywhere, as logo (to me) implies something entirely different and gave me pause.

1 Like
8

And so, why is replacing

/snap/chromium/××××/usr/lib/chromium-browser/chrome

by only

chromium-browser

makes a functional launcher ( in ×buntu 20.04 at least ) ?

Should I worry about such ↓ a .desktop file ?

#!/usr/bin/env xdg-open
[Desktop Entry]
Version=1.0
Name=Deezer
Comment=Deezer (Ice SSB)
Exec=chromium-browser --app=https://www.deezer.com/fr/ --class=ICE-SSB-deezer --user-data-dir=/home/django/snap/chromium/current/.local/share/ice/profiles/deezer
X-ICE-SSB-Profile=deezer
Terminal=false
X-MultipleArgs=false
Type=Application
Icon=/home/django/snap/chromium/current/.local/share/ice/icons/deezer.ico
Categories=GTK;Network;
MimeType=text/html;text/xml;application/xhtml_xml;
StartupWMClass=ICE-SSB-deezer
StartupNotify=true

Note that the genuine shortcut feature in Chromium is still broken today ( chromium as a snap 94.0.4606.81 revision 1781 in UbuntuBudgie 20.04 )

9

Exec=/snap/chromium/××××/usr/lib/chromium-browser/chrome is completely unsupported. If the Exec= looks like that, it isn’t running in Snap sandboxing at all, and so all the usual snap guarantees of a consistent runtime environment don’t apply because you’re running it directly on the host. It’s a recipe for disaster. It’ll also just break anytime the snap revision is purged from the system with normal updates.

Otherwise, Exec=chromium-browser happens to work because /snap/bin should be in your $PATH variable and so you’d expect to find /snap/bin/chromium-desktop there. However, if any other installation of chromium-browser happens on the system, they might have a higher priority and then your shortcut to what appears to be the snap would end up not being the snap at all.

Prefer being explicit with Exec=snap run chromium-browser or Exec=/snap/bin/chromium-browser, likely the first one wins since the presence of /snap isn’t always guaranteed.

So I wouldn’t worry about your example as long as you modified Exec= to avoid calling Chromium without the sandbox, but the most technically correct option is probably snap run

1 Like
10

A very big thank you for these explanations, sincerely.

Now. Why Chromium-as-a-snap « builds » itself its .desktop shortcuts like that ?

If you just use the « built-in » Chromium feature [ menu → more tools → create shortcut ] you end up with the Exec=/snap/chromium/××××/usr/lib/chromium-browser/chrome path and a launcher that launches nothing ( which is safe, after all ).

And it’s this way since … 2017.

11

Applications in the Sandbox don’t usually know they’re actually running as snaps, they can probe to find that out by inspecting some environment variables or certain files, but they’re usually blind to the package format entirely. In this case, Chromium doesn’t have a reason to expect the .desktop file has a problem and it’d need to be patched specifically to become snap aware for this bug. I wouldn’t ever expect a fix from the snapd side for this particular issue.

Then actually putting the .desktop file in the right place for it to become used automatically opens another can of worms because snaps aren’t allowed to make their own desktop files directly, as they could put anything in the Exec= and trivially escape sandboxing. So this’d require work with snapd to design a proper interface AND for Chromium to actually integrate with it, such that snapd could inspect the .desktop file for problems as it currently does during installation.

So in essence this particular problem is something that opens a lot of problems for (relatively) little gain, so there’s probably not been much work on it so far.

1 Like
12

Again, thanks for clear explanation.

Even if they worry me a bit.

That .desktop feature from Chromium is one out of other examples of things getting broken because of snap.

Other examples I think about concern Gimp ( thumbnails for .xcf files, some plugins requiring /tmp folder, online help ).

But the more app’s moving to snap the more « little » broken features might surface…

How do we expect people to adopt snap if a snap app’ can’t work as good as it used to in APT/.deb ?

If it’s not 100% as good as it was, then choice of packaging must remain - I’m thinking about Firefox and Chromium here. Gimp is still available in many packaging.

It’s not about « gain » it’s all about being the same or better ; not less or under.

13

Why isn’t this page listed in the ToC on the left?

14

Thanks for asking this, and you’re right. Before we had foldable navigation (January this year), we simply couldn’t fit everything in, but we can do this now. I’ve added this page to the navigation.

1 Like
15

In desktop files, if we hardcode the icon name, the app will not be able show proper icons in the left of the panel and in notifications. Snaps mostly show greyscaled icons in the panel, instead of symbolic icons. Is there any way to fix it?

16

Gnome Shell requires the .desktop name of clocks and weather to be “org.gnome.clocks.desktop” and “org.gnome.Weather.desktop” in order to ensure that top bar integration does work; but snapd renames them to “gnome-clocks_org.gnome.clocks.desktop” and “gnome-weather_org.gnome.Weather.desktop”. Is there a way of avoiding snapd to rename them?

17

someone needs to recheck/correct this documenatation particularly the content under

Desktop entry files in the snap/gui directory

The only way this worked for me is when, snap name: property in the snapcraft.yaml is same as one of the app-name in the apps: section of snapcraft.yaml it just doesn’t work if I do not have any app in the apps section whose name is same as snap name.

18

If the snap name and the app name aren’t same, you won’t be able to invoke it using snap run snapName or just snapName. So, you should make those same until possible.

19

Hmm not sure why, but this link on the doc page opens on the forum rather than in the docs site: