Archive:PackagingDrafts/DesktopFiles

This is just a draft

Changelog

0.1: define "vendor_id", including use of applications/subdir
0.2: simplify vendor_id usage options: upstream or fedora.
0.3: drop --add-category=Application;X-Fedora
Ratified, updated Guidelines
0.4: d-f-i usage examples, reference fdo specs
0.5: d-f-i usage mandatory (again)

Existing Guideline

Desktop files

If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Many applications will come with their own .desktop file, but if not, just make your own, and include it as a Source3: %{name}.desktop.

Here are the contents of a sample .desktop file (comical.desktop):

[Desktop Entry] 
Encoding=UTF-8
Name=Comical
GenericName=Comic Archive Reader
Comment=Open .cbr & .cbz files
Exec=comical
Icon=comical.png
Terminal=false
Type=Application
Categories=Graphics;
Version=0.9.4

Also remember that it is not simply enough to just include the .desktop file in the package, you need to run desktop-file-install in %install (and have BuildRequires: desktop-file-utils). Here are some examples of desktop-file-install usage:

desktop-file-install --vendor="<vendor_id>"                     \
--dir=${RPM_BUILD_ROOT}%{_datadir}/applications         \
%{SOURCE3}

desktop-file-install --vendor=""                                 \
--dir=%{buildroot}%{_datadir}/applications/<vendor_id>   \
%{buildroot}/%{_datadir}/applications/<vendor_id>/foo.desktop

• If upstream uses <vendor_id>, leave it intact, otherwise use fedora as <vendor_id>.

• It is important that vendor_id stay constant for the life of a package.

This is mostly for the sake of menu-editing (which bases off of .desktop file/path names).

Proposed Guideline

Motivations for updating the existing guideline:

• reference desktop-entry-spec, including adding a MUST to comply with it.
• make d-f-i usage explictly mandatory, for safety, spec compliance, etc.
• update examples:
• mention --add-category/--remove-category
• modify an already-installed .desktop file (e.g. moving it from %_datadir/applnk/<foo>/ to %{_datadir}/applications )

Desktop files

If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Installed .desktop files MUST follow the [desktop-entry-spec , paying particular attention to validating correct usage of Name, GenericName, [Categories , [StartupNotify entries.

.desktop file creation

If the package doesn't already include and install its own .desktop file, you need to make your own, and include it as a Source: (e.g. Source3: %{name}.desktop). Here are the contents of a sample .desktop file (comical.desktop):

[Desktop Entry] 
Encoding=UTF-8
Name=Comical
GenericName=Comic Archive Reader
Comment=Open .cbr & .cbz files
Exec=comical
Icon=comical.png
Terminal=false
Type=Application
Categories=Graphics;

desktop-file-install usage

It is not simply enough to just include the .desktop file in the package, one MUST run desktop-file-install in %install (and have BuildRequires: desktop-file-utils), to help ensure .desktop file safety and spec-compliance. Here are some examples of desktop-file-install usage:

desktop-file-install --vendor="<vendor_id>"               \
--dir=${RPM_BUILD_ROOT}%{_datadir}/applications         \
%{SOURCE3}

desktop-file-install --vendor="<vendor_id>"                \
--add-category="Multimedia"                              \
--delete-original                                        \
--dir=%{buildroot}%{_datadir}/applications               \
%{buildroot}/%{_datadir}/applnk/Multimedia/foo.desktop

desktop-file-install --vendor=""                           \
--remove-category="Science"                              \
--dir=%{buildroot}%{_datadir}/applications/<vendor_id>   \
%{buildroot}/%{_datadir}/applications/<vendor_id>/foo.desktop

• If upstream uses <vendor_id>, leave it intact, otherwise use fedora as <vendor_id>.
• It is important that vendor_id stay constant for the life of a package.

This is mostly for the sake of menu-editing (which bases off of .desktop file/path names).