[PATCH] manuals: document "mime-xdg" class and MIME_XDG_PACKAGES

michael.opdenacker
2022-10-31T13:21:31Z

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
.../migration-guides/migration-3.1.rst | 2 +-
documentation/ref-manual/classes.rst | 21 +++++++++++++++++++
documentation/ref-manual/qa-checks.rst | 8 +++----
documentation/ref-manual/variables.rst | 7 +++++++
4 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/documentation/migration-guides/migration-3.1.rst b/documentation/migration-guides/migration-3.1.rst
index a6106eefae..7fdd3b88a6 100644
--- a/documentation/migration-guides/migration-3.1.rst
+++ b/documentation/migration-guides/migration-3.1.rst
@@ -238,7 +238,7 @@ Warnings will now be shown at :ref:`ref-tasks-package_qa` time in the following
circumstances:

- A recipe installs ``.desktop`` files containing ``MimeType`` keys but
- does not inherit the new ``mime-xdg`` class
+ does not inherit the new :ref:`mime-xdg <ref-classes-mime-xdg>` class

- A recipe installs ``.xml`` files into ``${datadir}/mime/packages``
but does not inherit the :ref:`mime <ref-classes-mime>` class
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 3b33783c58..afe483e2a9 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1586,6 +1586,27 @@ The :ref:`mime <ref-classes-mime>` class generates the proper post-install and p
These scriptlets call ``update-mime-database`` to add the MIME types to
the shared database.

+.. _ref-classes-mime-xdg:
+
+``mime-xdg.bbclass``
+====================
+
+The :ref:`mime-xdg <ref-classes-mime-xdg>` class generates the proper
+post-install and post-remove (postinst/postrm) scriptlets for packages
+that install ``.desktop`` files containing ``MimeType`` entries.
+These scriptlets call ``update-desktop-database`` to add the MIME types
+to the database of MIME types handled by desktop files.
+
+Thanks to this class, when users open a file through a file browser
+on recently created images, they don't have to choose the application
+to open the file from the pool of all known applications, even the ones
+that cannot open the selected file.
+
+If you have recipes installing their ``.desktop`` files as absolute
+symbolic links, the detection of such files cannot be done by the current
+implementation of this class. In this case, you have to add the corresponding
+package names to the :term:`MIME_XDG_PACKAGES` variable.
+
.. _ref-classes-mirrors:

``mirrors.bbclass``
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index fb31dc16f9..3947dcfc17 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -590,10 +590,10 @@ Errors and Warnings
- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]``

The specified package contains a .desktop file with a 'MimeType' key
- present, but does not inherit the mime-xdg class that is required in
- order for that to be activated. Either add ``inherit mime`` to the
- recipe or remove the files at the :ref:`ref-tasks-install` step if they are not
- needed.
+ present, but does not inherit the :ref:`mime-xdg <ref-classes-mime-xdg>`
+ class that is required in order for that to be activated. Either add
+ ``inherit mime`` to the recipe or remove the files at the
+ :ref:`ref-tasks-install` step if they are not needed.

.. _qa-check-src-uri-bad:
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index dc6eccb314..4150464161 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4894,6 +4894,13 @@ system and gives an overview of their function and contents.
The revision currently checked out for the OpenEmbedded-Core layer (path
determined by :term:`COREBASE`).

+ :term:`MIME_XDG_PACKAGES`
+ The current implementation of the :ref:`mime-xdg <ref-classes-mime-xdg>`
+ class cannot detect ``.desktop`` files installed through absolute
+ symbolic links. Use this setting to make the class create post-install
+ and post-remove scripts for these packages anyway, to invoke the
+ ``update-destop-database`` command.
+
:term:`MIRRORS`
Specifies additional paths from which the OpenEmbedded build system
gets source code. When the build system searches for source code, it
--
2.34.1