Integrating with GNOME#
GNOME is a project to build a complete desktop and development platform based entirely on free software. Many companies, governments, schools, institutions, and individuals have deployed the GNOME desktop on their systems. If you are a developer of third-party software (“Independent Software Vendor” or ISV, or “Independent Software Developer” (ISD) if you don’t do it commercially), you may want to ensure that your existing software runs properly under GNOME. This guide explains how to integrate existing software with GNOME, without actually rewriting that software to explicitly use the GNOME platform libraries and development tools.
This guide will be useful in the following situations:
You are a software developer or distributor who has an application that is not explicitly designed to work with GNOME, but you want to ensure that it runs comfortably within a GNOME desktop.
You are a system administrator for an institution that has deployed GNOME desktops to its users. You also have legacy or in-house applications, and you want your users of GNOME to be able to access those applications comfortably.
You are writing a GNOME application proper and you need a checklist of basic things to do to ensure that your application integrates well with the rest of the GNOME desktop.
In general, this guide is about integrating existing software into a GNOME desktop. On the other hand, if you are considering writing new software, we encourage you to develop it completely with GNOME as your target platform; please refer to the GNOME Developer’s Site for more information.
One of the main concerns of GNOME is the user experience. Users should have a comfortable computing environment: this means having a complete desktop and a set of applications which operate together in a consistent way. With relatively little work, applications which are not written explicitly with GNOME in mind can be made to run comfortably within a GNOME desktop.
To run applications from GNOME, users click on icons on their desktops or they select the applications which they want to run from the applications grid. Therefore, the first step in integrating an existing program with GNOME is to register it with the set of applications that users can run.
The applications grid is automatically constructed from the list of registered applications.
In GNOME and other freedesktop.org-compliant desktops, an application gets
registered into the desktop’s menus through a desktop entry, which is a text
.desktop extension. This desktop file contains a listing of the
configurations for your application. The desktop takes the information in this
file and uses it to:
associate the name, description, and icon of the application
associate each window created by the application with the same name and icon
recognize the MIME types it supports for opening files
To register your application, create a desktop file using the same
application identifier you chose for your application and the
For more information about the application identifier, please see the Application ID tutorial.
A typical desktop file will have the following structure:
[Desktop Entry] Name=Your Application Comment=An amazing application Exec=your-application Icon=com.example.YourApplication Keywords=various;keywords;describing;your;application; StartupNotify=true Terminal=false
Some keys in your desktop files can be localized in different languages, like
Keywords keys. By localizing
your desktop file you allow users from different parts of the world to find your
application more easily.
For more information about the format of the desktop files, please visit the Freedesktop.org Desktop Entry specification.
You should ensure that your desktop file is valid as part of your project’s
test suite. You can use the
desktop-file-validate utility provided by the
Your desktop file should be installed under one of the
directories of the
XDG_DATA_HOME environment variables,
depending on the installation prefix. For system installations, the former
/usr/share/applications; for user installations, the latter
For more information about the XDG directories, please visit the Freedesktop.org Base Directories specification
Application icons should be installed following the Freedesktop.org Icon Theme specification. For GNOME applications, you should provide
a full color scalable icon using the SVG format
a full color, 256×256 pixels raster icon using the PNG format
You should also, optionally, provide a symbolic icon using the SVG format.
You should install your icon under the
hicolor icon theme namespace, using
the application identifier as the base name for the icon; for instance:
Instead of the typical UNIX-style
exec() approach to process
creation, launching an application in GNOME is preferably done by sending a
D-Bus message to the well-known name of that application, causing a D-Bus
activation. In the case that the application is already running, it can respond
to the message by opening a new window or raising its existing window, instead
of launching a new instance.
Starting processes with D-Bus activation ensures that each application gets
started in its own pristine environment, as a direct descendent of the
session, not in the environment of whatever its parent happened to be. This is
important for ensuring the app ends up in the correct
cgroup, for example.
Another reason is that being D-Bus activatable is a prerequisite for using persistent notifications.
In order for D-Bus to know how to activate your service, you need to install a
D-Bus service file under
[D-BUS Service] Name=com.example.YourApplication Exec=/usr/bin/your-app
You will also need to add the following key to your application’s desktop file:
DBusActivatable is true and the desktop file name looks like a valid
application ID, then the
Exec line will be ignored and your application will
be started by way of D-Bus activation instead (using the name of the desktop
file minus the
.desktop extension as the application ID).
If your application can open specific MIME types, you need to let the desktop know in the desktop file. For example, if your application can accept PNG files, add the following line into your desktop file:
Additional MIME types can be added by separating the different types with semicolons.
You will also need to add
%F as argument to your
Exec line if your
application supports opening multiple files at once, or
%f if it only
supports opening one file at a time, which will open multiple instances of
your application when opening a selection of files that your application
The system already knows of a large number of MIME types. However, if you are
creating one of your own, you need to register your MIME type into the MIME
database, by creating an XML file in the
<?xml version="1.0" encoding="UTF-8"?> <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"> <mime-type type="application/x-example"> <comment>Example file type </comment> <magic priority="50"> <match value="search-string" type="string" offset="10:140"/> </magic> <glob pattern="*.newextension"/> </mime-type> </mime-info>
To avoid collisions with files added by other applications, you should use
your application’s ID as the basename for the file, e.g.
In this example, replace the example MIME type with the name of your MIME type.
magic rule searches the contents of the file for the given string for
glob rule uses the suffix of file names for
magic rule forces the computer to open the files to search
for the string, the
glob rule is preferable.
Once your new MIME type is adequately described in the file, run the following in a shell:
For more information on choosing a good MIME extension and to register your MIME type, go to the IANA website.
URI schemes handling#
If your application can open specific URI schemes, you need to let the desktop know in the desktop file. For example, if your application can accept mailto: URIs, you need to add the corresponding x-scheme-handler/mailto to the MIME types in the desktop file, as done in the previous section. You can use any URI scheme you want, not just the common ones like mailto/http/https/ftp, for example the gemini:// URI scheme.
You also need to use %u or %U for respectively one or several URIs, the same way it was done with %f and %F in the previous section. If your app handles MIME types in addition to URIs, you only need to use the %u or %U version, no need to use %f and %F.