DesktopFiles

Revision 58 as of 2007-05-10 14:00:28

Clear message

In order to ensure that the menus are properly populated, and that software is easily installable with Add/Remove Packages, each package should contain a .desktop file. As a matter of policy, .desktop files should only be present for GUI interfaces: software intended to be used from the command-line should not provide such an interface.

.desktop files may be included in packages in two ways, either as part of the upstream distribution, or as part of the distribution packaging. Including the .desktop file in the upstream distribution is vastly preferred, as this allows for apporpriate translation of the .desktop file. If it cannot be included upstream, the .desktop file should be stored in the debian/ directory.

.desktop File Inclusion Criteria

  1. The package must provide a binary with a GUI interface
  2. The binary must be typically executed with constant arguments
  3. Users would expect to launch the program from the menu

Packaging Notes

  • In debian/control, if cdbs is not used, Build-Depend on debhelper (>= 4.2.21).

  • In debian/rules If cdbs's gnome.mk is not used, call dh_desktop in binary*

  • ensure that .desktop files are installed or moved to /usr/share/applications/<binary>.desktop

  • ensure that icon files are installed or moved to /usr/share/pixmaps/

Icons

  • Provide an 32x32 pixel XPM icon for use by the Debian menus
  • Optionally provide a 48x48 pixel PNG icon for use by freedesktop.org menus (the Debian icon will be used if this is unavailable)
  • If neither format is available, many formats can be converted as follows:
  • Get a base icon (clip of package graphic, .ico file, from scratch, etc.)
  • Crop / resize to 32x32 pixels

  • run convert editedicon.ico <package>.xpm (requires imagemagick)

  • if convert generated multiple images, select one (and name correctly)

Desktop Files

  • Check the spec at http://standards.freedesktop.org/desktop-entry-spec/latest/

  • Avoid Absolute pathnames in .desktop files
  • Do not include a file type extension in Icon=
  • Ensure that Categories= includes at least one Registered Category
  • Add any other applicable Additional Categories
  • Check with desktop-file-validate to ensure everything is correct

Workflow

  • Find a package without a .desktop file
  • Verify that the package is not listed below as not needing a .desktop file
  • Verify there is no .desktop file in the latest development version
  • If no .desktop file is needed, add the package to the list below
  • If a .desktop is needed:
  • Check to see if there is a .desktop in the upstream or Debian bug tracker
  • Create the necessary .desktop / icon if necessary
  • Open a wishlist bug in the package reporting the missing .desktop file
  • Attach the .desktop file and icon to the bug (optionally a patch for both)
  • Link the bug to the Debian BTS (create a BTS bug if required)
  • Tag the bug with "desktop-file"

Simple Creation techniques

  • In GNOME: use Nautilus' "Create Launcher" to create a template file

  • In KDE: <do something nifty>

  • Scripted: Some of this can be automated. Please check the results of the automation prior to submission. Most importantly, please ensure that any useful additional categories are included. 

#
# generate-desktop.bash
#
# Copyright 2005,2006 Emmet Hikory <emmet.hikory@gmail.com>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
#
#
# This script will search for debian menu entries containing icons,
# and either print the name of an oddly located .desktop file, or
# modify the menu-xdg generated file to match the freedesktop
# categories for inclusion the relevant package.
#
# Please be sure to review anything reported in the output.  If there
# is nothing odd, there should be no output.
#
# Before running this, the menu and menu-xdg packages must be installed
# It is probably also a good idea to update the locate database
#
# Please note that this only works for installed packages

XDGHOME=/var/lib/menu-xdg/applications/menu-xdg/

for MENUDIR in /usr/lib/menu /usr/share/menu
do

for i in `ls $MENUDIR`
do test -e $i.desktop ||
 ! dpkg -S $i.desktop > /dev/null 2>&1 &&
   grep icon $MENUDIR/$i > /dev/null &&
   test -e $XDGHOME/*$i.desktop &&
 ! (locate $i.desktop | grep -v Debian) &&
   cat $XDGHOME/*$i.desktop |
   sed '/Icon=/\/usr\/share\/pixmaps\/[^\/]*\.png/s/\/usr\/share\/pixmaps\///' |
   sed '/Databases/s/X-Debian-Apps-Databases/Database:/' |
   sed '/Editors/s/X-Debian-Apps-Editors/TextEditor;/' |
   sed '/Education/s/X-Debian-Apps-Education/Education;/' |
   sed '/Emulators/s/X-Debian-Apps-Emulators/Emulator;/' |
   sed '/Graphics/s/X-Debian-Apps-Graphics/Graphics;/' |
   sed '/Math/s/X-Debian-Apps-Math/Math;/' |
   sed '/Net/s/X-Debian-Apps-Net/Network;/' |
   sed '/Programming/s/X-Debian-Apps-Programming/Development;/' |
   sed '/Science/s/X-Debian-Apps-Science/Science;/' |
   sed '/Shells/s/X-Debian-Apps-Shells/Shell;/' |
   sed '/Sound/s/X-Debian-Apps-Sound/AudioVideo;Audio;/' |
   sed '/System/s/X-Debian-Apps-System/System;/' |
   sed '/Text/s/X-Debian-Apps-Text/Utility;/' |
   sed '/Tools/s/X-Debian-Apps-Tools/Utility;/' |
   sed '/Viewers/s/X-Debian-Apps-Viewers/Viewer;/' |
   sed '/Adventure/s/X-Debian-Games-Adventure/Game;AdventureGame;/' |
   sed '/Arcade/s/X-Debian-Games-Arcade/Game;ArcadeGame;/' |
   sed '/Board/s/X-Debian-Games-Board/Game;BoardGame;/' |
   sed '/Card/s/X-Debian-Games-Card/Game;CardGame;/' |
   sed '/Puzzles/s/X-Debian-Games-Puzzles/Game;LogicGame;/' |
   sed '/Simulation/s/X-Debian-Games-Simulation/Game;Simulation;/' |   sed '/Sports/s/X-Debian-Games-Sports/Game;SportsGame;/' |
   sed '/Tetris/s/X-Debian-Games-Tetris/Game;BlocksGame;/' |
   cat > $i.desktop
   test -e $i.desktop &&
   grep Categories=X-Debian $i.desktop > /dev/null &&
   echo $i.desktop needs manual Category assignment
done

done

Shell snippets for common issues

  • Using an absolute path for an icon: 

grep -E "^Icon=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate
  • Using an absolute path for a binary: 

grep -E "^Exec=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate
  • .desktop file fails validation 

for i in /usr/share/applications; do desktop-file-validate $i >> /dev/null || echo $i; done | xargs dlocate

Finding candidates for .desktop files

  • When looking for a program that needs a .desktop file, please consider using the following: 

#
# Copyright 2007 Steven Kowalik <stevenk@ubuntu.com>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

use strict;
my %menu_pkgs;
my %desktop_pkgs;
my $seen_file = 0;
foreach (<>) {
  if (!$seen_file and /^FILE/) {
    $seen_file = 1;
    next;
  }
  next unless $seen_file;
  next unless m&(usr/(share|lib)/menu|\.desktop)&;
  my @line = split(' ');
  my @pkgs = split(/,/, @line[1]);
  if ($1 eq ".desktop") {
    $desktop_pkgs{$_} = 0 foreach @pkgs;
  } elsif ($1 eq "usr/share/menu" or $1 eq "usr/lib/menu") {
    $menu_pkgs{$_} = 0 foreach @pkgs;
  }
}

foreach (keys(%menu_pkgs)) {
  print "$_\n" if !defined($desktop_pkgs{$_});
}

(Binary) Packages that do not require a .desktop file

Please only add files below if they might appear to require .desktop files at first pass. Many libraries, etc. obviously do not require them (although there are exceptions)

Admin

aptitude apt-spy bacula-console bastille battery-stats chrony configure-debian dbishell deborphan desktop-profiles hotswap-text iptstate menu partimage recover sysvconfig whowatch

Base

tasksel

Devel

autoproject cmake curves goo gprolog pydb smarteiffel

Doc

apt-howto-common bible-kjv dhelp doc-linux-ja-html dpkg-www dwww flex-old-doc man2html med-doc newbiedoc pinfo selflinux verse

Editors

bvi cream ee elvis-common emacs21-nox fte-console fte-docs geresh hexedit jed joe jove le levee ne ng-common yudit zile

Games

asciijump bb freeciv-server nethack-common nethack-console

HamRadio

ax25-apps cwcp

Intepreters

bigloo bwbasic erlang hugs irb1.6 irb1.8 irb1.9 pike7.2 pike7.4-core pike7.6-core spidermonkey-bin swi-prolog

LibDevel

libjackasyn0

Mail

elmo etpan-ng fetchmailconf sendemail

Math

mathomatic mathomatic-primes octave2.1

Net

nap ncftp ncftp2 snownews tin

Science

blast2 boxshade felt loki ncbi-tools-bin therion

Shells

csh ksh

Sound

alsaplayer-text aumix moc mp3blaster radio rexima

Text

catdoc

Utils

ncmpc

Web

links lynx-cur

X11

aewm aewm++ evilwm fluxbox flwm fvwm fvwm1 fvwm95 fvwm-gnome icewm icewm-experimental icewm-lite lwm pwm qvwm ratpoison sapphire sawfish uwm vtwm w9wm waimea wm2 wmaker