diff --git a/docs/conventions.rst b/docs/conventions.rst index 959eb492..818d9bc8 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -68,19 +68,19 @@ For some practical examples of bad IDs domain. Instead you should use ``io.github`` or ``io.gitlab`` as shown above. -AppData files -````````````` -AppData files provide metadata about applications, which is +MetaInfo files +`````````````` +MetaInfo files provide metadata about applications, which is used by application stores (such as Flathub, GNOME Software and KDE Discover). The `Freedesktop AppStream specification `_ provides a complete -reference for providing AppData. You can use the online +reference for providing MetaInfo. You can use the online `AppStream MetaInfo Creator `_ to generate a basic file. -AppData files should be named with the application ID and the ``.metainfo.xml`` +MetaInfo files should be named with the application ID and the ``.metainfo.xml`` file extension, and should be placed in ``/app/share/metainfo/``. For example:: /app/share/metainfo/org.gnome.Dictionary.metainfo.xml @@ -89,7 +89,7 @@ A legacy convention of having the ``.appdata.xml`` installed in ``/app/share/app is also accepted as well, and ``flatpak-builder`` will check either directory with either extension. -The ``appstream-util validate-relax`` command can be used to check AppData +The ``appstreamcli validate --explain`` command can be used to check MetaInfo files for errors. Application icons @@ -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,14 +147,31 @@ 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=GNOME;GTK;Office;Dictionary; + Categories=Office;Dictionary; 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/first-build.rst b/docs/first-build.rst index fd78be6f..98a0c77f 100644 --- a/docs/first-build.rst +++ b/docs/first-build.rst @@ -107,7 +107,8 @@ build like this is very fast. In order for your application to show up in application stores while testing with a local repository, you might have to run ``flatpak build-update-repo repo``. -For more information how to publish to application stores see `Appdata files `_. + +For more information how to publish to application stores see `MetaInfo files `_. 7. Install the app ------------------ 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/hosting-a-repository.rst b/docs/hosting-a-repository.rst index 8bc16515..5b451eac 100644 --- a/docs/hosting-a-repository.rst +++ b/docs/hosting-a-repository.rst @@ -92,7 +92,7 @@ The instructions will use Gitlab.com. .. code-block:: yaml variables: - # Application id of the app, should be same as id used in flatpak manifest and appdata + # Application id of the app, should be same as id used in flatpak manifest and MetaInfo APP_ID: tld.vendor.app_name # Location of the flatpak manifest, root of git repository MANIFEST_PATH: $CI_PROJECT_DIR/${APP_ID}.yaml diff --git a/docs/manifests.rst b/docs/manifests.rst index 1e6ebb8b..2fbd0cb0 100644 --- a/docs/manifests.rst +++ b/docs/manifests.rst @@ -56,7 +56,7 @@ the manifest: - ``rename-icon`` - rename the application icon - ``rename-desktop-file`` - rename the ``.desktop`` filename -- ``rename-appdata-file`` - rename the AppData file +- ``rename-appdata-file`` - rename the MetaInfo file Each of these properties accepts the name of the source file to be renamed. ``flatpak-builder`` then automatically renames the file to match 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