Archive:PackagingDrafts/DesktopFiles

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

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  in   (and have  ). Here are some examples of desktop-file-install usage:

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

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


 * If upstream uses , leave it intact, otherwise use fedora as .

This is mostly for the sake of menu-editing (which bases off of .desktop file/path names).
 * It is important that vendor_id stay constant for the life of a package.

= 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/ / 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. ).  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  in   (and have  ), to help ensure .desktop file safety and spec-compliance. Here are some examples of desktop-file-install usage:

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

desktop-file-install --vendor=""               \ --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/  \ %{buildroot}/%{_datadir}/applications//foo.desktop

This is mostly for the sake of menu-editing (which bases off of .desktop file/path names).
 * If upstream uses , leave it intact, otherwise use fedora as <vendor_id>.
 * It is important that vendor_id stay constant for the life of a package.