Манифесты🔗

Входными данными для flatpak-builder является файл JSON или YAML, который описывает параметры для создания приложения, а также инструкции для каждого из модулей, которые должны быть построены. Этот файл называется манифестом.

На этой странице представлена информация и руководство по использованию манифестов, включая объяснение наиболее общих параметров, которые можно указать. Перед чтением этого раздела рекомендуется ознакомиться с руководством в Создайте свой первый Flatpak и ознакомиться с Flatpak Builder.

Файлы манифеста должны получить названия с использованием идентификатора приложения. Например, файл манифеста для словаря GNOME называется org.gnome.Dictionary.yml. Эта страница использует этот файл манифеста, для всех своих примеров.

Полный список всех свойств, которые могут быть указаны в файлах манифеста, можно найти в Справочник команд Flatpak Builder, а также на странице руководства``flatpak-manifest``.

Основные свойства🔗

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.

Например, манифест GNOME Dictionary включает:

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

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

Переименование файла🔗

Экспорт - это файлы приложения, которые доступны хосту, и включают такие вещи, как файл и значок приложения .desktop.

Имена файлов, экспортируемых Flatpak, должны иметь префикс с использованием идентификатора приложения, например org.gnome.Dictionary.desktop. Лучший способ сделать это - переименовать эти файлы прямо в папке приложения.

Если переименование экспортируемых файлов для использования идентификатора приложения невозможно, flatpak-builder позволяет их переименовывать в процессе сборки. Это можно сделать, указав одно из следующих свойств в манифесте:

  • rename-icon - переименовать значок приложения

  • rename-desktop-file - переименовать имя файла .desktop

  • rename-appdata-file - rename the MetaInfo file

Каждое из этих свойств принимает имя исходного файла, который нужно переименовать. Затем flatpak-builder автоматически переименовывает файл в соответствии с идентификатором приложения. Обратите внимание, что этот метод переименования может вызвать внутренние конфликты именования, и поэтому переименование файлов в дереве является наиболее надежным подходом.

Завершение🔗

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

Раздел манифеста окончательной обработки использует свойство finish-args, которое можно увидеть в файле манифеста словаря:

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 Разрешения песочницы.

Очистка🔗

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.

Во-первых, можно включить список шаблонов имен файлов:

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.

Модули🔗

В списке модулей указывается каждый из модулей, которые должны быть построены как часть процесса сборки. Один из этих модулей - это само приложение, а другие модули - это зависимости и библиотеки, которые входят в состав Flatpak. В то время как простые приложения могут указывать только один или два модуля и, следовательно, иметь короткие разделы модулей, некоторые приложения могут объединять множество модулей и, следовательно, иметь длинные разделы модулей.

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

Как видно, у каждого указанного модуля есть имя (которое может быть присвоено произвольно) и список источники У каждого источника есть тип, и доступные типы включают:

  • archive - .tar или .zip архивные файлы

  • git - Репозитории Git

  • bzr - репозитории Bazaar

  • file - локальные/удаленные файлы (они копируются в исходный каталог)

  • dir - локальные каталоги (они копируются в исходный каталог)

  • script - список команд оболочки (они помещаются в файл сценария оболочки)

  • shell - массив команд оболочки, которые запускаются во время извлечения исходного кода

  • patch - патч (применяются к исходному каталогу)

  • extra-data - данные, которые можно загрузить во время установки; может включать архивные или пакетные файлы

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

Поддерживаемые системы сборки🔗

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

Также доступен «простой» метод сборки, который позволяет указать серию команд.

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.

Примечание

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

Общие модули🔗

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🔗

Flatpak Builder Tools (или flatpak-builder-tools) <https://github.com/flatpak/flatpak-builder-tools> — это набор скриптов, помогающих использовать flatpak-builder. В этом репозитории каждый каталог содержит инструкции по созданию манифеста для соответствующей платформы.

Примеры манифестов🔗

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