forked from Mirrors/flatpak-builder
564 lines
26 KiB
XML
564 lines
26 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<refentry id="flatpak-metadata">
|
|
|
|
<refentryinfo>
|
|
<title>flatpak metadata</title>
|
|
<productname>flatpak</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Alexander</firstname>
|
|
<surname>Larsson</surname>
|
|
<email>alexl@redhat.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>flatpak metadata</refentrytitle>
|
|
<manvolnum>5</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>flatpak-metadata</refname>
|
|
<refpurpose>Information about an application or runtime</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Flatpak uses metadata files to describe applications and runtimes.
|
|
The <filename>metadata</filename> 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
|
|
<filename>~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
A metadata file describing the effective configuration is available
|
|
inside the running sandbox at <filename>/.flatpak-info</filename>.
|
|
For compatibility with older Flatpak versions,
|
|
<filename>/run/user/$UID/flatpak-info</filename> is a symbolic
|
|
link to the same file.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>File format</title>
|
|
|
|
<para>
|
|
The metadata file is using the same .ini file format that is used for
|
|
systemd unit files or application .desktop files.
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>[Application] or [Runtime]</title>
|
|
|
|
<para>
|
|
Metadata for applications starts with an [Application] group,
|
|
metadata for runtimes with a [Runtime] group.
|
|
</para>
|
|
<para>
|
|
The following keys can be present in these groups:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>name</option> (string)</term>
|
|
<listitem><para>The name of the application or runtime. This key is mandatory.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime</option> (string)</term>
|
|
<listitem><para>The fully qualified name of the runtime that is used by the application. This key is mandatory for applications.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sdk</option> (string)</term>
|
|
<listitem><para>The fully qualified name of the sdk that matches the runtime.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>command</option> (string)</term>
|
|
<listitem><para>The command to run. Only relevant for applications.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>required-flatpak</option> (string)</term>
|
|
<listitem><para>
|
|
The required version of Flatpak to run this application
|
|
or runtime.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>tags</option> (string list)</term>
|
|
<listitem><para>
|
|
Tags to include in AppStream XML.
|
|
<!-- TODO: what are these tags for? What should they
|
|
be? -->
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Context]</title>
|
|
<para>
|
|
This group determines various system resources that may be shared
|
|
with the application when it is run in a flatpak sandbox.
|
|
</para>
|
|
<para>
|
|
All keys in this group (and the group itself) are optional.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>shared</option> (list)</term>
|
|
<listitem><para>
|
|
List of subsystems to share with the host system.
|
|
Possible subsystems: network, ipc.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sockets</option> (list)</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>devices</option> (list)</term>
|
|
<listitem><para>
|
|
List of devices to make available in the sandbox.
|
|
Possible values: dri, kvm, all.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>filesystems</option> (list)</term>
|
|
<listitem><para>
|
|
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,
|
|
xdg-config, xdg-cache, xdg-data,
|
|
an absolute path, or a homedir-relative path like
|
|
~/dir or paths relative to the xdg dirs, like
|
|
xdg-download/subdir. The xdg-* arguments can also
|
|
specify a subdirectory, such as xdg-pictures/screenshots.
|
|
Each entry can have a suffix of
|
|
:ro, :rw or :create to indicate if the path should be shared
|
|
read-only, read-write or read-write + create if needed
|
|
(default is read-write).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>persistent</option> (list)</term>
|
|
<listitem><para>
|
|
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.
|
|
For instance making ".myapp" persistent would make "~/.myapp"
|
|
in the sandbox a bind mount to "~/.var/app/org.my.App/.myapp",
|
|
thus allowing an unmodified application to save data in
|
|
the per-application location.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>features</option> (list)</term>
|
|
<listitem><para>
|
|
List of features available or unavailable to the
|
|
application, currently from the following list:
|
|
devel, multiarch.
|
|
A feature can be prefixed with ! to indicate the absence
|
|
of that feature, for example !devel if development and
|
|
debugging are not allowed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Instance]</title>
|
|
<para>
|
|
This group only appears in <filename>/.flatpak-info</filename>
|
|
for a running app, and not in the metadata files written by
|
|
application authors. It is filled in by Flatpak itself.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>app-path</option> (string)</term>
|
|
<listitem><para>
|
|
The absolute path on the host system of the app's
|
|
app files, as mounted at <filename>/app</filename>
|
|
inside the container
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>branch</option> (string)</term>
|
|
<listitem><para>
|
|
The branch of the app, for example
|
|
<literal>stable</literal>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>flatpak-version</option> (string)</term>
|
|
<listitem><para>
|
|
The version number of the Flatpak version that ran
|
|
this app
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime-path</option> (string)</term>
|
|
<listitem><para>
|
|
The absolute path on the host system of the app's
|
|
runtime files, as mounted at <filename>/usr</filename>
|
|
inside the container
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>session-bus-proxy</option> (boolean)</term>
|
|
<listitem><para>
|
|
True if this app cannot access the D-Bus session bus
|
|
directly (either it goes via a proxy, or it cannot
|
|
access the session bus at all)
|
|
<!-- TODO: Those semantics are weird, are they
|
|
intended? -->
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>system-bus-proxy</option> (boolean)</term>
|
|
<listitem><para>
|
|
True if this app cannot access the D-Bus system bus
|
|
directly (either it goes via a proxy, or it cannot
|
|
access the system bus at all)
|
|
<!-- TODO: Those semantics are weird, are they
|
|
intended? -->
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Session Bus Policy]</title>
|
|
<para>
|
|
If the <option>sockets</option> key is not allowing full access
|
|
to the D-Bus session bus, then flatpak provides filtered access.
|
|
</para>
|
|
<para>
|
|
The default policy for the session bus only allows the
|
|
application to own its own application ID and
|
|
subnames. For instance if the app is called
|
|
"org.my.App", it can only own "org.my.App" and
|
|
"org.my.App.*". Its also only allowed to talk to the
|
|
bus itself (org.freedesktop.DBus) and the portal APIs
|
|
APIs (bus names of the form org.freedesktop.portal.*).
|
|
</para>
|
|
<para>
|
|
Additionally the app is always allowed to reply to
|
|
messages sent to it, and emit broadcast signals (but
|
|
these will not reach other sandboxed apps unless they
|
|
are allowed to talk to your app.
|
|
</para>
|
|
<para>
|
|
If the [Session Bus Policy] group is present, it provides
|
|
policy for session bus access.
|
|
</para>
|
|
<para>
|
|
Each key in this group has the form of a D-Bus bus name or
|
|
prefix thereof, for example <option>org.gnome.SessionManager</option>
|
|
or <option>org.freedesktop.portal.*</option>
|
|
</para>
|
|
<para>
|
|
The possible values for entry are, in increasing order or
|
|
access:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>none</option></term>
|
|
<listitem><para>
|
|
The bus name or names in question is invisible to the application.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>see</option></term>
|
|
<listitem><para>
|
|
The bus name or names can be enumerated by the application.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>talk</option></term>
|
|
<listitem><para>
|
|
The application can send messages/ and receive replies and signals from the bus name or names.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>own</option></term>
|
|
<listitem><para>
|
|
The application can own the bus name or names (as well as all the above).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[System Bus Policy]</title>
|
|
<para>
|
|
If the <option>sockets</option> 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.
|
|
</para>
|
|
<para>
|
|
Entries in this group have the same form as for the [Session Bus Policy] group.
|
|
However, the app has no permissions by default.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Environment]</title>
|
|
<para>
|
|
The [Environment] group specifies environment variables to set
|
|
when running the application.
|
|
</para>
|
|
<para>
|
|
Entries in this group have the form <option>VAR=VALUE</option>
|
|
where <option>VAR</option> is the name of an environment variable
|
|
to set.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Extension NAME]</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>directory</option> (string)</term>
|
|
<listitem><para>
|
|
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 <filename>/app</filename>, otherwise
|
|
it is relative to <filename>/usr</filename>. This key
|
|
is mandatory.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>version</option> (string)</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>versions</option> (string)</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>add-ld-path</option> (string)</term>
|
|
<listitem><para>
|
|
A path relative to the extension point directory that will be appended
|
|
to LD_LIBRARY_PATH.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>merge-dirs</option> (string)</term>
|
|
<listitem><para>
|
|
A list of relative paths of directories below the extension point directory
|
|
that will be merged.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>download-if</option> (string)</term>
|
|
<listitem><para>
|
|
A condition that must be true for the extension to be auto-downloaded.
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>enable-if</option> (string)</term>
|
|
<listitem><para>
|
|
A condition that must be true for the extension to be enabled.
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdirectory-suffix</option> (string)</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdirectories</option> (boolean)</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>no-autodownload</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether to automatically download extensions matching this extension
|
|
point when updating or installing a 'related' application or runtime.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>autodelete</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether to automatically delete extensions matching this extension
|
|
point when deleting a 'related' application or runtime.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<!-- FIXME: Uncomment this when enable-p2p is enabled unconditionally.
|
|
<varlistentry>
|
|
<term><option>collection-id</option> (string)</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
-->
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[ExtensionOf]</title>
|
|
<para>
|
|
This optional group may be present if the runtime is an extension.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>ref</option> (string)</term>
|
|
<listitem><para>
|
|
The ref of the runtime or application that this extension
|
|
belongs to.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>priority</option> (integer)</term>
|
|
<listitem><para>
|
|
The priority to give this extension when looking for the
|
|
best match. Default is 0.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Extra Data]</title>
|
|
<para>
|
|
This optional group may be present if the runtime or application uses
|
|
extra data that gets downloaded separately. The data in this group
|
|
gets merged into the repository summary, with the xa.extra-data-sources
|
|
key.
|
|
</para>
|
|
<para>
|
|
If multiple extra data sources are present, their uri, size and checksum
|
|
keys are grouped together by using the same suffix. If only one extra
|
|
data source is present, the suffix can be omitted.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>NoRuntime</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether to mount the runtime while running the /app/bin/apply_extra
|
|
script. Defaults to true, i.e. not mounting the runtime.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>uriX</option> (string)</term>
|
|
<listitem><para>
|
|
The uri for extra data source X. The only supported uri schemes are
|
|
http and https.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sizeX</option> (integer)</term>
|
|
<listitem><para>
|
|
The size for extra data source X.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>checksumX</option> (string)</term>
|
|
<listitem><para>
|
|
The sha256 sum for extra data source X.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>[Policy SUBSYSTEM]</title>
|
|
<para>
|
|
Subsystems can define their own policies to be placed in a group
|
|
whose name has this form. Their values are treated as lists,
|
|
in which items can have their meaning negated by prepending !
|
|
to the value. They are not otherwise parsed by Flatpak.
|
|
<!-- TODO: More information would be nice -->
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
<programlisting>
|
|
[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
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>flatpak-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>flatpak-override</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|