Add an example with an application extension

allanday commented 7 years ago

From https://github.com/flatpak/flatpak.github.io/issues/52:

This would be interesting e.g. for packaging transmageddon, which wants to use decss if it happens to be installed on the host system.

allanday commented 7 years ago

It's worth noting that the introduction describes extensions as something that are primarily for runtimes rather than apps. See:

http://docs.flatpak.org/en/latest/introduction.html#extensions

Below is a section that we used to have on extensions, as a part of the introduction. We removed it because all the examples related to runtimes and the docs are supposed to be for app developers. It also seemed out of place in the introduction. It would be good to bring this section back, with examples for app authors, and in a different section of the docs.

Extensions

Applications and runtimes can define extension points, where optional pieces can be plugged into the filesystem. Flatpak is using this to separate translations and debuginfo from the main application, and to include certain parts that are provided separately, such as GL libraries or gstreamer plugins.

When flatpak is setting up a sandbox, it is looking for extension points that are declared in the application and runtime metadata, and mounts runtimes with a matching name. A typical extension section in a metadata file looks like this:

[Extension org.gnome.Platform.GL]
version=1.4
directory=lib/GL

More complicated extension points can accept multiple extensions that get mounted below a single directory. For example, the gstreamer extension:

  [Extension org.freedesktop.Platform.GStreamer]
  version=1.4
  directory=lib/extensions/gstreamer-1.0
  subdirectories=true

The subdirectories=true key instructs flatpak to mount e.g. a org.freedesktop.Platform.GStreamer.mp3 runtime on /usr/lib/extensions/gstreamer-1.0/mp3 in the sandbox. The gstreamer libraries in the org.freedesktop.Platform runtime have been configured to look in this place for plugins.

TingPing commented 6 years ago

This blog post would be a starting point perhaps: https://tingping.github.io/2018/03/18/flatpaking-plugins.html

albfan commented 4 years ago

@allanday: Doing an example on https://gitlab.gnome.org/GNOME/gnome-builder/-/issues/1180 that needs both SDK Extension and app extension points.

https://gitlab.gnome.org/GNOME/gnome-build-meta/-/merge_requests/571

TingPing commented 4 years ago

@albfan I'd appreciate you writing a page about it here.

albfan commented 4 years ago

Where it would be better to document sdk extensions? After Building chapter? in Publish chapter?

Let me find a good example (glade and catalogs could be a great example)

Then I will start it in Publish chapter and we could move later to the right place.

TingPing commented 4 years ago

How about: Building -> Guides -> Extension Points

albfan commented 4 years ago

Cool: https://docs.flatpak.org/en/latest/guides.html

Probably we would document gedit extension points (for something based on org.gnome.Sdk) See https://gitlab.gnome.org/GNOME/gedit/-/issues/301 and Hexchat for something based on org.freedesktop.Sdk)

TingPing commented 4 years ago

Also probably worth describing just at a high level what an Extension Point is here: https://docs.flatpak.org/en/latest/basic-concepts.html

flatpak / flatpak-docs

Add an example with an application extension #18

Extensions