Merge pull request #324 from dbrgn/desktop-file-exec-docs

Fix and improve docs about Exec line in desktop files

docs/freedesktop-quick-reference.rst

@@ -37,25 +37,61 @@ command, *Type* and *Icon*:
 
     [Desktop Entry]
     Name=Gnome Dictionary
-    Exec=org.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/``, you should use
-``desktop-file-validate`` to check your file for errors before including
-it.
+placed in ``/app/share/applications/`` within your app.
 
 Example:
 
 ::
 
     /app/share/applications/org.gnome.Dictionary.desktop
 
-You can find more information
-`here <https://wiki.archlinux.org/index.php/desktop_entries>`__. If
-interested, you can read also the full spec
-`here <https://standards.freedesktop.org/desktop-entry-spec/latest/>`__.
+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
+<https://wiki.archlinux.org/index.php/desktop_entries>`__. If
+interested, you can read also the full spec `here
+<https://standards.freedesktop.org/desktop-entry-spec/latest/>`__.
 
 Appdata files
 -------------