Difference between revisions of "Desktop entries"

From ArchWiki
Jump to: navigation, search
(How to use)
m (List or search in .desktop files: changed --less to --list , the old options --less can still be used)
 
(96 intermediate revisions by 25 users not shown)
Line 1: Line 1:
 
[[Category:Package development]]
 
[[Category:Package development]]
Desktop entries is a [http://www.freedesktop.org/wiki/ freedesktop.org] standard for specifying the behaviour of programs running on [[X Window System]]s. It is a configuration file that describe how an application is launched and how it appears in a menu with an icon. The most common desktop entries are the {{ic|.desktop}} and {{ic|.directory}} files. This article explains briefly how to create useful and standard compliant desktop entries. It is mainly intended for package contributors and maintainers, but may also be useful for software developers and others.
+
[[ja:デスクトップエントリ]]
 +
[[zh-CN:Desktop entries]]
 +
The freedesktop [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html Desktop Entry specification] provides a standard for applications to integrate into a [[desktop environment]]. Desktop entries are the configuration files that describe how an application is launched and which data it can handle. They also configure how an application appears in a menu with an icon, which is subject to the related [https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html menu specification] standard.  
  
{{Note|A lot of applications do not have a desktop entry by default or they have one that could be improved. To participate in creating and maintaining desktop entries, please join the [[Arch Desktop Project]].}}
+
The most common desktop entries are the {{ic|.desktop}} and {{ic|.directory}} files. This article explains briefly how to create useful and standard compliant desktop entries. It is mainly intended for package contributors and maintainers, but may also be useful for software developers and others.
  
 
There are roughly three types of desktop entries:
 
There are roughly three types of desktop entries:
 +
 
; Application : a shortcut to an application
 
; Application : a shortcut to an application
 
; Link : a shortcut to a web link.
 
; Link : a shortcut to a web link.
 
; Directory : a container of meta data of a menu entry
 
; Directory : a container of meta data of a menu entry
The following sections will roughly explain how these are created and validated.
 
  
==Application entry==
+
The following sections will roughly explain how these are created and validated.
 +
 
 +
Related to this content, and also defined in {{ic|.desktop}} files, are MIME-type associations for data files. [[Default applications]] describes how these are configured.
 +
 
 +
== Application entry ==
 +
 
 +
Desktop entries for applications, or {{ic|.desktop}} files, are generally a combination of meta information resources and a shortcut of an application. These files usually reside in {{ic|/usr/share/applications}} or {{ic|/usr/local/share/applications}} for applications installed system-wide, or {{ic|~/.local/share/applications}} for user-specific applications. User entries take precedence over system entries.
  
Desktop entries for applications or {{ic|.desktop}} files are generally a combination of meta information resources and a shortcut of an application. These files usually reside in {{ic|/usr/share/applications}}.
+
=== File example ===
  
===File example===
+
Following is an example of its structure with additional comments. The example is only meant to give a quick impression, and does not show how to utilize all possible entry keys. The complete list of keys can be found in the [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys freedesktop.org specification].
Following is an example of its structure with additional comments. The example is only meant to give a quick impression, and does not show how to utilize all possible entry keys. The complete list of keys can be found in the [http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s05.html freedesktop.org specification].
+
  
 
  [Desktop Entry]
 
  [Desktop Entry]
  Type=Application                          # Indicates the type as listed above
+
   
  Version=1.0                              # The version of the desktop entry specification to which this file complies
+
# The type as listed above
  Name=jMemorize                            # The name of the application
+
  Type=Application
  Comment=Flash card based learning tool    # A comment which can/will be used as a tooltip
+
  Exec=jmemorize                            # The executable of the application.
+
# The version of the desktop entry specification to which this file complies
  Icon=jmemorize                           # The name of the icon that will be used to display this entry
+
  Version=1.0
  Terminal=false                            # Describes whether this application needs to be run in a terminal or not
+
  Categories=Education;Languages;Java;      # Describes the categories in which this entry should be shown
+
# The name of the application
 +
  Name=jMemorize
 +
 +
# A comment which can/will be used as a tooltip
 +
  Comment=Flash card based learning tool
 +
 +
# The path to the folder in which the executable is run
 +
Path=/opt/jmemorise
 +
 +
# The executable of the application.
 +
  Exec=jmemorize
 +
 +
# The name of the icon that will be used to display this entry
 +
  Icon=jmemorize
 +
 +
# Describes whether this application needs to be run in a terminal or not
 +
  Terminal=false
 +
 +
# Describes the categories in which this entry should be shown
 +
Categories=Education;Languages;Java;
  
===Key definition===
+
=== Key definition ===
  
All Desktop recognized desktop entries can be found on the site of the project Freedesktop.org site on the following [http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s05.html link].
+
All Desktop recognized desktop entries can be found on the [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys freedesktop.org] site.
For example the {{Ic|Type}} key defines 3 types of desktop entries: Application (type 1), Link (type 2) and Directory (type 3).
+
For example, the {{Ic|Type}} key defines three types of desktop entries: Application (type 1), Link (type 2) and Directory (type 3).
  
 
* {{Ic|Version}} key does not stand for the version of the application, but for the version of the desktop entry specification to which this file complies.
 
* {{Ic|Version}} key does not stand for the version of the application, but for the version of the desktop entry specification to which this file complies.
  
* {{Ic|Name}}, {{Ic|GenericName}} and {{Ic|Comment}} often contain redundant values in the form of combinations of them, like:  
+
* {{Ic|Name}}, {{Ic|GenericName}} and {{Ic|Comment}} often contain redundant values in the form of combinations of them, like:
  
 
  Name=Pidgin Internet Messenger
 
  Name=Pidgin Internet Messenger
Line 40: Line 66:
 
or
 
or
 
  Name=NoteCase notes manager
 
  Name=NoteCase notes manager
  Comment=Notes Manager  
+
  Comment=Notes Manager
  
This should be avoided, as it will only be confusing to users. The {{Ic|Name}} key should only contain the name, or maybe an abbreviation/acronym if available.  
+
This should be avoided, as it will only be confusing to users. The {{Ic|Name}} key should only contain the name, or maybe an abbreviation/acronym if available.
  
 
* {{Ic|GenericName}} should state what you would generally call an application that does what this specific application offers (i.e. Firefox is a "Web Browser").
 
* {{Ic|GenericName}} should state what you would generally call an application that does what this specific application offers (i.e. Firefox is a "Web Browser").
 
* {{Ic|Comment}} is intended to contain any usefull additional information.
 
* {{Ic|Comment}} is intended to contain any usefull additional information.
  
====Deprecation====
+
==== Deprecation ====
 +
 
 
There are quite some keys that have become deprecated over time as the standard has matured. The best/simplest way is to use the tool {{Ic|desktop-file-validate}} which is part of the package {{Pkg|desktop-file-utils}}. To validate, run
 
There are quite some keys that have become deprecated over time as the standard has matured. The best/simplest way is to use the tool {{Ic|desktop-file-validate}} which is part of the package {{Pkg|desktop-file-utils}}. To validate, run
 
  $ desktop-file-validate <your desktop file>
 
  $ desktop-file-validate <your desktop file>
 
This will give you very verbose and useful warnings and error messages.
 
This will give you very verbose and useful warnings and error messages.
  
==Icons==
+
== Icons ==
===Common image formats===
+
 
 +
See also the [https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html Icon Theme Specification].
 +
 
 +
=== Common image formats ===
  
 
Here is a short overview of image formats commonly used for icons.
 
Here is a short overview of image formats commonly used for icons.
  
{| class="wikitable" border="1" cellpadding="5" align="center"
+
{| class="wikitable" align="center"
|+ Support for image formats for icons as specified by the [http://standards.freedesktop.org/icon-theme-spec/latest/ar01s02.html freedesktop.org standard].
+
|+ Support for image formats for icons as specified by the freedesktop.org standard.
 
! Extension
 
! Extension
 
! Full Name and/or Description
 
! Full Name and/or Description
Line 68: Line 98:
 
| Portable Network Graphics
 
| Portable Network Graphics
 
| [[wikipedia:Raster graphics|Raster]]
 
| [[wikipedia:Raster graphics|Raster]]
|bgcolor="red" | no
+
| {{No}}
|bgcolor="#00cc00"| yes
+
| {{Yes}}
 
|-
 
|-
 
!align="left" | .[[wikipedia:Scalable Vector Graphics|svg(z)]]
 
!align="left" | .[[wikipedia:Scalable Vector Graphics|svg(z)]]
 
| Scalable Vector Graphics
 
| Scalable Vector Graphics
 
| [[wikipedia:Vector graphics|Vector]]
 
| [[wikipedia:Vector graphics|Vector]]
|bgcolor="red" | no
+
| {{No}}
|bgcolor="#66cc00"| yes (optional)
+
| {{G|Yes (optional)}}
 
|-
 
|-
 
!align="left" | .[[wikipedia:X PixMap|xpm]]
 
!align="left" | .[[wikipedia:X PixMap|xpm]]
 
| X PixMap
 
| X PixMap
 
| [[wikipedia:Raster graphics|Raster]]
 
| [[wikipedia:Raster graphics|Raster]]
|bgcolor="red" | no
+
| {{No}}
|bgcolor="yellow"| yes (deprecated)
+
| {{Y|Yes (deprecated)}}
 
|-
 
|-
 
!align="left" | .[[wikipedia:Graphics Interchange Format|gif]]
 
!align="left" | .[[wikipedia:Graphics Interchange Format|gif]]
 
| Graphics Interchange Format
 
| Graphics Interchange Format
 
| [[wikipedia:Raster graphics|Raster]]
 
| [[wikipedia:Raster graphics|Raster]]
|bgcolor="red" | no
+
| {{No}}
|bgcolor="red"| no
+
| {{No}}
 
|-
 
|-
 
!align="left" | .[[wikipedia:ICO (icon image file format)|ico]]
 
!align="left" | .[[wikipedia:ICO (icon image file format)|ico]]
 
| MS Windows Icon Format
 
| MS Windows Icon Format
 
| [[wikipedia:Raster graphics|Raster]]
 
| [[wikipedia:Raster graphics|Raster]]
|bgcolor="#00cc00" | yes
+
| {{Yes}}
|bgcolor="red"| no
+
| {{No}}
 
|-
 
|-
 
!align="left" | .[[wikipedia:Apple Icon Image|icns]]
 
!align="left" | .[[wikipedia:Apple Icon Image|icns]]
 
| Apple Icon Image
 
| Apple Icon Image
 
| [[wikipedia:Raster graphics|Raster]]
 
| [[wikipedia:Raster graphics|Raster]]
|bgcolor="#00cc00"| yes
+
| {{Yes}}
|bgcolor="red"| no
+
| {{No}}
 
|-
 
|-
 
|}
 
|}
  
===Converting icons===
+
=== Converting icons ===
If you stumble across an icon which is in a format that is not supported by the freedesktop.org standard (like ''gif'' or ''ico''), you can '''convert''' (which is part of the '''imagemagick''' package) it to a supported/recommended format, e.g.:
+
 
  $ convert <icon name>.gif <icon name>.png             /* Converts from ''gif'' to ''png'' */
+
If you stumble across an icon which is in a format that is not supported by the freedesktop.org standard (like {{ic|gif}} or {{ic|ico}}), you can use the ''convert'' tool (which is part of the {{Pkg|imagemagick}} package) to convert it to a supported/recommended format, e.g.:
If you convert from a container format like ''ico'', you will get all images that were encapsulated in the ''ico'' file in the form ''<icon name>-<number>.png''.
+
 
If you want to know the size of the image, or the number of images in a container file like ''ico'' you can use '''identify''' (also part of the '''imagemagick''' package)
+
  $ convert <icon name>.gif <icon name>.png
$ identify /usr/share/vlc/vlc48x48.ico
+
 
/usr/share/vlc/vlc48x48.ico[0] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
+
If you convert from a container format like {{ic|ico}}, you will get all images that were encapsulated in the {{ic|ico}} file in the form {{ic|<icon name>-<number>.png}}. If you want to know the size of the image, or the number of images in a container file like {{ic|ico}} you can use the ''identify'' tool (also part of the {{Pkg|imagemagick}} package):
/usr/share/vlc/vlc48x48.ico[1] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
+
 
/usr/share/vlc/vlc48x48.ico[2] ICO 128x128 128x128+0+0 8-bit DirectClass 84.3kb
+
{{hc|$ identify /usr/share/vlc/vlc48x48.ico|
/usr/share/vlc/vlc48x48.ico[3] ICO 48x48 48x48+0+0 8-bit DirectClass 84.3kb
+
/usr/share/vlc/vlc48x48.ico[0] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[4] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
+
/usr/share/vlc/vlc48x48.ico[1] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[5] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
+
/usr/share/vlc/vlc48x48.ico[2] ICO 128x128 128x128+0+0 8-bit DirectClass 84.3kb
As you can see, the example ''ico'' file, although its name might suggest a single image of size 48x48, contains no less than 6 different sizes, of which one is even greater than 48x48, namely 128x128. And to give a bit of motivation on this subject, at the point of writing this section (2008-10-27), the 128x128 size was missing in the ''vlc'' package (0.9.4-2). So the next step would be to look at the vlc PKGBUILD and check whether this icon format was not in the source package to begin with (in that case we would inform the vlc developers), or whether this icon was somehow omitted from the Arch-specific package (in that case we can file a bug report at [https://bugs.archlinux.org/ the Arch Linux bug tracker]).
+
/usr/share/vlc/vlc48x48.ico[3] ICO 48x48 48x48+0+0 8-bit DirectClass 84.3kb
(''Update:'' this bug has now been [https://bugs.archlinux.org/task/11923 fixed], so as you can see, your work will not be in vain.)
+
/usr/share/vlc/vlc48x48.ico[4] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
 +
/usr/share/vlc/vlc48x48.ico[5] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
 +
}}
 +
 
 +
As you can see, the example ''ico'' file, although its name might suggest a single image of size 48x48, contains no less than 6 different sizes, of which one is even greater than 48x48, namely 128x128.
 +
 
 +
Alternatively, you can use ''icotool'' (from {{Pkg|icoutils}}) to extract png images from ico container:
 +
$ icotool -x <icon name>.ico
 +
 
 +
For extracting images from .icns container, you can use ''icns2png'' (provided by {{Aur|libicns}}):
 +
$ icns2png -x <icon name>.icns
 +
 
 +
=== Obtaining icons ===
  
===Obtaining icons===
 
 
Although packages that already ship with a .desktop-file most certainly contain an icon or a set of icons, there is sometimes the case when a developer has not created a .desktop-file, but may ship icons, nonetheless. So a good start is to look for icons in the source package.
 
Although packages that already ship with a .desktop-file most certainly contain an icon or a set of icons, there is sometimes the case when a developer has not created a .desktop-file, but may ship icons, nonetheless. So a good start is to look for icons in the source package.
 
You can i.e. first filter for the extension with '''find''' and then use '''grep''' to filter further for certain buzzwords like the package name, "icon", "logo", etc, if there are quite a lot of images in the source package.
 
You can i.e. first filter for the extension with '''find''' and then use '''grep''' to filter further for certain buzzwords like the package name, "icon", "logo", etc, if there are quite a lot of images in the source package.
  $ find /path/to/source/package -regex ".*\.\(svg\|png\|xpm\|gif\|ico\)$"     /* this filters for common extensions */
+
  $ find /path/to/source/package -regex ".*\.\(svg\|png\|xpm\|gif\|ico\)$"
 
If the developers of an application do not include icons in their source packages, the next step would be to search on their web sites.
 
If the developers of an application do not include icons in their source packages, the next step would be to search on their web sites.
 
Some projects, like i.e. ''tvbrowser'' have an [http://enwiki.tvbrowser.org/index.php/Banners,_Logos_and_other_Promotion_Material artwork/logo page] where additional icons may be found. If a project is multi-platform, there may be the case that even if the linux/unix package does not come with an icon, the Windows package might provide one. If the project uses a [[wikipedia:Version control system|Version control system]] like CVS/SVN/etc. and you have some experience with it, you also might consider browsing it for icons.
 
Some projects, like i.e. ''tvbrowser'' have an [http://enwiki.tvbrowser.org/index.php/Banners,_Logos_and_other_Promotion_Material artwork/logo page] where additional icons may be found. If a project is multi-platform, there may be the case that even if the linux/unix package does not come with an icon, the Windows package might provide one. If the project uses a [[wikipedia:Version control system|Version control system]] like CVS/SVN/etc. and you have some experience with it, you also might consider browsing it for icons.
If everything fails, the project might simple have no icon/logo yet.
+
If everything fails, the project might simply have no icon/logo yet.
  
 
== Tools ==
 
== Tools ==
  
 
=== gendesk ===
 
=== gendesk ===
 +
{{Pkg|gendesk}} started as an Arch Linux-specific tool for generating .desktop files by fetching the needed information directly from PKGBUILD files. Now it is a general tool that takes command-line arguments.
  
{{Pkg|gendesk}} is a Arch Linux-specific tool for generating .desktop files from PKGBUILD files. Most of the information is fetched directly from the PKGBUILD.
+
Icons can be automatically downloaded from [http://openiconlibrary.sourceforge.net/ openiconlibrary], if available. (The source for icons can easily be changed in the future).
 
+
Icons are downloaded from [https://admin.fedoraproject.org/pkgdb/appicon/show/%s fedora], if available. The source for icons can easily be changed in the future.
+
  
 
==== How to use ====
 
==== How to use ====
Line 138: Line 178:
 
* Add {{Ic|gendesk}} to makedepends
 
* Add {{Ic|gendesk}} to makedepends
  
* Start the {{Ic|build()}} function with:
+
* Start the {{Ic|prepare()}} function with:
{{bc|cd "$srcdir"
+
 
gendesk $SRCDEST/PKGBUILD
+
{{bc|gendesk --pkgname "$pkgname" --pkgdesc "$pkgdesc"}}
# And then the rest}}
+
 
 +
* Alternatively, if an icon is already provided ($pkgname.png, for instance). The {{Ic|-n}} flag is for not downloading an icon or using the default icon. Example:
 +
 
 +
{{bc|gendesk -n --pkgname "$pkgname" --pkgdesc "$pkgdesc"}}
 +
 
 +
* {{Ic|$srcdir/$pkgname.desktop}}&nbsp;will be created and can be installed in the {{Ic|package()}} function with:
 +
 
 +
{{bc|install -Dm644 "$pkgname.desktop" "$pkgdir/usr/share/applications/$pkgname.desktop"}}
 +
 
 +
* The icon can be installed with:
 +
 
 +
{{bc|install -Dm644 "$pkgname.png" "$pkgdir/usr/share/pixmaps/$pkgname.png"}}
 +
 
 +
* Use {{Ic|1=--name='Program Name'}} for choosing a name for the menu entry.
 +
 
 +
* Use {{Ic|1=--exec='/opt/some_app/elf --with-ponies'}} for setting the exec field.
 +
 
 +
* See the [https://github.com/xyproto/gendesk gendesk project] for more information.
 +
 
 +
=== List or search in .desktop files ===
 +
 
 +
The {{AUR|lsdesktopf}} script is listing available ''.desktop'' files or searching in their content.
 +
 
 +
Examples
 +
$ lsdesktopf
 +
$ lsdesktopf --list
 +
$ lsdesktopf --list gtk zh_TW,zh_CN,en_GB
 +
 
 +
List MIME-types or parts of MIME-types found in ''.desktop'', and which desktop files shares same MIME-type, output is equal as in [[Default applications#Configuration of the mimeapps.list file|mimeapps.list]] for section {{ic|[Added Associations]}}.
 +
 
 +
$ lsdesktopf --gm
 +
$ lsdesktopf --gm [options]
 +
 
 +
For more options use {{ic|lsdesktopf --help}}.
 +
 
 +
=== fbrokendesktop ===
 +
 
 +
The {{AUR|fbrokendesktop}} bash script using command ''which'' to detect broken {{ic|Exec}} that points to not existing path. Without any parameters it uses preset folders in {{ic|DskPath}} array. It shows only broken ''.desktop'' with full path and filename that is missing.
 +
 
 +
Examples
 +
 
 +
$ fbrokendesktop
 +
$ fbrokendesktop /usr
 +
$ fbrokendesktop /usr/share/apps/kdm/sessions/icewm.desktop
 +
 
 +
== Tips and tricks ==
 +
 
 +
=== Hide desktop entries ===
 +
 
 +
Firstly, copy the desktop entry file in question to {{ic|~/.local/share/applications}} to avoid your changes being overwritten.
 +
 
 +
Then, to hide the entry in all environments, open the desktop entry file in a text editor and add the following line: {{ic|NoDisplay&#61;true}}.
 +
 
 +
To hide the entry in a specific desktop, add the following line to the desktop entry file: {{ic|NotShowIn&#61;''desktop-name''}}
 +
 
 +
where ''desktop-name'' can be option such as ''GNOME'', ''Xfce'', ''KDE'' etc. A desktop entry can be hidden in more than desktop at once - simply separate the desktop names with a semi-colon.
 +
 
 +
=== Autostart ===
 +
 
 +
If you use an XDG-compliant desktop environment, such as GNOME or KDE, the desktop environment will automatically start [[Desktop entries|*.desktop]] files found in the following directories:
 +
 
 +
* System-wide: {{ic|$XDG_CONFIG_DIRS/autostart/}} ({{ic|/etc/xdg/autostart/}} by default)
 +
:* GNOME also starts files found in {{ic|/usr/share/gnome/autostart/}}
 +
* User-specific: {{ic|$XDG_CONFIG_HOME/autostart/}} ({{ic|~/.config/autostart/}} by default)
 +
 
 +
Users can override system-wide {{ic|*.desktop}} files by copying them into the user-specific {{ic|~/.config/autostart/}} folder.
 +
 
 +
For a more specific description of directories used, [http://standards.freedesktop.org/autostart-spec/autostart-spec-latest.html Desktop Application Autostart Specification].
 +
 
 +
{{Note|This method is supported only by XDG-compliant desktop environments. Tools like {{AUR|dapper}}, {{pkg|dex}}, or {{AUR|fbautostart}} can be used to offer XDG autostart in unsupported desktop environments as long as some other autostart mechanism exists. Use the existing mechanism to start the xdg compliant autostart tool.}}
 +
 
 +
=== Modify environment variables ===
  
* Add {{Ic|1=_name=('Program Name')}} to the PKGBUILD to choose a name for the menu entry. There are other options available too, like {{ic|1=_exec=('someapp --with-ponies')}}.
+
Edit the {{ic|Exec}} command by appending {{ic|env}}, for example:
  
* Use {{Ic|gendesk -n}} if you wish to generate a .desktop file, but not download any icon
+
{{hc|~/.local/share/applications/abiword.desktop|2=
 +
Exec=env LANG=he_IL.UTF-8 abiword %U
 +
}}
  
* See the [https://github.com/xyproto/gendesk/blob/master/gendesk.go gendesk source] for more information. (Patches and pull requests are welcome).
+
== See also ==
  
==More resources==
+
* [[DeveloperWiki:Removal of desktop files]]
*[[Wikipedia:.desktop|desktop wikipedia article]]
+
* [[Wikipedia:.desktop|desktop wikipedia article]]
*[http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s05.html recognized desktop entry keys]
+
* [http://freedesktop.org/wiki/Howto_desktop_files information for developers]
*[http://freedesktop.org/wiki/Specifications/desktop-entry-spec freedesktop.org desktop entry specification]
+
*[http://freedesktop.org/wiki/Specifications/icon-theme-spec freedesktop.org icon theme specification]
+
*[http://freedesktop.org/wiki/Specifications/menu-spec freedesktop.org menu specification]
+
*[http://freedesktop.org/wiki/Specifications/basedir-spec freedesktop.org basedir specification]
+
*[http://freedesktop.org/wiki/Howto_desktop_files information for developers]
+

Latest revision as of 15:37, 11 September 2016

The freedesktop Desktop Entry specification provides a standard for applications to integrate into a desktop environment. Desktop entries are the configuration files that describe how an application is launched and which data it can handle. They also configure how an application appears in a menu with an icon, which is subject to the related menu specification standard.

The most common desktop entries are the .desktop and .directory files. This article explains briefly how to create useful and standard compliant desktop entries. It is mainly intended for package contributors and maintainers, but may also be useful for software developers and others.

There are roughly three types of desktop entries:

Application 
a shortcut to an application
Link 
a shortcut to a web link.
Directory 
a container of meta data of a menu entry

The following sections will roughly explain how these are created and validated.

Related to this content, and also defined in .desktop files, are MIME-type associations for data files. Default applications describes how these are configured.

Application entry

Desktop entries for applications, or .desktop files, are generally a combination of meta information resources and a shortcut of an application. These files usually reside in /usr/share/applications or /usr/local/share/applications for applications installed system-wide, or ~/.local/share/applications for user-specific applications. User entries take precedence over system entries.

File example

Following is an example of its structure with additional comments. The example is only meant to give a quick impression, and does not show how to utilize all possible entry keys. The complete list of keys can be found in the freedesktop.org specification.

[Desktop Entry]

# The type as listed above
Type=Application

# The version of the desktop entry specification to which this file complies
Version=1.0

# The name of the application
Name=jMemorize

# A comment which can/will be used as a tooltip
Comment=Flash card based learning tool

# The path to the folder in which the executable is run
Path=/opt/jmemorise

# The executable of the application.
Exec=jmemorize

# The name of the icon that will be used to display this entry
Icon=jmemorize

# Describes whether this application needs to be run in a terminal or not
Terminal=false

# Describes the categories in which this entry should be shown
Categories=Education;Languages;Java;

Key definition

All Desktop recognized desktop entries can be found on the freedesktop.org site. For example, the Type key defines three types of desktop entries: Application (type 1), Link (type 2) and Directory (type 3).

  • Version key does not stand for the version of the application, but for the version of the desktop entry specification to which this file complies.
  • Name, GenericName and Comment often contain redundant values in the form of combinations of them, like:
Name=Pidgin Internet Messenger
GenericName=Internet Messenger

or

Name=NoteCase notes manager
Comment=Notes Manager

This should be avoided, as it will only be confusing to users. The Name key should only contain the name, or maybe an abbreviation/acronym if available.

  • GenericName should state what you would generally call an application that does what this specific application offers (i.e. Firefox is a "Web Browser").
  • Comment is intended to contain any usefull additional information.

Deprecation

There are quite some keys that have become deprecated over time as the standard has matured. The best/simplest way is to use the tool desktop-file-validate which is part of the package desktop-file-utils. To validate, run

$ desktop-file-validate <your desktop file>

This will give you very verbose and useful warnings and error messages.

Icons

See also the Icon Theme Specification.

Common image formats

Here is a short overview of image formats commonly used for icons.

Support for image formats for icons as specified by the freedesktop.org standard.
Extension Full Name and/or Description Graphics Type Container Format Supported
.png Portable Network Graphics Raster No Yes
.svg(z) Scalable Vector Graphics Vector No Yes (optional)
.xpm X PixMap Raster No Yes (deprecated)
.gif Graphics Interchange Format Raster No No
.ico MS Windows Icon Format Raster Yes No
.icns Apple Icon Image Raster Yes No

Converting icons

If you stumble across an icon which is in a format that is not supported by the freedesktop.org standard (like gif or ico), you can use the convert tool (which is part of the imagemagick package) to convert it to a supported/recommended format, e.g.:

$ convert <icon name>.gif <icon name>.png

If you convert from a container format like ico, you will get all images that were encapsulated in the ico file in the form <icon name>-<number>.png. If you want to know the size of the image, or the number of images in a container file like ico you can use the identify tool (also part of the imagemagick package):

$ identify /usr/share/vlc/vlc48x48.ico
/usr/share/vlc/vlc48x48.ico[0] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[1] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[2] ICO 128x128 128x128+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[3] ICO 48x48 48x48+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[4] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[5] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb

As you can see, the example ico file, although its name might suggest a single image of size 48x48, contains no less than 6 different sizes, of which one is even greater than 48x48, namely 128x128.

Alternatively, you can use icotool (from icoutils) to extract png images from ico container:

$ icotool -x <icon name>.ico

For extracting images from .icns container, you can use icns2png (provided by libicnsAUR):

$ icns2png -x <icon name>.icns

Obtaining icons

Although packages that already ship with a .desktop-file most certainly contain an icon or a set of icons, there is sometimes the case when a developer has not created a .desktop-file, but may ship icons, nonetheless. So a good start is to look for icons in the source package. You can i.e. first filter for the extension with find and then use grep to filter further for certain buzzwords like the package name, "icon", "logo", etc, if there are quite a lot of images in the source package.

$ find /path/to/source/package -regex ".*\.\(svg\|png\|xpm\|gif\|ico\)$"

If the developers of an application do not include icons in their source packages, the next step would be to search on their web sites. Some projects, like i.e. tvbrowser have an artwork/logo page where additional icons may be found. If a project is multi-platform, there may be the case that even if the linux/unix package does not come with an icon, the Windows package might provide one. If the project uses a Version control system like CVS/SVN/etc. and you have some experience with it, you also might consider browsing it for icons. If everything fails, the project might simply have no icon/logo yet.

Tools

gendesk

gendesk started as an Arch Linux-specific tool for generating .desktop files by fetching the needed information directly from PKGBUILD files. Now it is a general tool that takes command-line arguments.

Icons can be automatically downloaded from openiconlibrary, if available. (The source for icons can easily be changed in the future).

How to use

  • Add gendesk to makedepends
  • Start the prepare() function with:
gendesk --pkgname "$pkgname" --pkgdesc "$pkgdesc"
  • Alternatively, if an icon is already provided ($pkgname.png, for instance). The -n flag is for not downloading an icon or using the default icon. Example:
gendesk -n --pkgname "$pkgname" --pkgdesc "$pkgdesc"
  • $srcdir/$pkgname.desktop will be created and can be installed in the package() function with:
install -Dm644 "$pkgname.desktop" "$pkgdir/usr/share/applications/$pkgname.desktop"
  • The icon can be installed with:
install -Dm644 "$pkgname.png" "$pkgdir/usr/share/pixmaps/$pkgname.png"
  • Use --name='Program Name' for choosing a name for the menu entry.
  • Use --exec='/opt/some_app/elf --with-ponies' for setting the exec field.

List or search in .desktop files

The lsdesktopfAUR script is listing available .desktop files or searching in their content.

Examples

$ lsdesktopf
$ lsdesktopf --list
$ lsdesktopf --list gtk zh_TW,zh_CN,en_GB

List MIME-types or parts of MIME-types found in .desktop, and which desktop files shares same MIME-type, output is equal as in mimeapps.list for section [Added Associations].

$ lsdesktopf --gm
$ lsdesktopf --gm [options]

For more options use lsdesktopf --help.

fbrokendesktop

The fbrokendesktopAUR bash script using command which to detect broken Exec that points to not existing path. Without any parameters it uses preset folders in DskPath array. It shows only broken .desktop with full path and filename that is missing.

Examples

$ fbrokendesktop
$ fbrokendesktop /usr
$ fbrokendesktop /usr/share/apps/kdm/sessions/icewm.desktop

Tips and tricks

Hide desktop entries

Firstly, copy the desktop entry file in question to ~/.local/share/applications to avoid your changes being overwritten.

Then, to hide the entry in all environments, open the desktop entry file in a text editor and add the following line: NoDisplay=true.

To hide the entry in a specific desktop, add the following line to the desktop entry file: NotShowIn=desktop-name

where desktop-name can be option such as GNOME, Xfce, KDE etc. A desktop entry can be hidden in more than desktop at once - simply separate the desktop names with a semi-colon.

Autostart

If you use an XDG-compliant desktop environment, such as GNOME or KDE, the desktop environment will automatically start *.desktop files found in the following directories:

  • System-wide: $XDG_CONFIG_DIRS/autostart/ (/etc/xdg/autostart/ by default)
  • GNOME also starts files found in /usr/share/gnome/autostart/
  • User-specific: $XDG_CONFIG_HOME/autostart/ (~/.config/autostart/ by default)

Users can override system-wide *.desktop files by copying them into the user-specific ~/.config/autostart/ folder.

For a more specific description of directories used, Desktop Application Autostart Specification.

Note: This method is supported only by XDG-compliant desktop environments. Tools like dapperAUR, dex, or fbautostartAUR can be used to offer XDG autostart in unsupported desktop environments as long as some other autostart mechanism exists. Use the existing mechanism to start the xdg compliant autostart tool.

Modify environment variables

Edit the Exec command by appending env, for example:

~/.local/share/applications/abiword.desktop
Exec=env LANG=he_IL.UTF-8 abiword %U

See also