Development/Howto/XDGMenuSystem
From Mandriva Community Wiki
Contents |
Since Mandrake 7.1, Mandriva Linux systems used Debian menu system for its packages.
Migration plan is explained here.
Starting with Mandriva Linux 2007, freedesktop.org XDG menu system standard, already implemented natively in GNOME, KDE, Rox and supported by various ISV (for instance, Codeweavers) is used for Mandriva packages.
[edit] XDG menu system in details
[edit] Files used
The menu system consists of three types of files:
- *.menu files, which define the menu structure. They are found in subdirectories from XDG_CONFIG_DIRS/menus (XDG_CONFIG_DIRS environment variable; directories list separated by a colon; default search path is ~/.config/menus and /etc/xdg/menus). The most important file is applications.menu. It defines the standard menu structure. This file is packaged in desktop-common-data package and should not be modified. Any changes from ISV should be done using additional .menu files placed in XDG_CONFIG_DIRS/menus/applications-merged.
- *.directory files, which define menu directories name and icon. They are found in subdirectories from XDG_DATA_DIRS/desktop-directories (XDG_DATA_DIRS environment variable; directories list separated by colon; default search patch is ~/.local/share/desktop-directories and /usr/share/desktop-directories).
- *.desktop files, which define menu entries. They are found in subdirectories from XDG_DATA_DIRS/applications.
[edit] Dealing with XDG menu system in packages
All packages with graphical applications should be shipped with a .desktop file. Packages that add submenus should ship with .menu and .directory files.
Packages should still have %{update_menus} and %{clean_menus} in %post and %postun scripts. Packages needing support for Mandriva Linux 2007.0 and earlier versions should still ship an menu file based on the old infrastructure.
[edit] Menu entry
Specification for .desktop file is available here.
When an application comes without a .desktop file the following should be added in %install
mkdir -p %{buildroot}%{_datadir}/applications
cat > %{buildroot}%{_datadir}/applications/mandriva-%{name}.desktop <<EOF
[Desktop Entry]
Name=Foo
Comment=Foo does special things
Exec=%{_bindir}/%{name}
Icon=%{name}
Terminal=false
Type=Application
StartupNotify=true
MimeType=foo/bar;foo2/bar2;
Categories=GNOME;GTK;AudioVideo;Audio;Video;Player;
EOF
When the application already ships a .desktop file, the spec file should add missing information in %install:
desktop-file-install \
--add-category="GTK" \
--remove-category="Qt" \
--add-mime-type="foo/bar" \
--add-only-show-in="KDE" \
--dir %{buildroot}%{_datadir}/applications %{buildroot}%{_datadir}/applications/*
Notice: option --vendor="" is not mandatory now.
If the application supports file or url as arguments, the following keys should be added to the Exec line (see here for complete list),
- if no file can be added, don't add anything
- if only one file can be added as argument : %f
- if several files can be added as argument : %F
- if one url can be added as argument : %u
- if several urls can be added as argument : %U
For Icon , neither an extension nor path should be specified as long as icons are stored in the default icon path.
If the application can manage some mimetypes, they should be added in the MimeType field, separated by semi-colon (and the list must finish with a semi-colon). Then if MimeType field is specified:
- Requires(post): desktop-file-utils and Requires(postun): desktop-file-utils should be added to the package
- %{update_desktop_database} should be added to %post
- %{clean_desktop_database} should be added to %postun
Explanations about mimetypes are available here.
If the application is not a graphical one and must be run in a terminal, the Terminal key should be set to true and the ConsoleOnly key should be added to Categories.
If the application doesn't support the startup notification mechanism (i.e. a clock cursor is being displayed until the application is displayed on screen), the StartupNotify key should be set to false.
The Categories field must be filled with an entry based on the Mandriva menu section, as listed here and should be filled with more category fields characterizing the application, using the registered keys from the standard list here. Currently, applications.menu shipped with Mandriva makes use only of Mandriva Categories. However, if you intend to place a menu entry in some new category you must supply a .menu and a .directory file and add your category of Category . Gtk applications should add a GTK key. Same for KDE applications (KDE), GNOME applications (GNOME), Qt applications (Qt), Motif applications (Motif), text-only applications (ConsoleOnly) and Java applications (Java).
For an application to appear only in one or in a list of desktop environments, the OnlyShowIn key should be added, with the possible values (separated by semi-colon): KDE, GNOME, ROX, XFCE.
[edit] Menu directory
When application needs submenu that is not in Mandriva Categories then the following should be added in %install:
mkdir -p %{buildroot}/etc/xdg/menus/applications-merged
cat > %{buildroot}/etc/xdg/menus/applications-merged/%{name}.menu << EOF
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">
<Menu>
<Name>Mandriva Linux</Name>
<Menu>
<Name>More Applications</Name>
<Menu>
<Name>System</Name>
<Menu>
<Name>Foo</Name>
<Directory>mandriva-%{name}.directory</Directory>
<Include>
<Category>%{title} or something else</Category>
</Include>
</Menu>
</Menu>
</Menu>
</Menu>
EOF
mkdir -p %{buildroot}%{_datadir}/desktop-directories
cat >
%{buildroot}%{_datadir}/desktop-directories/mandriva-%{name}.directory <<
EOF
[Desktop Entry]
Encoding=UTF-8
Name=%{title}
Icon=%{name}
Type=Directory
EOF
This way the application will add its submenu to More Applications->System.
[edit] Desktop file validation
Since a recent version of xdg tools desktop files have to follow some more standardization. The new xdg system introduced in 2008.0 checks the file encoding which must be UTF8 and the presence of an extension after the icon name (which must NOT be present).
You will have build error when desktop-file-install is invoked on a non-compliant desktop file.
To remove an icon extension :
- sed -i -e 's/^Icon=%{name}.png$/Icon=%{name}/g' %{buildroot}%{_datadir}/applications/*
