【Flatpak】构建的要求和约定

2024-05-02T22:09:30 (UTC +08:00)
https://docs.flatpak.org/en/latest/conventions.html

Flatpak 努力尽可能少地对应用程序提出要求。然而，预期应用程序遵循一小部分标准的 Linux 桌面约定，主要是为了确保应用程序与 Linux 桌面和应用中心集成。开发人员可能也会遇到一小部分 Linux 技术约定。

有关更多桌面集成选项的信息，请参阅桌面集成。

预期标准

使用 Flatpak 的应用程序通常应符合以下标准。以前面向 Linux 桌面的应用程序通常需要进行非常少的（如果有的话）更改来实现这一点。

应用程序标识符

正如在使用 Flatpak中所描述的，Flatpak 要求每个应用程序具有唯一的标识符，其形式类似于 org.example.app。

格式采用反向 DNS 样式，因此第一个部分应该是项目控制的域，而尾部部分代表特定项目。有一些例外情况，例如扩展使用扩展的项目的基本应用程序标识符，而不是它们自己的标识符。

正如将在下面和未来的部分中看到的那样，预期将在许多地方使用此 ID。开发人员在创建自己的 ID 时必须遵循标准的D-Bus 总线名称命名约定。此格式已经被桌面文件规范和Appstream 规范推荐使用。

以下是一些不良标识符的实际示例：

• org.example.desktop

  这是一个不良的标识符，因为出于遗留原因，Appstream 标准将以 .desktop 结尾的 ID 视为特殊情况，导致不一致性。出于同样的原因，不应为新命名的应用程序使用 .Desktop 后缀。即使应用程序名称已经是标识符的域名部分的一部分，也不要犹豫重复应用程序名称（例如 org.example.Example）。

• io.github.foo

  这是有问题的，因为虽然 foo.github.io 可能对你的项目来说是唯一的，但它不包括项目特定的标识符。如果另一个项目创建了 io.github.foo-bar，这可能会导致问题，因为它应该是自己的命名空间，但 flatpak 的某些区域可能会将它们视为相似。即使是多余的，更好的标识符也应该是 io.github.foo.foo。

• org.example-site.foo

  根据 DBus 规范，这个标识符是无效的，因为在除了最后一个组件之外，连字符 - 是不允许的。你应该将 - 替换为下划线 _，因此应使用 org.example_site.Foo。

• com.github.foo.bar 或 com.gitlab.foo.bar

  虽然一个项目可能托管在 GitHub 或 GitLab 上，但它对 github.com 或 gitlab.com 域没有任何控制权。相反，你应该像上面显示的那样使用 io.github 或 io.gitlab。

• Org.Example.App

  标识符的顶级域部分必须小写，虽然不是必需的，但建议应用程序部分也使用小写。因此，你应该使用 org.example.app。

MetaInfo 文件

MetaInfo 文件提供关于应用程序的元数据，这些元数据由应用商店（如 Flathub、GNOME 软件和 KDE Discover）使用。

Freedesktop AppStream 规范提供了有关提供 MetaInfo 的完整参考。你可以使用在线的AppStream MetaInfo Creator生成基本文件。

MetaInfo 文件应该以应用程序的 ID 和 .metainfo.xml 文件扩展名命名，并且应该放置在 /app/share/metainfo/ 目录下。例如：

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

一个传统的约定是将 .appdata.xml 安装在 /app/share/appdata 中，也同样被接受，flatpak-builder 将检查任一目录以及任一扩展名。

appstreamcli validate --explain 命令可用于检查 MetaInfo 文件是否存在错误。

应用程序图标

应用程序应该提供一个应用程序图标，用于它们的应用程序启动器。这些图标应该按照Freedesktop 图标规范提供。

图标应该以应用程序的 ID 命名，可以是 PNG 或 SVG 格式，并且必须放置在标准位置：

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

例如，GNOME Dictionary 的图标的 128✕128px 版本的路径是：

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

图标必须是方形的，即宽度和高度必须相同。规范允许的最大尺寸是 512x512px。SVG 图标的大小为 scalable：

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

Flatpak 将导出以下图标名称模式：$FLATPAK_ID, $FLATPAK_ID.foo, $FLATPAK_ID-foo。它们可能以像 .png, .svg 这样的扩展后缀结尾。导出的图标可以在 $HOME/.local/share/flatpak/exports/share 或 /var/lib/flatpak/exports/share 的 icons 子文件夹中找到，取决于系统或用户安装。

在安装 flatpak 软件包时，分发通常会将这些路径附加到主机上的 $XDG_DATA_DIRS。除非 Flatpak 导出了图标，否则主机应用程序无法访问它。

桌面文件

桌面文件用于向桌面环境提供有关每个应用程序的信息。Freedesktop 规范提供了编写桌面文件的完整参考，你也可以在其他信息在线获取。

桌面文件应该以应用程序的 ID 开头，后跟 .desktop 文件扩展名，并且应该放置在 /app/share/applications/ 目录下。例如：

/app/share/applications/org.gnome.Dictionary.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 命令来检查桌面文件中的错误。

桌面文件的 Exec 键在安装应用程序时会被 Flatpak 重写。键的原始值成为 --command 参数的值，如下所示：

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

Flatpak 将导出以下桌面文件名模式：$FLATPAK_ID.desktop, $FLATPAK_ID.foo.desktop, $FLATPAK_ID-foo.desktop。导出的桌面文件可以在 $HOME/.local/share/flatpak/exports/share 或 /var/lib/flatpak/exports/share 的 applications 子文件夹中找到，取决于系统或用户的安装。

在安装 flatpak 软件包时，分发通常会将这些路径附加到主机上的 $XDG_DATA_DIRS。除非 Flatpak 导出了桌面文件，否则主机应用程序无法访问它。

技术约定

以下是 Flatpak 和 Linux 桌面使用的标准技术约定。具有 Linux 经验的人可能已经对它们有所了解。然而，对于新手开发人员来说，这些信息可能会有所帮助。

D-Bus

D-Bus 是 Linux 桌面上使用的标准 IPC 框架。许多应用程序可能不需要使用它，但如果需要，Flatpak 会支持它。

D-Bus 可以用于应用程序启动和与某些系统服务通信。应用程序还可以提供自己的 D-Bus 服务（在这种情况下，D-Bus 服务名称预期与应用程序 ID 相同）。

文件系统布局

每个 Flatpak 沙盒，即应用程序运行的环境，都包含应用程序运行时的文件系统。这遵循标准的 Linux 文件系统约定。

例如，沙盒的根目录包含 /etc 目录用于配置文件和 /usr 用于多用户实用程序和应用程序。除此之外，每个沙盒都包含一个顶级的 /app 目录，用于存放应用程序自己的文件。

XDG 基础目录

XDG 基础目录是用户特定应用程序数据的标准位置。流行的工具包提供了方便的函数来访问 XDG 基础目录。其中包括：

• Electron：可以使用 app.getPath 访问 XDG 基础目录

• Glib：通过 g_get_user_cache_dir ()、g_get_user_data_dir ()、g_get_user_config_dir () 函数提供对 XDG 基础目录的访问

• Qt：使用QStandardPaths 类提供对 XDG 基础目录的访问

然而，没有使用这些工具包之一的应用程序可以期望在以下位置找到它们的 XDG 基础目录：

例如，GNOME Dictionary 将在以下位置存储用户特定的数据：

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

这些环境变量始终由 flatpak 设置，并覆盖任何主机值。但是，如果需要使用主机目录，则会设置 $HOST_XDG_CONFIG_HOME、$HOST_XDG_DATA_HOME、$HOST_XDG_CACHE_HOME 和 $HOST_XDG_STATE_HOME 环境变量，如果在主机上设置了自定义值。

请注意，$XDG_STATE_HOME 和 $HOST_XDG_STATE_HOME 仅受 Flatpak 1.13 及更高版本的支持。如果你的应用程序需要在较早版本的 Flatpak 上工作，你可以使用 --persist=.local/state 和 --unset-env=XDG_STATE_HOME finish 参数，这样即使稍后将 Flatpak 升级到 >1.13，应用程序也将使用正确的目录。

请注意，应用程序可以配置为使用非默认的基础目录位置（请参阅沙盒权限）。