Skip to content

runtime: Improve the runtime section #547

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bbhtt merged 2 commits into from
Dec 1, 2024
Merged

runtime: Improve the runtime section #547

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
59dfb9f
runtime: Improve the runtime section
bbhtt Dec 1, 2024
6667645
Update po files
bbhtt Dec 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 103 additions & 112 deletions docs/available-runtimes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}'
Loading