Требования и соглашения¶

Flatpak сознательно делает как можно меньше требований к приложениям. Однако ожидается небольшое количество стандартных соглашений о рабочих столах Linux, в первую очередь для обеспечения интеграции приложений с рабочими столами Linux и центрами приложений. Разработчики также могут столкнуться с небольшим количеством технических соглашений Linux.

Информацию о дополнительных возможностях интеграции с рабочим столом можно найти в Интеграция с рабочим столом.

Ожидаемые стандарты¶

Обычно ожидается, что приложения, использующие Flatpak, будут соответствовать следующим стандартам. Приложениям, которые ранее были ориентированы на рабочий стол Linux, для этого обычно потребуется внести очень мало изменений (если они вообще будут внесены).

Идентификаторы приложений¶

As described in Использование Flatpak, Flatpak requires each application to have a unique identifier, which has a form such as org.example.app.

Формат выполнен в стиле обратного DNS, поэтому первый раздел должен быть доменом, контролируемым проектом, а завершающий раздел представляет конкретный проект. Есть некоторые исключения из этого, такие как расширения, использующие базовый идентификатор приложения проекта, который они расширяют, а не свой собственный.

Как будет показано ниже и в следующих разделах, ожидается, что этот идентификатор будет использоваться в ряде мест. Разработчики должны следовать стандартным соглашениям об именах D-Bus для имен шин <https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names>`_ при создании своих собственных идентификаторов. Этот формат уже рекомендован Спецификацией файла рабочего стола и Спецификацией потока приложений.

Некоторые практические примеры плохих идентификаторов

org.example.desktop

Это неправильный идентификатор, поскольку стандарт Appstream по устаревшим причинам рассматривает идентификаторы, оканчивающиеся на .desktop, как особый случай, вызывающий несогласованность. По этой же причине суффиксы .Desktop не следует использовать для новых названий приложений. Не стесняйтесь повторять имя приложения, даже если оно уже является частью раздела доменного имени идентификатора (например, 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

Хотя проект может быть размещен на GitHub или GitLab, он не имеет никакого контроля над доменом github.com или gitlab.com. Вместо этого вы должны использовать io.github или io.gitlab как показано выше.
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

Устаревшее соглашение об установке .appdata.xml в /app/share/appdata также принимается, и flatpak-builder будет проверять любой каталог с любым расширением.

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

Значки приложений¶

Ожидается, что приложения будут предоставлять значок приложения, который используется для запуска их приложений. Эти значки должны предоставляться в соответствии со спецификацией значков Freedesktop <https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html>`_.

Иконки должны называться с идентификатором приложения, быть в формате PNG или SVG и должны быть размещены в стандартном месте:

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

Например, путь к версии значка GNOME Dictionary размером 128✕128 пикселей:

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

Иконки должны быть квадратной формы, т.е. их ширина и высота должны быть одинаковыми. Максимальный размер, разрешенный спецификацией, составляет 512x512px. SVG иконки имеют размер масштабируемый:

/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.

Файлы рабочего стола¶

Файлы рабочего стола используются для предоставления среде рабочего стола информации о каждом приложении. Спецификация Freedesktop предоставляет полный справочник по написанию файлов рабочего стола и дополнительную информацию о них доступен онлайн.

Файлы рабочего стола должны называться с идентификатором приложения, за которым следует расширение файла .desktop, и должны быть помещены в /app/share/applications/. Например:

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

Минимальный файл рабочего стола должен содержать как минимум имя приложения, команду exec, тип, имя значка и категории:

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

Команду desktop-file-validate можно использовать для проверки наличия ошибок в файлах рабочего стола.

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.

Экспорт через «дополнительные данные»¶

Файлы, загруженные через «extra-data», загружаются только при установке, поэтому они еще недоступны для «flatpak-builder» для автоматического экспорта в процессе сборки.

При использовании «extra-data» поместите все файлы, которые необходимо экспортировать, в это место:

/app/extra/export/share/

Например, если словарь GNOME использовал «extra-data» для загрузки значка 96x96, это будет его путь:

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

Технические соглашения¶

Ниже приведены стандартные технические соглашения, используемые рабочими столами Flatpak и Linux. Те, у кого есть опыт работы с Linux, вероятно, уже знают о них. Однако разработчикам, которые не знакомы с Linux, часть этой информации может оказаться полезной.

D-Bus¶

D-Bus — это стандартная структура IPC, используемая на настольных компьютерах Linux. Многим приложениям не нужно его использовать, но Flatpak поддерживает его, если это необходимо.

D-Bus можно использовать для запуска приложений и связи с некоторыми системными службами. Приложения также могут предоставлять свои собственные службы D-Bus (при этом ожидается, что имя службы D-Bus будет таким же, как идентификатор приложения).

Схема файловой системы¶

Каждая песочница Flatpak, представляющая собой среду, в которой запускается приложение, содержит файловую систему среды выполнения приложения. Это соответствует стандартным соглашениям о файловой системе Linux.

Например, корень песочницы содержит каталог /etc для файлов конфигурации и /usr для многопользовательских утилит и приложений. В дополнение к этому каждая песочница содержит каталог верхнего уровня /app, в котором находятся собственные файлы приложения.

Базовые каталоги XDG¶

Базовые каталоги XDG являются стандартными расположениями для данных приложений, специфичных для пользователя. Популярные наборы инструментов предоставляют удобные функции для доступа к базовым каталогам XDG. К ним относятся:

Electron: доступ к базовым каталогам XDG можно получить с помощью app.getPath
Glib: обеспечивает доступ к базовым каталогам XDG через функции g_get_user_cache_dir(), g_get_user_data_dir(), g_get_user_config_dir()
Qt: предоставляет доступ к базовым каталогам XDG с помощью QStandardPaths <https://doc.qt.io/qt-5/qstandardpaths.html>`_

Однако приложения, которые не используют один из этих наборов инструментов, могут найти свои базовые каталоги XDG в следующих местах:

Базовый каталог	Применение	Местоположение по умолчанию
XDG_CONFIG_HOME	Пользовательские файлы конфигурации	~/.var/app/<app-id>/config
XDG_DATA_HOME	Пользовательские данные	~/.var/app/<app-id>/data
XDG_CACHE_HOME	Несущественные пользовательские данные	~/.var/app/<app-id>/cache
XDG_STATE_HOME	Данные состояния, такие как история отмен	~/.var/app/<app-id>/.local/state

Например, словарь GNOME будет хранить пользовательские данные в:

~/.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.

Обратите внимание, что приложения могут быть настроены на использование базовых каталогов не по умолчанию (см. разрешения для песочницы).