Today we'll explore the Desktop Entry specification, and see how we can implement it to integrate applications into our desktop environment.  Specifically, we'll do this by creating a desktop entry file for Calibre, a great e-book organizer that I use regularly.  For a couple of different reasons, I installed Calibre from source, and so it didn't automatically get a desktop entry created for it like it would have had it been installed via aptitude.  Regardless of cause, the situation serves as a good opportunity to create a desktop entry manually!

A quick screen of Calibre:

Calibre Screenshot

Now I use the application launcher kupfer, which displays a nice image alongside various application launching options.  It looks and feels much like the OS X Quicksilver launcher to which I used to be very attached.

This article presupposes some familiarity with Linux and itself takes place within the context of Debain 10 running i3.  The information here however is highly general, and should apply with little to no modification to most distros and desktop environments.

Background and Information Gathering:

A desktop entry file is a fairly standardized way of organizing information about an installed application for use by various desktop environment components like menus and launchers.  For example, kupfer, Ubuntu's Unity and Cinnamon's start-like menu all use them to find the icons for, and how to launch an application.

We can find out a little bit about our environment by looking at an xdg environment variable:

$ echo $XDG_DATA_DIRS
/usr/local/share:/usr/share

So our environment is looking at those directories for information about things we might ask it to do.  Let's checkout what's in /usr/share/:

$ cd /usr/share/
$ ls -l
drwxr-xr-x    2 root root 4.0K Feb 24 10:17 aclocal/
drwxr-xr-x    2 root root 4.0K Dec 20 08:57 adduser/
drwxr-xr-x    2 root root 4.0K Jan 14 15:03 aglfn/
drwxr-xr-x    9 root root 4.0K Dec 20 22:26 alsa/
drwxr-xr-x    5 root root 4.0K Jan  7 10:37 ant/
drwxr-xr-x    6 root root 4.0K Dec 22 22:25 apache2/
drwxr-xr-x    2 root root 4.0K Dec 20 07:56 apparmor-features/
drwxr-xr-x    2 root root 4.0K Feb 28 12:36 appdata/
drwxr-xr-x    2 root root 4.0K Jan  7 10:38 application-registry/
drwxr-xr-x    3 root root 4.0K Mar  2 10:38 applications/
...
drwxr-xr-x    6 root root 4.0K Dec 20 15:28 zsh/

Looks like folders for the installed applications!

Let's specifically checkout that 'applications' folder:

$ cd /usr/share/applications
$ ls -l
-rw-r--r-- 1 root root 9.0K Nov  3  2018 clementine.desktop
-rw-r--r-- 1 root root 1.9K Feb 14  2019 debian-uxterm.desktop
-rw-r--r-- 1 root root 2.0K Feb 14  2019 debian-xterm.desktop
-rw-r--r-- 1 root root  490 Dec  7  2018 feh.desktop
-rw-r--r-- 1 root root 3.8K Feb 11 16:50 firefox-esr.desktop
...
-rw-r--r-- 1 root root 7.3K Mar 28  2018 xfce4-power-manager-settings.desktop
-rw-r--r-- 1 root root 1.3K Jan 24  2019 xscreensaver-properties.desktop
-rw-r--r-- 1 root root  11K Feb  4  2019 yelp.desktop

And there are a bunch of desktop entries!  Unless you've already created some manually, these have been created by your package manager.  Further, things installed here will be available to any user on the system, as is typical with any data not located within a /home/<username>/ folder.

Let's look at one of the entries:

$ vi sublime_text.desktop

The Structure of a Desktop Entry:

Sublime's text's entry is reasonably short and straight forward:

[Desktop Entry]
Version=1.0
Type=Application
Name=Sublime Text
GenericName=Text Editor
Comment=Sophisticated text editor for code, markup and prose
Exec=/opt/sublime_text/sublime_text %F
Terminal=false
MimeType=text/plain;
Icon=sublime-text
Categories=TextEditor;Development;
StartupNotify=true
Actions=Window;Document;

[Desktop Action Window]
Name=New Window
Exec=/opt/sublime_text/sublime_text -n
OnlyShowIn=Unity;

[Desktop Action Document]
Name=New File
Exec=/opt/sublime_text/sublime_text --command new_file
OnlyShowIn=Unity;

A detailed explanation of what's going on here can be found here.  Let's briefly consider the important ones:

  • [Desktop Entry] Declares this to be a desktop entry file
  • Type declares the kind of thing the entry is for.  While we're going to use 'Application' as well, there is also 'Link' and 'Directory'
  • Comment is a string that will be displayed as subtext in some contexts.  In kupfer it is displayed along with the Applications' icon
  • Name is the title of the application as it will be displayed
  • Exec is the path of the executable to launch
  • Icon is the path to the icon to use.  Though if a spec-compliant folder structure exists you can use short-hand like this entry does, you can also simply specify the full path to the icon

Sublime's entry also contains several Unity-specific invocations which while perhaps cool, aren't of much interest from our perspective here.  In short, they allow for additional actions to be associated with an application and provide for alternative modes of opening or starting an application.  In this case, they're Ubuntu-centric.

Creating our Own Entry:

As we mentioned earlier, if we want an entry to be available to all users on the machine, we can place it in a global place, like /usr/share/applications/.  Alternatively, if we want it to be available only to a specific user, we can place it in ~/.local/share/applications.

For the sake of diversity, let's create a user-specific entry for Calibre.  Let's create a new file:

$ vi ~/.local/share/applications/calibre.desktop

Let's use the following information:

[Desktop Entry]
Type=Application
Name=Calibre
Comment=E-Book Management
TryExec=/opt/calibre/calibre
Exec=/opt/calibre/calibre %F
Icon=/opt/calibre/resources/images/book.png

Save, and you should now be able to launch Calibre with either kupfer, or whatever other launcher you'd like!

* A note, though most similar information on the web use the %F option, however I haven't been able to find documentation on it, and launch behavior seems to be the same whether it's used or not.  Since it's in the package-manager version, I've kept it in my entry as well.

Now you're ready to start creating desktop entries for whatever you'd like!

# Reads: 1226