Missing information on extensions

[allanday]

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.

[TheEvilSkeleton]

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?

[allanday]

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?

[TheEvilSkeleton]

Just to make sure, by .Local you mean .Locale right?