flatpak-docs
flatpak-docs copied to clipboard
Published
20 hours ago •
flatpak
flatpak
Missing information on extensions
There's an odd mention of extensions in the docs, but no real explanation. It's a basic concept so we ought to cover it, probably in building basics.
As a part of this, we ought to specifically explain .Local and .Debug extensions and how they work. This might call for a new section under debugging (which doesn't exist yet) and creating a new page on localisation.
In man flatpak-metadata, I see this:
Click to expand
[Extension NAME]
Runtimes and applications can define extension points, which allow optional, additional runtimes to be
mounted at a specified location inside the sandbox when they are present on the system. Typical uses for
extension points include translations for applications, or debuginfo for sdks. The name of the extension
point is specified as part of the group heading. Since 0.11.4, the name may optionally include a tag in
the NAME in the name@tag ref syntax if you wish to use different configurations (eg, versions) of the
same extension concurrently. The "tag" is effectively ignored, but is necessary in order to allow the
same extension name to be specified more than once.
directory (string)
The relative path at which the extension will be mounted in the sandbox. If the extension point is
for an application, the path is relative to /app, otherwise it is relative to /usr. This key is
mandatory. Available since 0.1.
version (string)
The branch to use when looking for the extension. If this is not specified, it defaults to the branch
of the application or runtime that the extension point is for. Available since 0.4.1.
versions (string)
The branches to use when looking for the extension. If this is not specified, it defaults to the
branch of the application or runtime that the extension point is for. Available since 0.9.1, and
backported to the 0.8.x branch in 0.8.4.
add-ld-path (string)
A path relative to the extension point directory that will be appended to LD_LIBRARY_PATH. Available
since 0.9.1, and backported to the 0.8.x branch in 0.8.3.
merge-dirs (string)
A list of relative paths of directories below the extension point directory that will be merged.
Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.
download-if (string)
A condition that must be true for the extension to be auto-downloaded. As of 1.1.1 this supports
multiple conditions separated by semi-colons.
These are the supported conditions:
active-gl-driver
Is true if the name of the active GL driver matches the extension point basename. Available since
0.9.1, and backported to the 0.8.x branch in 0.8.3.
active-gtk-theme
Is true if the name of the current GTK theme (via org.gnome.desktop.interface GSetting) matches
the extension point basename. Added 0.10.1.
have-intel-gpu
Is true if the i915 kernel module is loaded. Added 0.10.1.
on-xdg-desktop-*
Is true if the suffix (case-insensitively) is in the XDG_CURRENT_DESKTOP env var. For example
on-xdg-desktop-GNOME-classic. Added 1.1.1.
autoprune-unless (string)
A condition that must be false for the extension to be considered unused when pruning. For example,
flatpak uninstall --unused uses this information. The only currently recognized value is
active-gl-driver, which is true if the name of the active GL driver matches the extension point
basename. Available since 0.11.8.
enable-if (string)
A condition that must be true for the extension to be enabled. As of 1.1.1 this supports multiple
conditions separated by semi-colons. See download-if for available conditions.
subdirectory-suffix (string)
A suffix that gets appended to the directory name. This is very useful when the extension point
naming scheme is "reversed". For example, an extension point for GTK+ themes would be
/usr/share/themes/$NAME/gtk-3.0, which could be achieved using subdirectory-suffix=gtk-3.0. Available
since 0.9.1, and backported to the 0.8.x branch in 0.8.3.
subdirectories (boolean)
If this key is set to true, then flatpak will look for extensions whose name is a prefix of the
extension point name, and mount them at the corresponding name below the subdirectory. Available
since 0.1.
no-autodownload (boolean)
Whether to automatically download extensions matching this extension point when updating or
installing a 'related' application or runtime. Available since 0.6.7.
locale-subset (boolean)
If set, then the extensions are partially downloaded by default, based on the currently configured
locales. This means that the extension contents should be a set of directories with the language code
as name. Available since 0.9.13 (and 0.6.6 for any extensions called *.Locale)
autodelete (boolean)
Whether to automatically delete extensions matching this extension point when deleting a 'related'
application or runtime. Available since 0.6.7.
collection-id (string)
The ID of the collection that this extension point belongs to. If this is unspecified, it defaults to
the collection ID of the application or runtime that the extension point is for. Currently, extension
points must be in the same collection as the application or runtime that they are for. Available
since 0.99.1.
How should we structure it? Should we just copy paste?
The first couple of sentences from the man page are decent, but it quickly gets into technical details after that - not something we'd want for a basic introduction.
The other topics I'd want to cover is who the users of extensions are, and what they might need to use them for. Who needs to be in the business of creating .Local and .Debug extensions, and how do they get installed?