Flatpak application bundles may contain application entry points, which are any of these things:
- a graphical program that would normally appear in a menu
- a graphical program that would not normally appear in a menu, but can be launched in some other way, for example as a content-type handler
Desktop environments provide metadata about these programs so that they can be launched.
At least the following use-cases exist:
- It must be possible to translate the name into multiple languages, with a default (international English) name used for languages where there is no specific translation.
- Different manufacturers’ launcher implementations might have a different taxonomy of categories for programs.
- Certain graphical programs should be hidden from the menu, but treated as a first-class program during user interaction.
- Some graphical programs present multiple views which may appear separately in menus, but are all implemented in terms of the same running process. For example, an audio player may appear in the menu three times, as “Albums”, “Artists” and “Songs”. However, ideally there would only be one audio player process at any given time, even if the user switches between views.
- Some programs should be started during device startup or user login.
- In the SDK images, Apertis applications and services should not necessarily be listed in the XFCE menus, and XFCE applications should not be listed in the “device simulator”.
Security and privacy considerations
The list of installed store application bundles is considered to be private information, for several reasons:
- the general operating principle for Apertis’ app framework is that apps must not affect each other, except where given permission to interact, ensuring “loose coupling” between apps
- the presence of certain app bundles might be considered to be sensitive (for example, app bundles correlated with political or religious views)
- the complete list could be used for user fingerprinting, for example guessing that users of an online service share a device by observing that they have the same list of app-bundles
The list of installed entry-points is almost equivalent to the list of store application bundles and has similar considerations. However, some components cannot work without a list of store application bundles, or a list of their entry points. This leads to some privacy requirements:
- Certain platform components such as the app launcher require the ability to list store application bundles and/or their entry points. They must be able to do so.
- Store applications with special permissions might also be allowed to list store application bundles and/or their entry points.
- Store applications may list the entry points that advertise a particular public interface, as defined in the Interface discovery design.
- Store applications without special permissions must not be able to enumerate store application bundles that do not contain an entry point advertising a public interface, either directly or by enumerating entry points and inferring the existence of a bundle from its entry points.
Optionally, a single entry point may be specified to provide an icon for presentation in the application launcher. If no icon is presented it won’t be obvious to the user that they have the application installed, so the application store screening process should carefully consider whether an application should be allowed to install services and type handlers with no icon for the launcher.
Background services in the current Flatpak distribution model do not use entry points; rather, they request the ability to run arbitrary command lines in the background at runtime via the XDG Background portal.
System services are outside the scope of this design.
Application bundle metadata describes the fields that can appear in application entry points and are expected to remain supported long-term. This document provides rationale for those fields, suggested future directions, and details of functionality that is not necessarily long-term stable.
Each built-in or store application bundle has a bundle ID, which is
a reversed domain name such as
Each entry point within an application bundle has an entry point ID,
which is a reversed domain name such as
For simple bundles with a single entry point, the bundle ID and the entry point ID should be equal.
For more complex bundles with multiple entry points, the entry point ID should start with the bundle ID, but may have additional components.
All names should be allocated in a namespace controlled by the author
of the bundle — in particular, Apertis applications should be in
org.apertis. Sample code that is not intended to be used in production
should be placed in
also available for code samples that need to demonstrate the interaction
between multiple namespaces (we prefer
com.example, as a hint to
developers that reversed domain names do not always start with “org”).
Each Apertis application entry point is represented by a standard
freedesktop.org Desktop Entry (a
.desktop file in
XDG_DATA_DIRS/applications). The desktop file must
be named using the entry point ID, so
org.apertis.Example would have
The localestring mechanism is used for translated strings.
Apertis applications should usually have
OnlyShowIn=Apertis; so that they do
not appear in the XFCE desktop environment menu in SDK images.
Interfaces key is used for Interface discovery. In particular,
the following interfaces are defined:
org.apertis.GlobalSearchProvider: Indicates that the application is a global search provider, equivalent to the
MimeType key controls the possible content-type
and URI-scheme associations. For example,
x-scheme-handler/http is used in desktop environments such as GNOME
to designate an application as capable of acting as a general-purpose
web browser, and we will do the same here.
Services that parse desktop files should use the implementation in GLib, or an Apertis-specific API built on top of that implementation.
Additional recommended keys
The following additional keys are defined in the
[Desktop Entry] group.
X-GNOME-FullName(localestring): The human-readable full name of the application, such as
Test Web Browser. This key is already used by the GLib library, and by desktop environments based on it (such as GNOME). Like
Name, this is a “localestring”: non-English versions can be provided with syntax like
X-GNOME-FullName[pt_BR]=Navegador Internet de teste.
Simple applications (one entry point)
This is the simple case where an entry point has one “view”, for example a web browser.
# cat org.test.Web.desktop [Desktop Entry] Type=Application Name=Test Browser GenericName=Browser X-GNOME-FullName=The Test Web Browser Exec=test-browser %U Categories=Network;WebBrowser; MimeType=text/html;x-scheme-handler/http;x-scheme-handler/https; Icon=applications-internet
Entry points which do not appear in the menus
Some bundles might have an entry point that exists only to be started
as a side-effect of other operations, for instance to handle URIs
and content-types. Those entry points would have
NoDisplay=true to hide them from the menus; that is the only difference.
Some bundles have more than one entry in the system menus; the example
referred to previously would be an audio player with entry points for
Artists, Songs, and Albums. We propose to represent these with one
file per menu entry.
In this model, each menu entry is a
.desktop file. The audio player
org.test.Audio.Albums.desktop. In addition, it would install
The running instance of the application would always identify itself as
org.test.Audio, and the other three
.desktop files would be linked to it
by way of being in the same app bundle.
When using D-Bus activation for applications (which is recommended), the application
would have separate D-Bus
.service files for all four names, would
take all four bus names and their corresponding object paths at runtime,
and would export the
org.freedesktop.Application API at all four paths;
but all of them would have
to ensure that only one activation occurs. The
ActivateAction method on each bus name would open the relevant view.
The result would look something like this:
# org.test.Audio.desktop [Desktop Entry] Type=Application Name=Frampton GenericName=Audio Player X-GNOME-FullName=The Test Audio Player Exec=test-audio %F Categories=Audio;Player;Music; MimeType=audio/mpeg; NoDisplay=true; Icon=music
# org.test.Audio.Artists.desktop [Desktop Entry] Type=Application Name=Frampton — Artists GenericName=Artists Exec=test-audio --artists Categories=Audio;Player;Music; Icon=music-artist
# org.test.Audio.Albums.desktop [Desktop Entry] Type=Application Name=Frampton — Albums GenericName=Albums Exec=test-audio --albums Categories=Audio;Player;Music; Icon=music-album
# org.test.Audio.Songs.desktop [Desktop Entry] Type=Application Name=Audio — Songs GenericName=Songs Exec=test-audio --songs Categories=Audio;Player;Music; Icon=music-track