runtime: Improve the runtime section

bbhtt · bbhtt · commit af07209179c9 · 2024-12-01T08:09:26.000+05:30
- Add support policy documentation
- Add ways to check available software in a runtime
- Remove IDs for runtimes
- Remove list of libraries. These get outdated too often
diff --git a/docs/available-runtimes.rst b/docs/available-runtimes.rst
@@ -2,156 +2,147 @@ Available Runtimes
 ==================
 
 This page provides information about available Flatpak runtimes. It is
-primarily intended as information for application developers and distributors.
+primarily intended as information for application developers and
+distributors.
 
 There are currently three main runtimes available: Freedesktop, GNOME and
-KDE. These are all hosted on `Flathub <https://flathub.org/>`_. Each runtime
-comes with the corresponding SDK for building, and extensions for specific uses.
-
-What is mentioned here is just a high level look at the contents. To have up
-to date information simply install the runtime and open a shell inside of it
-(``flatpak run org.freedesktop.Sdk//23.08``) from there you can look around or
-use tools like ``pkg-config --list-all``. In the runtime shell you can also
-inspect ``/usr/manifest.json``, which lists the sources used to build it.
+KDE all of which are hosted on `Flathub <https://flathub.org/>`_. Each
+runtime comes with a parent SDK for building, a Docs, a Debug and a
+Locale extension to provide documentation, debug symbols and localisation
+support, respectively and other extensions or extension points for
+specific uses.
 
 Freedesktop
 -----------
 
-The Freedesktop runtime is the standard runtime that can be used for any
-application and contains a set of essential libraries and services, including
-D-Bus, GLib, Gtk3, PulseAudio, X11 and Wayland.
+The `Freedesktop runtime <https://gitlab.com/freedesktop-sdk/freedesktop-sdk/>`_
+is the standard runtime that can be used for any application. It
+contains a set of essential libraries, provides the graphics and the
+toolchain stack and forms the base of the GNOME and KDE runtimes.
+
+It also provides a base set of extensions and extension points used
+by other runtimes and applications. See
+:ref:`extension:Extensions or extension points defined by runtime` for
+more details.
 
-The Freedesktop runtime is maintained `here
-<https://gitlab.com/freedesktop-sdk/freedesktop-sdk/>`__ and has a website
-`here <https://freedesktop-sdk.io/>`__.
+A given branch of the Freedesktop runtime has a 2 year support period
+after which they are declared EOL. A new major version is published on
+August of every year. The release schedule can be found on `Gitlab <https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/wikis/Releases>`_
+and announcements of new major version releases are made on `Flathub Discourse <https://discourse.flathub.org/c/announcements/6>`_.
 
-Available Freedesktop runtimes:
+The Freedesktop platform (``org.freedesktop.Platform`` and
+``org.freedesktop.Sdk``) provides strict ABI/API stability in a
+major version.
 
 ====================================================== =====================================
 ID                                                     Description
 ====================================================== =====================================
 org.freedesktop.Platform                               Runtime
 org.freedesktop.Sdk                                    SDK
-====================================================== =====================================
-
-The following runtime extensions are available:
-
-====================================================== =====================================
-ID                                                     Description
-====================================================== =====================================
 org.freedesktop.Platform.Locale                        Runtime translations (extension)
-org.freedesktop.Platform.VAAPI.Intel{,.i386}           Intel vaapi drivers (extension)
-org.freedesktop.Platform.ffmpeg-full                   All ffmpeg codecs (extension)
-org.freedesktop.Platform.Compat.{architecture}         32 bits compatible extension
-org.freedesktop.Platform.Compat.{architecture}.debug   32 bits compatible extension (debug)
-org.freedesktop.Platform.GL{,32}.default               Mesa drivers (extension)
-org.freedesktop.Platform.GL{,32}.mesa-git              Mesa drivers, latest (extension)
 org.freedesktop.Sdk.Debug                              SDK debug information (extension)
 org.freedesktop.Sdk.Locale                             SDK translations (extension)
 org.freedesktop.Sdk.Docs                               SDK documentation (extension)
-org.freedesktop.Sdk.Extension.toolchain-{architecture} SDK cross compilers (extension)
 ====================================================== =====================================
 
 GNOME
 -----
 
-The GNOME runtime is appropriate for any application that uses the GNOME
-platform. It is based on the Freedesktop runtime and adds the GNOME platform,
-including:
-
-* Gjs
-* GObject Introspection
-* GStreamer
-* GVFS
-* Libnotify
-* Libsecret
-* LibSoup
-* PyGObject
-* Vala
-* WebKitGTK
-
-The GNOME runtime is maintained `here
-<https://gitlab.gnome.org/GNOME/gnome-build-meta>`__.
-
-Available GNOME runtimes:
-
-=========================  =================================
-ID                         Description
-=========================  =================================
-org.gnome.Platform         Runtime
-org.gnome.Sdk              SDK
-=========================  =================================
-
-The following runtime extensions are available:
-
-=========================  =================================
-ID                         Description
-=========================  =================================
-org.gnome.Platform.Locale  Runtime translations (extension)
-org.gnome.Sdk.Debug        SDK debug information (extension)
-org.gnome.Sdk.Locale       SDK translations (extension)
-org.gnome.Sdk.Docs         SDK documentation (extension)
-=========================  =================================
+The `GNOME runtime <https://gitlab.gnome.org/GNOME/gnome-build-meta>`_
+is appropriate for any application that uses the GNOME platform. It is
+based on the Freedesktop runtime and adds the  libraries and components
+used by the GNOME platform.
+
+Major version releases of the runtime are synced with `GNOME releases <https://release.gnome.org/calendar/>`_
+and are announced on `GNOME Discourse <https://discourse.gnome.org/tag/announcement>`_.
+Usually a given branch of the runtime is supported for an year and EOL-ed
+upon the release of a newstable version.
+
+====================================================== =====================================
+ID                                                     Description
+====================================================== =====================================
+org.gnome.Platform                                     Runtime
+org.gnome.Sdk                                          SDK
+org.gnome.Platform.Locale                              Runtime translations (extension)
+org.gnome.Sdk.Debug                                    SDK debug information (extension)
+org.gnome.Sdk.Locale                                   SDK translations (extension)
+org.gnome.Sdk.Docs                                     SDK documentation (extension)
+====================================================== =====================================
 
 KDE
 ---
 
-The KDE runtime is also based on the Freedesktop runtime and adds Qt and KDE
-Frameworks. It is appropriate for any application that makes use of the KDE
+Runtime ID: ``org.kde.Platform``
+SDK ID: ``org.kde.Sdk``
+
+The `KDE runtime <https://invent.kde.org/packaging/flatpak-kde-runtime>`_
+is also based on the Freedesktop runtime and adds Qt and KDE Frameworks.
+It is appropriate for any application that makes use of the KDE
 platform and most Qt-based applications.
 
-The KDE runtime is maintained `here
-<https://invent.kde.org/packaging/flatpak-kde-runtime>`__.
+Qt5 LTS (based on KDE's Qt patch collection) branches are created on
+Freedesktop runtime major version releases and Qt6 branches are created
+on new Qt6 releases. More information about the support policy can be
+found on the `KDE wiki <https://community.kde.org/Policies/Flatpak_Runtime_Update_Policy>`_
+and announcements for new runtime branch releases are made on the
+`KDE Discourse <https://discuss.kde.org/c/announcement/9>`_.
 
-Available KDE runtimes:
+====================================================== =====================================
+ID                                                     Description
+====================================================== =====================================
+org.kde.Platform                                       Runtime
+org.kde.Sdk                                            SDK
+org.kde.Platform.Locale                                Runtime translations (extension)
+org.kde.Sdk.Debug                                      SDK debug information (extension)
+org.kde.Sdk.Locale                                     SDK translations (extension)
+org.kde.Sdk.Docs                                       SDK documentation (extension)
+====================================================== =====================================
 
-=======================  =================================
-ID                       Description
-=======================  =================================
-org.kde.Platform         Runtime
-org.kde.Sdk              SDK
-=======================  =================================
+elementary
+----------
 
-The following runtime extensions are available:
+Runtime ID: ``io.elementary.Platform``
+SDK ID: ``io.elementary.Platform``
 
-=======================  =================================
-ID                       Description
-=======================  =================================
-org.kde.Platform.Locale  Runtime translations (extension)
-org.kde.Sdk.Debug        SDK debug information (extension)
-org.kde.Sdk.Locale       SDK translations (extension)
-org.kde.Sdk.Docs         SDK documentation (extension)
-=======================  =================================
+The `elementary runtime <https://github.com/elementary/flatpak-platform>`_
+is hosted by elementary and is appropriate for any application that
+would like to publish to the elementary AppCenter. It is based on the
+GNOME runtime and adds the elementary platform.
 
-elementary
-----------
+====================================================== =====================================
+ID                                                     Description
+====================================================== =====================================
+io.elementary.Platform                                 Runtime
+io.elementary.Sdk                                      SDK
+io.elementary.Platform.Locale                          Runtime translations (extension)
+io.elementary.Sdk.Debug                                SDK debug information (extension)
+io.elementary.Sdk.Locale                               SDK translations (extension)
+io.elementary.Sdk.Docs                                 SDK documentation (extension)
+====================================================== =====================================
+
+Check software available in runtimes
+------------------------------------
+
+The best way to check software packaged in the runtime is to look at
+their respective manifests in the git repository or release contents.
+
+The latter can be done using::
+
+	flatpak run --command=cat <ID>//<branch> /usr/manifest.json|jq -r '."modules"|.[]|."name"'|sed -E 's#.*/(.*)\.bst#\1#'|sort -u
 
-The elementary runtime is appropriate for any application that would like to publish in elementary AppCenter. It is based on the GNOME runtime and adds the elementary platform, including:
+	# List all contents in GNOME 47 runtime
+	flatpak run --command=cat org.gnome.Platform//47 /usr/manifest.json|jq -r '."modules"|.[]|."name"'|sed -E 's#.*/(.*)\.bst#\1#'|sort -u
 
-* elementary Icons
-* elementary Stylesheet
-* elementary Sound Theme
-* Granite
+``pkg-config`` can be used for modules that install pkg-config files::
 
-The elementary runtime is maintained `here
-<https://github.com/elementary/flatpak-platform>`__.
+	flatpak run --command=pkg-config <SDK ID>//<branch> --list-all
 
-Available elementary runtimes:
+	# Check version appstream in Freedesktop SDK 24.08
+	flatpak run --command=pkg-config org.freedesktop.Sdk//24.08 --modversion appstream
 
-=============================  =================================
-ID                             Description
-=============================  =================================
-io.elementary.Platform         Runtime
-io.elementary.Sdk              SDK
-=============================  =================================
+``ldconfig`` can be used to list all libraries::
 
-The following runtime extensions are available:
+	flatpak run --command=ldconfig <ID>//<branch> -p
 
-=============================  =================================
-ID                             Description
-=============================  =================================
-io.elementary.Platform.Locale  Runtime translations (extension)
-io.elementary.Sdk.Debug        SDK debug information (extension)
-io.elementary.Sdk.Locale       SDK translations (extension)
-io.elementary.Sdk.Docs         SDK documentation (extension)
-=============================  =================================
+	# Check libraries in Freedesktop runtime 24.08
+	flatpak run --command=ldconfig org.freedesktop.Platform//24.08 -p|awk '/\.so/ {print $1}'
