Desktop Files

Desktop files contain information about the application or script they belong to. They’re most often used with binary executables, but you can use them with a script too, should you wish. For brevity, we’re just going to say “application.”

A desktop file contains metadata that your desktop environment can reference when it is dealing with that application. The desktop file will specify where the application binary or script is, what icon it uses, and so on. Because desktop files are stored in standard locations, your desktop environment can reliably locate and reference them.

If an application doesn’t have a desktop file some of its integration with your desktop environment will fail. It won’t appear in the results of application searches, nor will you be able to pin it to the dock or other launcher. On some desktop environments, you can place a desktop file on your desktop and it will act as a shortcut, letting you run the application by double-clicking the desktop file. It’s this use-case that gave them their name.

Applications might not have a desktop file for a number of reasons. The installation routine may have hiccuped, or it might be a minimalist installer that never intended to provide one. Downloading an application as source code and compiling it on your computer often doesn’t create a desktop file.

Of course, if you’ve written the application yourself, you’re responsible for the desktop file, too. Applications that are well-behaved and conform to the norms and expectations of your desktop environment are the ones that feel professional and give users confidence you know what you’re doing.

Regardless of why you’re about to create a desktop file, how to do it is the same in all cases.

The Construction of a Desktop File

A desktop file is a plain text file. They can be created using any text editor. They are given the same name as the application they represent, and by convention have a “.desktop” extension.

Desktop files may contain comments, group headers, and key-value pairs.

• Comments: Comments start with a hash “#“.
• Group Headers: Group headers act as section titles. They are enclosed within brackets “[]”. They are used to group together related sets of key-value pairs. The only mandatory group header is “[Desktop Entry].”
• Key-Value Pairs: Settings are entered by providing values to named elements, or “keys.” For example, Type=Application is a key-value pair. “Type” is the key and “Application” is the value.

A Worked Example

Before you start, make sure the application runs. Open a terminal window, and launch the application. If it runs, that’s great. You can go ahead and make your desktop file. If the application doesn’t run, then no matter what you put in your desktop file it still won’t run.

You need to correct whatever it is that is preventing the application from launching before you even think about adding another layer of abstraction by way of a desktop file.

The program we’re working with has an executable called taf located in the “/usr/local/bin/taf/” directory. We’ll launch the application to make sure it starts up without any issues.

./taf

The program launches just fine.

That simple test yields useful knowledge. If we encounter difficulties trying to launch the application from our desktop file, it means the problem must be something to do with the desktop file, and not the application itself.

We can create our desktop file anywhere, but to put it into use we need to copy it into one of two places.

• If you’re the only person who will use the application, copy your desktop file to your “~/.local/share/applications” directory.
• If you want all users to be able to use the application, copy your desktop file to the “/usr/share/applications/” directory.

A fully-working desktop file doesn’t have to contain very much information. Here’s the desktop file we created for the taf application. It’s called “taf.desktop.”

[Desktop Entry]
Name=Text Adventure Framework
GenericName=Interpreter for GDL Adventure Scripts
Comment=Game Description Language interpreter
Version=1.0
Exec=/usr/local/bin/taf/taf
Path=/usr/local/bin/taf/
Icon=/usr/local/bin/taf/taf_icon.png
Terminal=false
Type=Application
Categories=GNOME;GTK;Game;

This can be used as a template for your own desktop files. Remember to use the name of your executable for the application you’re creating the desktop file for, and amend the directory paths to suit.

This is what each of the lines means.

• [Desktop Entry]: This line identifies the file as a desktop file. Even if the file was misnamed and did not have a “.desktop” extension, it ought to be recognized and handled as a desktop file.
• Name: The full title of the application, not the name of the executable. This will be shown beneath the application icon when it is displayed in the desktop environment. It is also the text that will be used in tooltips.
• GenericName: A general description of the type of application this is. If there is a generic term that applies such as web browser, IDE, or word processor, you could use that.
• Comment: This is intended to provide additional information to supplement the “Name” and “GenericName” key-value pairs.
• Version: The version of the desktop file specification to which this file conforms.
• Exec: This may be the name of the executable, or the full path to the executable, including the name of the executable.
• Path: This is the path to the directory that the application will be launched from. It’s the working directory of the application at launch time.
• Icon: The icon of the application. This icon is used in application search results and when the application is added to the dock or other launcher.
• Terminal: Indicates whether the application runs in a terminal window.
• Type: For regular applications, this will always be “Application.”
• Categories: This value should be terminated by a semi-colon “;” because it holds a list. The list holds categories that the application may be listed under in menus.

Each time you modify your live desktop file—the one in “~/.local/share/applications” or “/usr/share/applications/”—you’ll need to log out and in again to see what effect your changes have made. To avoid this you can use the update-desktop-database command. You’ll need to use sudo when you do.

sudo update-desktop-database

There’s also a utility to check your desktop file for correctness. If it detects any syntax or other errors it’ll report them to you. We’ll add the word “Application” to the “Categories” line in our file, and check it.

We changed the last line to be:

Categories=GNOME;GTK;Game;Application;

This should raise an error because the “Application” category has been deprecated.

desktop-file-validate taf.desktop

The validator gives us a warning that the “Application” category is no longer an acceptable value in the “Categories” list.

Using Your Desktop File

If the application is for your use only, copy the desktop file to your “~/.local/share/applications” directory. If all users are allowed to use the application, copy the desktop file to the “/usr/share/applications/” directory.

We’re going to copy it to the “/usr/share/applications/” directory.

sudo cp taf.desktop /usr/share/applications

We’ll also ensure our new desktop file is read and has its metadata added to the database.

sudo update-desktop-database

The “Super” key is usually located between the left-hand “Ctrl” and “Alt” keys. Pressing the “Super” key in GNOME enters the application search. Because our desktop file described an application called “Text Adventure Framework”, entering “text” as the search clue is enough to display the application’s icon in the search results.

Clicking the icon launches the application.

The application has been integrated nicely into the desktop environment. Its icon is correctly displayed in the dock while it runs. Pointing to the icon displays a tooltip containing the full name of the application.

Clicking the icon shows the window preview view, showing the windows that the application has opened.

Right-clicking the application icon produces a context menu. Selecting the “Add to Favorites” option pins the application to the dock.

The application icon is moved above the separator line and becomes a permanent icon on the dock. The icon is present even when the application is not running.