FreeDesktop Structure

These are notes of the structure of desktops following the Freedesktop specifications.

XDG menus

  • XDG Menu in LXDE
  • ArchLinux: Xdg-menu
  • xdg-utils is a set of command line utilities for Free Desktop: creating menus, opening files, setting mime types it includes the command xdg-desktop-menu which is used for (un)installing freedesktop menu items i.e. .desktop files for freedesktop compatible environments.
  • To build the full desktop menu many distribution use a command to browse the freedesktop menu hierarchy xdg-menu. It is decribed in Archlinux :archwiki`Xdg-Menu`.
  • In Debian the freedesktop menus are generated from Debian Menus System by the command install-menu with the configuration /etc/menu-methods/menu-xdg from the package menu-xdg. To use them with default config $XDG_MENU_PREFIX must be set to debian-.
  • Debian is using the alternate debian menu, with the increasing spreading of Free desktop menus through .desktop files, it becomes more difficult to maintain a debian menu file for each package. There was a Proposal: using Desktop entries with the Debian menu system which compare Debian menus with .xdesktop files. An alternative is to switch debian packaging to freedesktop menus, it is developped in Debian and application-menu policies.

XDG Default application.

The Freedesktop way of opening applications is through xdg-open and the Mime type of the file.

Each application provide a .desktop file that conform to Desktop Entry Specification, amon many key, value pairs this file contain a key MimeType that indicates the MIME Types that an application knows how to handle. An application is expected to be able to reasonably open files of these types using the command listed in the Exec key. It is specified in Mime Actions Specification.

Example:

$ cat /usr/share/applications/feh.desktop
[Desktop Entry]
Name=Feh
.......
Exec=feh %F
Type=Application
.......
MimeType=image/jpeg;image/png;image/gif;image/tiff;image/bmp;
         image/x-icon;image/x-xpixmap;image/x-xbitmap;

ArchLinux wiki <https://wiki.archlinux.org/> has also many related documentation : Default applications describe mime database, xdg-open, xdg-mime, ect. Xdg user directories, :archwiki:`Desktop Entries.

It list also some alternatives, that try to provide more flexibility than the official Freedesktop mechanism.

Managing default applications with xdg-utils.

To know the mime file type of a file we use xdg-mime:

$ xdg-mime query filetype example.png
image/png

An URI is associated with a special mime type x-scheme-handler/scheme where scheme is the URI scheme like http, https, ftp, mms, rtsp …. (see URI scheme handlers in freedesktop specification)

What application open this file type:

$ xdg-mime query default image/png
feh.desktop

Change the default application:

$ xdg-mime default geeqie.desktop image/png

Open a file with the default application with xdg-open:

$ xdg-open example.png

The command xdg-settings allow to change at once all defaults for web scheme handlers or other url scheme handlers:

$ xdg-mime query default x-scheme-handler/http
org.kde.falkon.desktop
$ xdg-mime query default x-scheme-handler/https
org.kde.falkon.desktop
$ xdg-settings get default-web-browser
org.kde.falkon.desktop
$ xdg-settings set default-web-browser firefox.desktop
$ xdg-settings get default-web-browser
firefox.desktop
$ xdg-mime query default x-scheme-handler/http
firefox.desktop
$ xdg-settings get default-url-scheme-handler http
firefox.desktop
$ xdg-settings get default-url-scheme-handler mms
smplayer.desktop
$ xdg-mime query default x-scheme-handler/mms
smplayer.desktop

As seen above xdg-settings is a convenience tool that replace one or many operations that can also be done with xdg-mime, but usually we want to use the same browser for all web url

If you have the gio command from the libglib2.x-bin package (glib is used in GTK+ and Gnome applications) you can use it to see all packages that declare the mime type by issuing a query like:

$ gio mime x-scheme-handler/http

you can use any mime type. With gio you don’t have to dig manually in the mime databases, in the file system, that we now describe.

The mimeapps file.

Each mimeapps file is composed of many sections:

  1. Default Applications: are made of lines like:

    mimetype=application1.desktop;application2.desktop...

    They give the default to open this mime type, many defaults can be specified in the same or different mimeapps file they are used in their order in the file or in the mimeapps browse order. The first application installed is used some may be missing.

  2. Added Associations: The association between an application and the mime types elle can open is usually defined in the desktop file, but this section define some added associations.

  3. Removed Associations: removes associations of applications with mimetypes, this mean that this asociation is not used, even if present in a desktop.

Added associations should be in preference order, if a valid default application is not used the higher preferrence association will be used.

The adding and removal of associations only applies to desktop files in the current directory, or a later one, this mean that if a desktop file is defined say in /etc/xdg directory you cannot add or remove an association related to it in /usr/local/share/applications/mimeapps.list that has a lower priority.

You can see all applications are defined for each mime type in /usr/share/applications/mimeinfo.cache, they are not prioritized in this file which only summarize the MimeType= field of each desktop file.

The priority for each type is shown in the first file with this type in this list: ~/.config/$desktop-mimeapps.list, ~/.config/mimeapps.list, /etc/xdg/$desktop-mimeapps.list, /etc/xdg/mimeapps.list, /usr/local/share/applications/$desktop-mimeapps.list, /usr/local/share/applications/mimeapps.list, /usr/share/applications/$desktop-mimeapps.list, /usr/share/applications/mimeapps.list.

Each of these files can be absent, the $desktop-mimeapps.list are seldom used, in these entry $desktop is stand for $XDG_CURRENT_DESKTOP environment variable, which contain the desktop name in lowercase.

Here we have used the defaults for the examined directories, of course you should use instead the Freedesktop Directory environment variables instead if they are not let at their default values.

For a detailed description of the mimeapps traversal algorithm look at Adding/removing associations in Mime Actions Specification.

The previous utilities changes the entries in ~/.config/mimeapps.list.

Follow the Gnome System Administration Guide instructions, if you want to add a custom MIME type for all users or add a custom MIME type for individual users.

Freedesktop Directories

The Base Directories are used when looking for for user configuration.

The freedesktop base directories that follow is used by all freedesktop compatible application. They have a default that can be overrided by exporting in your environment the variables.

  • $XDG_DATA_HOME default $HOME/.local/share contains user-specific data files.
  • $XDG_CONFIG_HOME default $HOME/.config contains user specific configuration files.
  • $XDG_DATA_DIRS default /usr/local/share/:/usr/share/ are directories seperated with a colon ‘:’ to search for data in addition of $XDG_DATA_HOME
  • $XDG_CONFIG_DIRS default /etc/xdg are directories seperated with a colon ‘:’ to search for configuration files in addition of $XDG_CONFIG_HOME. Configurations are searched in directory order, using the first match.
  • $XDG_CACHE_HOME default $HOME/.cache for temporary data.
  • $XDG_RUNTIME_DIR temporary runtime, his life must be the session, and it must be owned by the user with access mode 0700 see full requirement in the `specification <http://standards.freedesktop.org/basedir-spec/latest/>`__ Usually it is set by pam_systemd at login and there is no need to change it. You can get its value from the environment variable $XDG_RUNTIME_DIR.

The user directories are the directories under $HOME used by your desktop to store your data their default set in $XDG_CONFIG_DIRS/user-dirs.defaults usually /etc/xdg/user-dirs.defaults it default to:

DESKTOP=Desktop
DOWNLOAD=Downloads
TEMPLATES=Templates
PUBLICSHARE=Public
DOCUMENTS=Documents
MUSIC=Music
PICTURES=Pictures
VIDEOS=Videos

These system defaults can be changed in user-dirs.defaults.

The program xdg-user-dirs-update is run very early in the login phase. This program reads a configuration file, and a set of default directories. It then creates localized versions of these directories in the users home directory and sets up a config file in $(XDG_CONFIG_HOME)/user-dirs.dirs defaults to ~/.config that applications read to find these directories.

You can customize the values in your ~/.config/user-dirs.dirs; as an example if you have a non english locale and wish to force these directories to keep their default english names run:

$ LC_ALL=C xdg-user-dirs-update

That will create the ~/.config/user-dirs.dirs. It also creates an ~/.config/user-dirs.locale used to remember the locale used and allowing to translate names if it changes.

An other popular alternative to avoid to create too many directories under $HOME is:

MUSIC=Documents/Music
PICTURES=Documents/Pictures
VIDEOS=Documents/Videos

The Debian Wiki list the dotfiles we can find in a Debian system, their role and the programs that use them. Most of them are not yet following the XDG standard, many programs may be launched with a specific environment on command line option to make them comply with xdg satndard as explained in ArchWiki: XDG Base Directory support. You can also symlink many of these files or directories inside the corresponding XDG Base directory.

Autostart applications

Applications referenced by a .desktop file in $XDG_CONFIG_DIRS/autostart and $XDG_CONFIG_HOME may be autostarted by xdg compliant window managers.

In additions to generic keys, autostart .desktop files may contain additional keys:

  • Hidden when true, the application is ignored
  • OnlyShowIn and NotShowIn can list desktop environments in which the application is only (not?) started. These two keys are exclusives each other.
  • TryExec: Tha application is started only when the named exec exist. It can be an absolute path or a name to be looked for in $PATH.