Requisitos & convenções

O Flatpak deliberadamente possui o menor número de requisitos de aplicativos possível. No entanto, é esperado um pequeno número de convenções padrão de desktops Linux, principalmente para garantir que os aplicativos se integrem aos desktops e centros de aplicativos Linux. Os desenvolvedores também podem encontrar um pequeno número de convenções técnicas do Linux.

Informações sobre outras opções de integração de desktop podem ser encontradas em Integração de desktop.

Padrões esperados

Geralmente, espera-se que os aplicativos que usam o Flatpak cumpram os seguintes padrões. Os aplicativos que já tinham como alvo a área de trabalho Linux normalmente precisam fazer muito poucas alterações (se houver) para fazer isso.

IDs de aplicativo

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

O formato está no estilo DNS reverso, portanto, a primeira seção deve ser um domínio controlado pelo projeto e a seção final representa o projeto específico. Existem algumas exceções a isso, como extensões que usam o ID de aplicativo base do projeto que elas estendem em vez de suas próprias.

Como será visto abaixo e em seções futuras, espera-se que esse ID seja usado em vários lugares. Os desenvolvedores devem seguir as convenções de nomenclatura D-Bus padrão para nomes de barramento ao criar seus próprios IDs. Este formato já é recomendado pela especificação do arquivo de desktop e pela especificação do Appstream também.

Para alguns exemplos práticos de IDs inválidos

• org.exemplo.desktop

  Esse é um ID incorreto porque o padrão Appstream por motivos legados trata os IDs que terminam com .desktop como um caso especial que causa inconsistência. Por esse mesmo motivo, os sufixos .Desktop não devem ser usados para aplicativos recém-nomeados. Não hesite em repetir o nome do aplicativo, mesmo que ele já faça parte da seção de nomes de domínio do identificador (por exemplo, org.exemplo.Exemplo).

• 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

  Embora um projeto possa estar hospedado no GitHub ou GitLab, ele não tem controle sobre o domínio github.com ou gitlab.com. Em vez disso, você deve usar o io.github ou io.gitlab como mostrado acima.

• 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

Uma convenção legada de ter o .appdata.xml instalado em /app/share/appdata também é aceita, e o flatpak-builder verificará qualquer diretório com qualquer extensão.

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

Ícones de aplicativo

Espera-se que os aplicativos forneçam um ícone de aplicativo, usado para seu iniciador. Esses ícones devem ser fornecidos de acordo com a especificação do ícones do Freedesktop.

Os ícones devem ser nomeados com o ID do aplicativo, estar no formato PNG ou SVG e devem ser colocados no local padrão:

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

Por exemplo, o caminho para a versão 128✕128px do ícone do Dicionário do GNOME é:

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

Ícones devem estar em formato de quadrados, ou seja, sua largura e sua altura devem ser iguais. O tamanho máximo permitido pela especificação é 512x512px. Ícones SVG têm o tamanho 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.

Arquivos desktop

Os arquivos desktop são usados para fornecer ao ambiente informações sobre cada aplicativo. A especificação do Freedesktop fornece uma referência completa para a escrita de arquivos desktop e informações adicionais sobre eles está disponível online.

Os arquivos desktop devem ser nomeados com o ID do aplicativo, seguido pela extensão do arquivo .desktop, e devem ser colocados em /app/share/applications/. Por exemplo:

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

Um arquivo desktop mínimo deve conter pelo menos o comando name, exec do aplicativo, type, nome do ícone em icon e categories:

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

O comando desktop-file-validate pode ser usado para verificar erros nos arquivos 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.

Exportando através de extra-data

Os arquivos baixados através de extra-data são baixados apenas durante a instalação, pois ainda não estão disponíveis para o flatpak-builder exportar automaticamente durante o processo de compilação.

Ao usar extra-data, coloque todos os arquivos que devem ser exportados neste local:

/app/extra/export/share/

Por exemplo, se o Dicionário do GNOME usasse extra-data para baixar um ícone de 96x96, este seria o seu caminho:

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

Convenções técnicas

A seguir, são apresentadas convenções técnicas padrão usadas pelos desktops Flatpak e Linux. Aqueles com experiência em Linux provavelmente já estarão cientes deles. No entanto, os desenvolvedores que são novos no Linux podem achar algumas dessas informações úteis.

D-Bus

D-Bus é o framework IPC padrão usada em desktops Linux. Muitos aplicativos não precisarão usá-lo, mas o Flatpak fornece suporte a ele, caso seja necessário.

O D-Bus pode ser usado para iniciar e se comunicar com alguns serviços do sistema. Os aplicativos também podem fornecer seus próprios serviços D-Bus (ao fazer isso, o nome do serviço D-Bus deve ser o mesmo que o ID do aplicativo).

Layout de sistema de arquivos

Cada sandbox do Flatpak, que é o ambiente em que um aplicativo é executado, contém o sistema de arquivos do runtime do aplicativo. Isto segue as convenções padrão do sistema de arquivos Linux.

Por exemplo, a raiz do sandbox contém o diretório /etc para arquivos de configuração e /usr para utilitários e aplicativos multiusuário. Além disso, cada sandbox contém um diretório /app de nível superior, onde os arquivos do aplicativo estão localizados.

Diretórios base XDG

Diretórios base XDG são locais padrão para dados de aplicativos específicos do usuário. Os kits de ferramentas populares fornecem funções de conveniência para acessar os diretórios base do XDG. Esses incluem:

• Electron: os diretórios base XDG podem ser acessados com app.getPath

• Glib: fornece acesso aos diretórios base XDG através das funções g_get_user_cache_dir (), g_get_user_data_dir () e g_get_user_config_dir ()

• Qt: fornece acesso aos diretórios base XDG com a classe QStandardPaths

No entanto, os aplicativos que não estão usando um desses kits de ferramentas podem esperar encontrar seus diretórios base XDG nos seguintes locais:

Diretório base	Uso	Local padrão
XDG_CONFIG_HOME	Arquivos de configuração específicos do usuário	~/.var/app/<id-aplicativo>/config
XDG_DATA_HOME	Dados específicos do usuário	~/.var/app/<id-aplicativo>/data
XDG_CACHE_HOME	Dados não essenciais específicos do usuário	~/.var/app/<id-aplicativo>/cache
XDG_STATE_HOME	Dados de estado, tais como histórico de desfazimento	~/.var/app/<id-aplicativo>/.local/state

Por exemplo, Dicionário do GNOME vai armazenar dados específicos do usuário em:

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

Observe que os aplicativos podem ser configurados para usar locais de diretório base diferente do padrão (consulte Permissões de sandbox).