diff --git a/docs/conventions.rst b/docs/conventions.rst index b771cd32..818d9bc8 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -116,6 +116,16 @@ icons are of size ``scalable``:: /app/share/icons/hicolor/scalable/apps/org.gnome.Dictionary.svg +Flatpak will export the following icon name patterns: +``$FLATPAK_ID, $FLATPAK_ID.foo, $FLATPAK_ID-foo``. They may end with an +extension suffix like ``.png, .svg``. Exported icons can be found in the +``icons`` subfolder of ``$HOME/.local/share/flatpak/exports/share`` or +``/var/lib/flatpak/exports/share`` depending on system or user install. + +The distribution usually appends those paths to ``$XDG_DATA_DIRS`` on +host when installing the ``flatpak`` package. Unless an icon is exported +by Flatpak, host applications cannot access it. + Desktop files ````````````` @@ -137,7 +147,7 @@ A minimal desktop file should contain at least the application's *name*, [Desktop Entry] Name=Gnome Dictionary - Exec=org.gnome.Dictionary + Exec=gnome-dictionary Type=Application Icon=org.gnome.Dictionary Categories=Office;Dictionary; @@ -145,6 +155,23 @@ A minimal desktop file should contain at least the application's *name*, The ``desktop-file-validate`` command can be used to check for errors in desktop files. +The ``Exec`` key of the desktop files is rewritten by Flatpak when installing +an app. The original value of the key becomes the value of the ``--command`` +argument like so:: + + Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=gnome-dictionary org.gnome.Dictionary + +Flatpak will export the following desktop filename patterns: +``$FLATPAK_ID.desktop, $FLATPAK_ID.foo.desktop, $FLATPAK_ID-foo.desktop``. +Exported desktop files can be found in the ``applications`` subfolder of +``$HOME/.local/share/flatpak/exports/share`` or +``/var/lib/flatpak/exports/share`` depending on system or +user install. + +The distribution usually appends those paths to ``$XDG_DATA_DIRS`` on +host when installing the ``flatpak`` package. Unless a desktop file is +exported by Flatpak, host applications cannot access it. + Exporting through extra-data ---------------------------- diff --git a/docs/freedesktop-quick-reference.rst b/docs/freedesktop-quick-reference.rst deleted file mode 100644 index 4692d347..00000000 --- a/docs/freedesktop-quick-reference.rst +++ /dev/null @@ -1,116 +0,0 @@ -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 `__. diff --git a/docs/reference.rst b/docs/reference.rst index 054184a9..82ce8ccd 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -10,7 +10,6 @@ Reference documentation for flatpak, flatpak-builder and libflatpak. flatpak-builder-command-reference available-runtimes sandbox-permissions-reference - freedesktop-quick-reference under-the-hood libflatpak-api-reference portal-api-reference