anatomy of a flatpak app didn't make much sense

It was a jumble of topics, and it covered extensions which aren't specific to apps. This commit restructures it, and hopefully makes the docs more logical.
flatpak · Jan 13, 2017 · 7bc762c · 7bc762c
1 parent 2333dbc
commit 7bc762c
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 60 deletions.
diff --git a/docs/anatomy-of-a-flatpak-app.rst b/docs/anatomy-of-a-flatpak-app.rst
diff --git a/docs/elements-of-a-flatpak-app.rst b/docs/elements-of-a-flatpak-app.rst
@@ -0,0 +1,55 @@
+Elements of a Flatpak Application
+=================================
+
+Flatpak expects applications to follow standard Linux desktop conventions. These are supplemented with a small number of Flatpak-specific elements that are used to distribute, install and run applications.
+
+Standard application elements
+-----------------------------
+
+The following are some of the Linux desktop conventions that are supported and expected by Flatpak. Application developers are encouraged to use them.
+
+* `AppData <https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps>`_, for providing information that can be used by app stores, such as an application description and screenshots
+* Application icons, provided in the typical sizes, formats and locations
+* D-Bus service files, for D-Bus activation and any services provided by the application
+* .desktop files, for providing basic information about the application
+
+Application structure
+---------------------
+
+When an application is built using flatpak, it is outputted with the following structure:
+
+* ``metadata`` - a keyfile which provides information about the application
+* ``/files`` - the files that make up the application, include source code and application data
+* ``/files/bin`` - application binaries
+* ``/export`` - files which the host environment needs access to, such as the application's AppData, .desktop file, icon and D-Bus service file
+
+All the files in the export directory must have the application ID as a prefix. This guarantees that applications cannot cause conflicts, and that they can’t override any system installed applications.
+
+Metadata files
+^^^^^^^^^^^^^^
+
+The application's ``metadata`` file provides information that allows flatpak to set up the sandbox for running the application. A typical metadata file looks like this::
+
+  [Application]
+  name=org.gnome.gedit
+  runtime=org.gnome.Platform/x86_64/3.22
+  sdk=org.gnome.Sdk/x86_64/3.22
+  command=gedit
+
+  [Context]
+  shared=ipc;network;
+  sockets=x11;wayland;pulseaudio;
+  devices=dri;
+  filesystems=host;
+
+  [Environment]
+  GEDIT_FOO=bar
+
+  [Session Bus Policy]
+  org.extra.name=talk
+  org.other.name=own
+
+This specifies the name of the application, the runtime it requires, the SDK that it is built against and the command used to run it. It also specifies file and device access, sets certain environment variables (inside the sandbox, of course), and how to connect to the session bus. Details on how to change these metadata parameters are included in subsequent sections.
+
+.. note::
+  While it is most common to encounter application metadata files, runtimes and extensions also have them.
diff --git a/docs/extensions.rst b/docs/extensions.rst
@@ -0,0 +1,27 @@
+Extensions
+==========
+
+In the introduction, Flatpak's key concepts were introduced: runtimes, bundled applications, SDKs, and sandboxes. There is one other concept that must be added to this list: extensions.
+
+An extension is an optional piece that can be plugged into a filesystem, and they can be created for both applications and runtimes. Extensions are used for several purposes in Flatpak:
+
+* To separate translations and debug information from each application. Since these parts can be large and are not always wanted, it makes sense to allow them to be optionally installed alongside the application.
+* For software components that need to be distributed separately from an application or library. Primary examples of this include GL libraries (which need to be provided by the host) and GStreamer plugins (which can't always be distributed for legal reasons).
+
+metadata
+--------
+
+Like runtimes, extensions are declared in the metadata of an application. They are then mounted by flatpak inside the application's sandbox. 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 are mounted below a single directory. For example, in this example the ``org.freedesktop.Platform`` runtime defines an extension point for GStreamer::
+
+  [Extension org.freedesktop.Platform.GStreamer]
+  version=1.4
+  directory=lib/extensions/gstreamer-1.0
+  subdirectories=true
+
+Here, the ``subdirectories=true`` key means that an extension with the ``org.freedesktop.Platform.GStreamer.mp3`` ID would be mounted within ``/usr/lib/extensions/gstreamer-1.0/mp3`` in the sandbox. This is how the ``org.freedesktop.Platform`` knows where to look for GStreamer plugins.
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,7 +13,8 @@ Contents
    :glob:
 
    introduction
-   anatomy-of-a-flatpak-app
+   elements-of-a-flatpak-app
+   extensions
    building-simple-apps
    flatpak-builder
    working-with-the-sandbox