Manifestos¶

A entrada para flatpak-builder é um arquivo JSON ou YAML que descreve os parâmetros para a construção de um aplicativo, bem como instruções para cada um dos módulos a serem compilados. Este arquivo é chamado de manifesto.

Esta página fornece informações e orientações sobre como usar manifestos, incluindo uma explicação dos parâmetros mais comuns que podem ser especificados. Recomenda-se ter seguido o tutorial Compilando seu primeiro Flatpak antes de ler esta seção e estar familiarizado com Flatpak Builder.

Os arquivos de manifesto devem ser nomeados usando o ID do aplicativo. Por exemplo, o arquivo de manifesto do Dicionário do GNOME é denominado org.gnome.Dictionary.yml. Esta página usa este arquivo de manifesto para todos os seus exemplos.

Uma lista completa de todas as propriedades que podem ser especificadas nos arquivos de manifesto pode ser encontrada na Referência de comandos do Flatpak Builder, bem como na página do manual flatpak-manifest.

Propriedades básicas¶

Each manifest file should specify basic information about the application that is to be built, including the id, runtime, runtime-version, sdk and command parameters. These properties are typically specified at the beginning of the file.

Por exemplo, o manifesto do Dicionário do GNOME inclui:

id: org.gnome.Dictionary
runtime: org.gnome.Platform
runtime-version: '45'
sdk: org.gnome.Sdk
command: gnome-dictionary

A especificação de um runtime e sua versão permite que o runtime necessário ao seu aplicativo seja instalado automaticamente nos sistemas dos usuários.

Renomeação de arquivo¶

Exportações são arquivos de aplicativos que são disponibilizados para o host e incluem itens como o arquivo .desktop e o ícone do aplicativo.

Os nomes dos arquivos que são exportados por um Flatpak devem ser prefixados usando o ID do aplicativo, como org.gnome.Dictionary.desktop. A melhor maneira de fazer isso é renomear esses arquivos diretamente no código-fonte do aplicativo.

Se não for possível renomear arquivos exportados para usar o ID do aplicativo, o flatpak-builder permitirá que eles sejam renomeados como parte do processo de compilação. Isso pode ser feito especificando uma das seguintes propriedades no manifesto:

rename-icon – renomeia o ícone do aplicativo
rename-desktop-file – renomeia o arquivo .desktop
rename-appdata-file - rename the MetaInfo file

Cada uma dessas propriedades aceita o nome do arquivo de origem a ser renomeado. flatpak-builder renomeia automaticamente o arquivo para corresponder ao ID do aplicativo. Observe que esse método de renomeação pode introduzir conflitos de nomenclatura internos e que renomear arquivos na árvore é, portanto, a abordagem mais confiável.

Acabamento¶

Os aplicativos executados com o Flatpak têm acesso extremamente limitado ao ambiente host por padrão, mas os aplicativos requerem acesso a recursos fora de sua caixa de proteção para serem úteis. O acabamento é o estágio de compilação em que as permissões do sandbox do aplicativo são especificadas, a fim de dar acesso a esses recursos.

A seção de manifesto de acabamento usa a propriedade finish-args, que pode ser vista no arquivo de manifesto do Dicionário:

finish-args:
  # X11 + XShm access
  - --share=ipc
  - --socket=fallback-x11
  # Wayland access
  - --socket=wayland
  # GPU acceleration if needed
  - --device=dri
  # Needs to talk to the network:
  - --share=network
  # Needs to save files locally
  - --filesystem=xdg-documents

Guidance on which permissions to use can be found in the Permissões de sandbox.

Se você está se perguntando sobre o último argumento de acabamento (finish), consulte esta postagem do blog.

Limpeza¶

A propriedade cleanup pode ser usada para remover arquivos produzidos pelo processo de construção que não são desejados como parte do aplicativo, como cabeçalhos ou documentação do desenvolvedor. Duas propriedades no arquivo de manifesto são usadas para isso.

Primeiro, uma lista de padrões de nome de arquivo pode ser incluída:

cleanup:
  - '/include'
  - '/bin/foo-*'
  - '*.a'

A segunda propriedade de limpeza é uma lista de comandos que são executados durante a fase de cleanup:

cleanup-commands:
  - 'sed s/foo/bar/ /bin/app.sh'

As propriedades de limpeza podem ser definidas por módulo, caso em que apenas os nomes de arquivos criados por esse módulo específico serão correspondidos.

Módulos¶

A lista de módulos especifica cada um dos módulos que devem ser compilados como parte do processo de compilação. Um desses módulos é o próprio aplicativo e outros módulos são dependências e bibliotecas que fazem parte do Flatpak. Embora aplicativos simples possam especificar apenas um ou dois módulos e, portanto, tenham seções de módulos curtos, alguns aplicativos podem agrupar vários módulos e, portanto, ter seções de módulos longas.

A seção de módulos do Dicionário do GNOME é curta, pois contém apenas o próprio aplicativo e se parece com:

modules:
  - name: gnome-dictionary
    buildsystem: meson
    config-opts:
      - -Dbuild_man=false
    sources:
      - type: archive
        url: https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.1.tar.xz
        sha256: 16b8bc248dcf68987826d5e39234b1bb7fd24a2607fcdbf4258fde88f012f300
      - type: patch
        path: appdata_oars.patch

Como pode ser visto, cada módulo listado possui um name (que pode ser atribuído livremente) e uma lista de sources. Cada fonte possui um type, e os tipos disponíveis incluem:

archive – arquivos em .tar ou .zip

git – repositórios Git

bzr – repositórios Bazaar

file – arquivos locais/remotos (esses são copiados para dentro do diretório fonte)

dir – diretórios locais (esses são copiados para dentro do diretório fonte)

script – um vetor de comandos shell (esses são colocados em um arquivo de script shell)

shell – um vetor de comandos shell que são executados durante a extração do fonte

patch – um patch (são aplicados ao diretório fonte)

extra-data – dados que podem ser baixados em tempo de instalação; esto pode incluir um arquivo compactado ou arquivos de pacote

Diferentes propriedades estão disponíveis para cada tipo de fonte, listadas em Referência de comandos do Flatpak Builder.

Suporte a sistemas de compilação¶

Os módulos podem ser compilados com uma variedade de sistemas de construção, incluindo:

Um método de compilação “simples” também está disponível, o que permite que uma série de comandos seja especificada.

Shared Modules¶

Shared Modules (ou shared-modules) é um repositório contendo vários manifestos para compilar bibliotecas comuns. Destina-se a ser usado como um submódulo git.

Para adicioná-lo ao seu repositório, execute este comando:

git submodule add https://github.com/flathub/shared-modules.git

Em seguida, adicione o módulo desejado. Neste exemplo, usaremos gtk2:

modules:
  - shared-modules/gtk2/gtk2.json

Para atualizar o submódulo, execute este comando:

git submodule update --remote --merge

Para remover o submódulo, execute estes comandos:

git submodule deinit -f -- shared-modules
rm -rf .git/modules/shared-modules
git rm -f shared-modules
rm .gitmodules

Flatpak Builder Tools¶

Flatpak Builder Tools (ou flatpak-builder-tools) é uma coleção de scripts para ajudar a usar o flatpak-builder. Nesse repositório, cada diretório contém instruções para gerar um manifesto para a respectiva plataforma.

Exemplo de manifestos¶

Um manifesto completo para o Dicionário do GNOME criado a partir do Git. Também é possível navegar por todos os manifestos hospedados pelo Flathub.