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