Freedesktop quick reference¶
In order to ensure interoperability, flatpak adheres strictly to a number of freedesktop standards and practices. This page describes the basic conventions that should be followed when building a flatpak app.
Icons¶
Application icons can be in either png or svg format, must use the
application’s appid as a prefix and be placed in
/app/share/icons/hicolor/$size/apps/
Example:
/app/share/icons/hicolor/128x128/apps/org.gnome.Dictionary.png
If interested, you can read the full spec here
Desktop files¶
Desktop files are used by desktop environments in order to identify and display available applications to the user, they contain information about how to launch the application, its icon and categories among others.
A minimal desktop file needs at least the application’s Name, Exec command, Type and Icon:
[Desktop Entry]
Name=Gnome Dictionary
Exec=gnome-dictionary --database=dictionary.db
Type=Application
Icon=org.gnome.Dictionary
Your desktop file should be prefixed with your application’s appid and
placed in /app/share/applications/
within your app.
Example:
/app/share/applications/org.gnome.Dictionary.desktop
It’s recommended to use desktop-file-validate
to check your file
for errors before including it.
A special note about the Exec
line: When installing an app, Flatpak will
automatically rewrite the included .desktop
file so that the app will be
started through Flatpak. The rewritten desktop file is then exported to a path
such as exports/share/applications/org.gnome.Dictionary.desktop
under your
Flatpak installation directory (usually /var/lib/flatpak/
or
~/.local/share/flatpak/
). In the case of org.gnome.Dictionary.desktop
,
the rewritten Exec
line looks like this:
Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=gnome-dictionary org.gnome.Dictionary --database=dictionary.db
The command from the original desktop file will be part of the
--command
argument to Flatpak and arguments will be passed through.
This means that in most cases, it should match the value of the
command:
line in your app’s manifest.
If you want the --command
argument to be omitted from the flatpak
run
command in the generated desktop file, you can leave the Exec
value in the source desktop file empty:
[Desktop Entry]
Name=Gnome Dictionary
Exec=
Type=Application
Icon=org.gnome.Dictionary
This way, the generated Exec
line looks like this:
Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 org.gnome.Dictionary
Note
With Flatpak ≤ 1.12.7, a warning may be shown when exporting a build with an empty Exec= line to a repository:
(flatpak build-export:189863): GLib-CRITICAL **: 22:15:27.398: g_path_is_absolute: assertion 'file_name != NULL' failed
This warning can be ignored.
You can find more general information about desktop files here. If interested, you can read also the full spec here.
Appdata files¶
Appdata files are used by application stores (e.g. KDE Discover, GNOME Software) in order to display metadata about your application, such as a description, screenshots, changelogs when updates are available, and other miscellaneous things.
Your Appdata file should be prefixed with your application’s appid and
placed in /app/share/metainfo/
. You should also use
appstream-util validate-relax
to check your file for errors before
including it.
Example:
/app/share/metainfo/org.gnome.Dictionary.appdata.xml
If interested, you can read the full spec here.