要求与规范#

Flatpak尽可能不对应用程序作出限制。不过,开发者应当尽可能遵循标准Linux桌面的规范,这主要是为了应用程序能更好地集成到Linux桌面和应用中心(App Center)。开发者也应尽可能遵循Linux技术规范。

更多有关桌面集成的选项可以参考 桌面集成

应当遵循的标准#

使用Flatpak构建的应用应当遵循下列标准。一般而言,为Linux桌面设计的应用程序只需做少数改动即可符合这些标准。

应用ID#

As described in 使用Flatpak, Flatpak requires each application to have a unique identifier, which has a form such as org.example.app.

The format is in reverse-DNS style so the first section should be a domain controlled by the project and the trailing section represents the specific project. There are some exceptions to this, such as extensions using the base application-id of the project they extend rather than their own.

As will be seen below and in future sections, this ID is expected to be used in a number of places. Developers must follow the standard D-Bus naming conventions for bus names when creating their own IDs. This format is already recommended by the Desktop File specification and Appstream specification also.

For some practical examples of bad IDs

  • org.example.desktop

    This is a bad ID because the Appstream standard for legacy reasons treats IDs ending with .desktop as a special case causing inconsistency. For this same reason, .Desktop suffixes should not be used for newly named applications. Don’t hesitate to repeat the application name even if it already is part of the domain name section of the identifier (eg. org.example.Example).

  • io.github.foo

    This is problematic because while foo.github.io may be unique to your project, it does not include a project-specific identifier. This may cause issues if another project creates io.github.foo-bar which should be its own namespace but areas of flatpak may treat them similar. A better ID would be io.github.foo.foo even if it is redundant.

  • org.example-site.foo

    This ID is not valid according to the DBus specification as a dash - isn’t allowed except on the last component. You should replace - with an undercore _ and therefore, use org.example_site.Foo instead.

  • com.github.foo.bar or com.gitlab.foo.bar

    While a project may be hosted on GitHub or GitLab it does not have any control over the github.com or gitlab.com domain. Instead you should use io.github or io.gitlab as shown above.

  • Org.Example.App

    The TLD portion of the ID must be lowercased and while not required the application portion is recommended to be lowercase as well. Instead you should use org.example.app.

MetaInfo files#

MetaInfo files provide metadata about applications, which is used by application stores (such as Flathub, GNOME Software and KDE Discover).

The Freedesktop AppStream specification provides a complete reference for providing MetaInfo. You can use the online AppStream MetaInfo Creator to generate a basic file.

MetaInfo files should be named with the application ID and the .metainfo.xml file extension, and should be placed in /app/share/metainfo/. For example:

/app/share/metainfo/org.gnome.Dictionary.metainfo.xml

A legacy convention of having the .appdata.xml installed in /app/share/appdata is also accepted as well, and flatpak-builder will check either directory with either extension.

The appstreamcli validate --explain command can be used to check MetaInfo files for errors.

应用图标#

Applications are expected to provide an application icon, which is used for their application launcher. These icons should be provided in accordance with the Freedesktop icon specification.

图标应该以应用ID命名,以PNG或者SVG格式,而且必须放在标准的位置:

/app/share/icons/hicolor/$size/apps/

举个例子,128x128px版本的GNOME Dictionary的图标的路径应该是:

/app/share/icons/hicolor/128x128/apps/org.gnome.Dictionary.png

Icons must be square shaped, ie their width and height must be the same. The maximum size allowed by the specification is 512x512px. SVG icons are of size scalable:

/app/share/icons/hicolor/scalable/apps/org.gnome.Dictionary.svg

Flatpak will export the following icon name patterns: $FLATPAK_ID, $FLATPAK_ID.foo, $FLATPAK_ID-foo. They may end with an extension suffix like .png, .svg. Exported icons can be found in the icons subfolder of $HOME/.local/share/flatpak/exports/share or /var/lib/flatpak/exports/share depending on system or user install.

The distribution usually appends those paths to $XDG_DATA_DIRS on host when installing the flatpak package. Unless an icon is exported by Flatpak, host applications cannot access it.

desktop文件#

Desktop files are used to provide the desktop environment with information about each application. The Freedesktop specification provides a complete reference for writing desktop files, and additional information about them is available online.

desktop文件应该以应用的ID命名,以 .desktop 为文件扩展名,而且应该放在 /app/share/applications/ 。举个例子:

/app/share/applications/org.gnome.Dictionary.desktop

一个desktop文件应当至少包含以下字段: name*(应用程序名)、*exec*(启动命令)、*type*(类型)、*icon*(图标名)和 *categories (所属分类):

[Desktop Entry]
Name=Gnome Dictionary
Exec=gnome-dictionary
Type=Application
Icon=org.gnome.Dictionary
Categories=Office;Dictionary;

desktop-file-validate 命令可以用来检测desktop文件的错误。

The Exec key of the desktop files is rewritten by Flatpak when installing an app. The original value of the key becomes the value of the --command argument like so:

Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=gnome-dictionary org.gnome.Dictionary

Flatpak will export the following desktop filename patterns: $FLATPAK_ID.desktop, $FLATPAK_ID.foo.desktop, $FLATPAK_ID-foo.desktop. Exported desktop files can be found in the applications subfolder of $HOME/.local/share/flatpak/exports/share or /var/lib/flatpak/exports/share depending on system or user install.

The distribution usually appends those paths to $XDG_DATA_DIRS on host when installing the flatpak package. Unless a desktop file is exported by Flatpak, host applications cannot access it.

Exporting through extra-data#

Files downloaded through extra-data are only downloaded when installing, as such they aren’t yet available for flatpak-builder to automatically export during the build process.

When using extra-data, place any files that must be exported under this location:

/app/extra/export/share/

For example, if GNOME Dictionary used extra-data to download a 96x96 icon this would be its path:

/app/extra/export/share/icons/hicolor/96x96/apps/org.gnome.Dictionary.png

技术规范#

Flatpak和多数Linux桌面都遵循下列标准技术规范。有Linux使用经验的用户对此可能已有了解。首次使用Linux的开发者同样可以在这里找到有用的信息。

D-Bus#

D-Bus是Linux桌面使用的标准IPC(进程间通讯,译者注)框架。大多数应用程序并不会用到D-Bus;但如果需要,Flatpak也同样提供D-Bus支持。

D-Bus可用于启动应用程序,以及系统服务之间的交互。应用程序也可以实现它们自己的D-Bus服务(此时,D-Bus服务的名称必须与应用程序的ID一致)。

Filesystem layout(文件系统布局,译者注)#

每个Flatpak沙箱,一个应用运行的环境,包含这个应用的运行时的文件系统。这个准守 standard Linux filesystem conventions (标准Linux文件系统约定,译者注)。

举个例子,沙箱根目录包含 /etc 用于配置文件和 /usr 用于多用户utilities和应用。除此之外,每个沙箱包含一个顶级 /app/ 目录,用于应用自己文件的存放。

XDG基本目录#

XDG base directories are standard locations for user-specific application data. Popular toolkits provide convenience functions for accessing XDG base directories. These include:

  • Electron: 使用 app.getPath 访问XDG基本目录

  • Glib: 通过 g_get_user_cache_dir (), g_get_user_data_dir (), g_get_user_config_dir () 函数访问XDG基本目录

  • Qt: provides access to XDG base directories with the QStandardPaths Class

如果应用没有使用上述工具包,也可以通过下面的方式找到XDG基本目录:

基本目录

用途

默认位置

XDG_CONFIG_HOME

具体用户配置文件

~/.var/app/<app-id>/config

XDG_DATA_HOME

具体用户数据

~/.var/app/<app-id>/data

XDG_CACHE_HOME

Non-essential user-specific data(非基本具体用户数据,译者注)

~/.var/app/<app-id>/cache

XDG_STATE_HOME

State data such as undo history

~/.var/app/<app-id>/.local/state

举个例子,GNOME Dictionary会把具体用户数据存放在:

~/.var/app/org.gnome.Dictionary/data/gnome-dictionary

These environment variables are always set by flatpak and override any host values. However if using the host directories are needed the $HOST_XDG_CONFIG_HOME, $HOST_XDG_DATA_HOME, $HOST_XDG_CACHE_HOME, and $HOST_XDG_STATE_HOME environment variables will be set if a custom value was set on the host.

Note that $XDG_STATE_HOME and $HOST_XDG_STATE_HOME is only supported by Flatpak 1.13 and later. If your app needs to work on earlier versions of Flatpak, you can use the --persist=.local/state and --unset-env=XDG_STATE_HOME finish args so the app will use the correct directory, even after Flatpak is later upgraded to >1.13.

注意应用可以被配置成使用非默认基本目录(见 沙箱权限)。