View source for XDG menu system policy

[[Category:Packaging Policies]]
{{introduction|ROSA Linux uses [http://standards.freedesktop.org/menu-spec/latest/ standard XDG menu system], already implemented natively in GNOME, KDE, Rox and supported by various ISV.}}

== XDG menu system in details ==
=== Files used ===
The menu system consists of three types of files:

* *.menu files, which define the menu structure. They are found in subdirectories from {{file|XDG_CONFIG_DIRS/menus}} (XDG_CONFIG_DIRS  environment variable; directories list separated by a colon;  default search path is {{file|~/.config/menus}} and {{file|/etc/xdg/menus}}). The most important file is {{file|applications.menu}}. It defines the standard menu structure. This file is packaged in {{pkg|desktop-common-data}} package and should not be modified. Any changes from ISV should be done using additional .menu files placed in {{file|XDG_CONFIG_DIRS/menus/applications-merged}}.

* *.directory files, which define menu directories name and icon. They are found in subdirectories from {{file|XDG_DATA_DIRS/desktop-directories}} (XDG_DATA_DIRS environment variable; directories list separated by colon; default search patch is {{file|~/.local/share/desktop-directories}} and {{file|/usr/share/desktop-directories}}). 

* *.desktop files, which define menu entries. They are found in subdirectories from {{file|XDG_DATA_DIRS/applications}}.


== 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.

=== Menu entry ===
Specification for .desktop file is available [http://standards.freedesktop.org/desktop-entry-spec/latest/ here].

When an application comes without a .desktop file the following should be added in <tt>%install</tt>

<pre>
mkdir -p %{buildroot}%{_datadir}/applications
cat > %{buildroot}%{_datadir}/applications/rosa-%{name}.desktop <<EOF
[Desktop Entry]
Name=Foo
GenericName=Video player
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
</pre>

When the application already ships a .desktop file, the spec file should add missing information in <tt>%install</tt>:

<pre>
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/*
</pre>

Notice: option --vendor="" is not mandatory.

If the application supports file or url as arguments, the following keys should be added to the <tt>Exec</tt> line (see [http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables here] for complete list),

* if no file can be added, don't add anything
* if only one file can be added as argument : <tt>%f</tt>
* if several files can be added as argument : <tt>%F</tt>
* if one url can be added as argument : <tt>%u</tt>
* if several urls can be added as argument : <tt>%U</tt>

For  <tt>Icon</tt> , 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 <tt>MimeType</tt> field, separated by semi-colon (and the list must finish with a semi-colon). 

Explanations about mimetypes are available [[Development/Howto/Mimetypes|here]].

If the application is not a graphical one and must be run in a terminal, the <tt>Terminal</tt> key should be set to <tt>true</tt> and the <tt>ConsoleOnly</tt> key should be added to <tt>Categories</tt>.

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 <tt>StartupNotify</tt> key should be set to false.

The <tt>Categories</tt> field must be filled with an entry based on the ROSA menu section, as listed [[#ROSA_categories|here]] and should be filled with more category fields characterizing the application, using the registered keys from the standard list [http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html#category-registry here]. Currently, {{file|applications.menu}} shipped with ROSA makes use only of [[#ROSA_categories|ROSA 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 <tt>Category</tt> . Gtk applications should add a <tt>GTK</tt> key. Same for KDE applications (<tt>KDE</tt>), GNOME applications (<tt>GNOME</tt>), Qt applications (<tt>Qt</tt>), Motif applications (<tt>Motif</tt>), text-only applications (<tt>ConsoleOnly</tt>) and Java applications (<tt>Java</tt>). 

For an application to appear only in one or in a list of desktop environments, the <tt>OnlyShowIn</tt> key should be added, with the possible values (separated by semi-colon): KDE, GNOME, ROX, XFCE.

=== Menu directory ===
When application needs submenu that is not in [[#ROSA_categories|ROSA Categories]] then the following should be added in <tt>%install</tt>:

<pre>
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>ROSA Linux</Name>
    <Menu>
        <Name>More Applications</Name>
        <Menu>
            <Name>System</Name>
            <Menu>
                <Name>Foo</Name>
                <Directory>rosa-%{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/rosa-%{name}.directory <<
EOF
[Desktop Entry]
Encoding=UTF-8
Name=%{title}
Icon=%{name}
Type=Directory
EOF
</pre>

This way the application will add its submenu to {{menu|More Applications->System}}.

=== Desktop file validation ===
Since a recent version of xdg tools desktop files have to follow some more standardization.
The XDG system used in ROSA checks the file encoding which must be UTF-8 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 :

* <tt> sed -i -e 's/^Icon=%{name}.png$/Icon=%{name}/g' %{buildroot}%{_datadir}/applications/*</tt>

<hr>

{{message|This Policy is based on the [http://wiki.mandriva.com/en/XDG_menu_system_policy Mandriva XDG menu system policy].}}