From a1ef27cafb8695fae2acdbe7a83f0b0991ccbfcd Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 30 Jun 2016 20:16:48 -0400 Subject: [PATCH] Document the metadata format This is useful information that should be available in a single place. --- doc/Makefile.am | 4 + doc/flatpak-metadata.xml | 323 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 327 insertions(+) create mode 100644 doc/flatpak-metadata.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index f0e78e07..0af2a9bb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,6 +14,9 @@ XSLTPROC_FLAGS = \ .xml.1: $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< +.xml.5: + $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + man_MANS = \ flatpak.1 \ flatpak-remote-add.1 \ @@ -43,6 +46,7 @@ man_MANS = \ flatpak-build-update-repo.1 \ flatpak-build-sign.1 \ flatpak-builder.1 \ + flatpak-metadata.5 \ $(NULL) xml_files = $(man_MANS:.1=.xml) diff --git a/doc/flatpak-metadata.xml b/doc/flatpak-metadata.xml new file mode 100644 index 00000000..5be34b25 --- /dev/null +++ b/doc/flatpak-metadata.xml @@ -0,0 +1,323 @@ + + + + + + + flatpak metadata + flatpak + + + + Developer + Alexander + Larsson + alexl@redhat.com + + + + + + flatpak metadata + 5 + + + + flatpak-metadata + Information about an application or runtime + + + + Description + + + Flatpak uses metadata files to describe applications and runtimes. + The metadata file for a deployed application or + runtime is placed in the toplevel deploy directory. For example, the + metadata for the locally installed application org.gnome.Calculator + is in + ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata. + + + + Most aspects of the metadata configuration can be overridden when + launching applications, either temporarily via options of the flatpak + run command, or permanently with the flatpak override command. + + + + A metadata file describing the effective configuration is available + inside the running sandbox at /run/user/$UID/flatpak-info. + + + + + File format + + + The metadata file is using the same .ini file format that is used for + systemd unit files or application .desktop files. + + + + [Application] or [Runtime] + + + Metadata for applications starts with an [Application] group, + metadata for runtimes with a [Runtime] group. + + + The following keys can be present in these groups: + + + + (string) + The name of the application or runtime. This key is mandatory. + + + (string) + The fully qualified name of the runtime that is used by the application. This key is mandatory for applications. + + + (string) + The fully qualified name of the sdk that matches the runtime. + + + (string) + The command to run. Only relevant for applications. + + + + + [Context] + + This group determines various system resources that may be shared + with the application when it is run in a flatpak sandbox. + + + All keys in this group (and the group itself) are optional. + + + + (list) + + List of subsystems to share with the host system. + Possible subsystems: network, ipc. + + + + (list) + + List of well-known sockets to make available in the sandbox. + Possible sockets: x11, wayland, pulseaudio, session-bus, system-bus. + When making a socket available, flatpak also sets + well-known environment variables like DISPLAY or + DBUS_SYSTEM_BUS_ADDRESS to let the application + find sockets that are not in a fixed location. + + + + (list) + + List of devices to make available in the sandbox. + Possible values: dri, all. + + + + (list) + + List of filesystem subsets to make available to the + application. Possible values: home, host, xdg-desktop, + xdg-documents, xdg-download xdg-music, xdg-pictures, + xdg-public-share, xdg-templates, xdg-videos, xdg-run, + an absolute path, or a homedir-relative path like + ~/dir or paths relative to the xdg dirs, like + xdg-download/subdir. Each entry can have a suffix of + :ro or :rw to indicate if the path should be shared + read-only or read-write. + + + + (list) + + List of homedir-relative paths to make available at + the corresponding path in the per-application home directory, + allowing the locations to be used for persistent data when + the application does not have access to the real homedir. + + + + + + [Session Bus Policy] + + If the key is not allowing full access + to the D-Bus session bus, then flatpak provides filtered access. + + + The default policy for the session bus does not allow the + application to own any names, but allows it to talk to portal + APIs (bus names of the form org.freedesktop.portal.*). + + + If the [Session Bus Policy] group is present, it provides + policy for session bus access. + + + Each key in this group has the form of a D-Bus bus name or + prefix thereof, for example + or + + + The possible values for entry are, in increasing order or + access: + + + + + + The bus name or names in question is invisible to the application. + + + + + + The bus name or names can be enumerated by the application. + + + + + + The application can send messages and receive replies from the bus name or names. + + + + + + The application can own the bus name or names. + + + + + + [System Bus Policy] + + If the key is not allowing full access + to the D-Bus system bus, then flatpak does not make the system + bus available unless the [System Bus Policy] group is present + and provides a policy for filtered access. + + + Entries in this group have the same form as for the [Session Bus Policy] group. + + + + [Environment] + + The [Environment] group specifies environment variables to set + when running the application. + + + Entries in this group have the form + where is the name of an environment variable + to set. + + + + [Extension NAME] + + Runtimes and applications can define extensions, which are optional, + additional runtimes to be mounted at a specified location inside + the sandbox when they are present on the system. Typical uses for + extensions include translations for applications, or debuginfo + for sdks. The name of the extension is specified as part of the + group heading. + + + + (string) + + The relative path at which the extension will be mounted in + the sandbox. If the extension is for an application, the + path is relative to /app, otherwise + it is relative to /usr. This key + is mandatory. + + + + (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 is for. + + + + (boolean) + + If this key is set to true, then flatpak will look for + extensions whose name is a prefix of the extension name, and + mount them at the corresponding name below the subdirectory. + + + + (boolean) + + Whether to automatically download this extension + when updating or installing a 'related' application + or runtime. + + + + (boolean) + + Whether to automatically delete this extension + when deleting a 'related' application or runtime. + + + + + + + + Example + +[Application] +name=org.gnome.Calculator +runtime=org.gnome.Platform/x86_64/3.20 +sdk=org.gnome.Sdk/x86_64/3.20 +command=gnome-calculator + +[Context] +shared=network;ipc; +sockets=x11;wayland; +filesystems=xdg-run/dconf;~/.config/dconf:ro; + +[Session Bus Policy] +ca.desrt.dconf=talk + +[Environment] +DCONF_USER_CONFIG_DIR=.config/dconf + +[Extension org.gnome.Calculator.Locale] +directory=share/runtime/locale +subdirectories=true + +[Extension org.gnome.Calculator.Debug] +directory=lib/debug + + + + + See also + + + flatpak1, + flatpak-run1, + flatpak-override1 + + + + +