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: '48'
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.

Limpeza🔗

The cleanup property can be used to remove files produced by the build process that are not wanted as part of the application, such as headers or developer documentation. Two properties in the manifest file are used for this. This can be either done for each modules in which case only names created by that module will be matched or at the toplevel which will match anything created in the entire manifest.

Items starting with / are taken to be relative to the prefix, so /include will cleanup /app/include, otherwise it matches the basename.

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

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

A cleanup with *, at the module level will cleanup all artifacts built from that module. This is often useful for build dependencies of a module that does not need to be shipped in the final Flatpak package:

cleanup:
  - '*'

The cleanup-commands property can be a list of cleanup commands:

cleanup-commands:
  - 'find /app/bin -mindepth 1 -maxdepth 1  -name 'rpm*' ! -name 'rpm2cpio' -delete'

Note that, instead of cleaning up unnecessary files, it is often better to build less components through config-opts, build-commands, make-args. For example, if the application does not need documentation files or manpages, it’s best to stop building them. This should make the build faster in some cases and reduce the need for excessive cleanups.

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.

Modules are built in the order they are declared in the manifest. If any module changes, that module and all the subsequent modules below it will be rebuilt, otherwise it should use the cache.

The general recommendation is to place the “main” module, usually the module for the main application as the last module in the manifest but if there is a module which gets updated often and is independent from the rest, that module can also be placed as the last module to avoid rebuilding everything else.

Modules can either be nested to clearly show the dependency structure or be linearly declared.

# Nested

finish-args:
  - --share=ipc
  - --socket=fallback-x11
  - --socket=wayland
  - --socket=pulseaudio

  modules:
    - name: video-player-app
      buildsystem: meson
      config-opts:
        - --buildtype=release
      cleanup:
        - /share/man
      sources:
        - type: archive
          url: https://example.com/release.tar.gz
          sha256: 216656c4495bb3ca02dc4ad9cf3da8e8f15c8f80e870eeac8eb1eedab4c3788b
      modules:
        - name: libmpv
          buildsystem: meson
          config-opts:
            - -Dlibmpv=true
          sources:
            - type: archive
              url: https://example.com/mpv.tar.gz
              sha256: 2ca92437affb62c2b559b4419ea4785c70d023590500e8a52e95ea3ab4554683
          modules:
            - "shared-modules/lua5.1/lua-5.1.5.json"

            - name: libv4l2
              buildsystem: meson
              sources:
                - type: archive
                  url: url: https://example.com/libv4l2.tar.gz
                  sha256: 0fa075ce59b6618847af6ea191b6155565ccaa44de0504581ddfed795a328a82
# Linear

finish-args:
  - --share=ipc
  - --socket=fallback-x11
  - --socket=wayland
  - --socket=pulseaudio

  modules:
    - "shared-modules/lua5.1/lua-5.1.5.json"

    - name: libv4l2
      buildsystem: meson
      sources:
        - type: archive
          url: url: https://example.com/libv4l2.tar.gz
          sha256: 0fa075ce59b6618847af6ea191b6155565ccaa44de0504581ddfed795a328a82

    - name: libmpv
      buildsystem: meson
       config-opts:
         - -Dlibmpv=true
      sources:
        - type: archive
          url: https://example.com/mpv.tar.gz
          sha256: 2ca92437affb62c2b559b4419ea4785c70d023590500e8a52e95ea3ab4554683

    - name: video-player-app
      buildsystem: meson
      config-opts:
        - --buildtype=release
      cleanup:
        - /share/man
      sources:
        - type: archive
          url: https://example.com/release.tar.gz
          sha256: 216656c4495bb3ca02dc4ad9cf3da8e8f15c8f80e870eeac8eb1eedab4c3788b

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

Different properties are available for each source type, which are listed in the Module Sources.

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.

Each of the above buildsystem sets up the installation prefix, libdir etc. and runs a series of commands to configure (meson setup, or ./autogen.sh, ./configure or cmake), build, install (ninja install, make install etc.) and optionally run tests (make check, ninja test etc.).

Thus they can also be achieved by using the simple buildsystem and manually specifying the commands.

Nota

Using the proper buildsystem is almost always preferred rather than manually handling the correct setup.

An example is provided below.

# Using autotools without configure
- name: ffnvcodec
  buildsystem: autotools
  no-autogen: true
  make-install-args:
    - PREFIX=/app
  sources:
    - type: git
      url: https://github.com/FFmpeg/nv-codec-headers.git
      commit: 43d91706e097565f57b311e567f0219838bcc2f6
      tag: n11.1.5.3

# Using meson buildsystem
- name: libdrm
  buildsystem: meson
  builddir: true
  config-opts:
    - -Dtests=false
  sources:
    - type: git
      url: https://gitlab.freedesktop.org/mesa/drm.git
      tag: libdrm-2.4.124

# Using simple

- name: ffnvcodec
  buildsystem: simple
  build-commands:
    - make -j$FLATPAK_BUILDER_N_JOBS PREFIX=/app install
  sources:
    - type: git
      url: https://github.com/FFmpeg/nv-codec-headers.git
      commit: 43d91706e097565f57b311e567f0219838bcc2f6
      tag: n11.1.5.3

- name: libdrm
  buildsystem: simple
  build-commands:
    - meson setup builddir --prefix=/app --libdir=/app/lib -Dtests=false
    - ninja -C builddir install
  sources:
    - type: git
      url: https://gitlab.freedesktop.org/mesa/drm.git
      tag: libdrm-2.4.124

Shared Modules🔗

Flathub contains a shared modules repository containing build manifests for commonly used modules. These are usally shared by apps on Flathub and maintained in a single place. The repository is intended to be used as a git submodule.

Please see the readme for details on how to use this.

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🔗

Flathub hosts a large collection of applications and the respective manifests can be browsed and searched via GitHub.