Справочник манифеста aft-app#

Манифест aft-app — YAML-файл, описывающий все параметры сборки Flatpak-приложения из deb-пакета. Манифест передаётся команде aft-app build и определяет метаданные, источник, зависимости, разрешения, параметры подписи и экспорта.

Файл поддерживает многодокументный формат YAML: несколько манифестов в одном файле, разделённых символами ---.

Корневые поля#

version: "1.0"
metadata: { }
runtime: { }
source: { }
dependencies: { }
files: { }
permissions: { }
extensions: [ ]
commands: { }
build: { }
export: { }
standalone: { }

version: Версия формата манифеста. Обязательное поле. Текущее значение: "1.0".

Секция metadata#

Определяет идентификационные данные приложения.

metadata:
  id: org.example.MyApp
  name: My Application
  version: 1.0.0
  arch: amd64
  branch: stable
  tags:
    - proprietary
    - network

Поле	Тип	Обязательное	Описание
`id`	строка	Да	Идентификатор в формате обратного DNS (`org.example.MyApp`). Должен содержать минимум одну точку.
`name`	строка	Да	Отображаемое имя приложения.
`version`	строка	Да	Версия приложения.
`arch`	строка	Да	Архитектура. Допустимые значения: `amd64`, `x86_64`, `arm64`, `aarch64`, `i386`, `armhf`.
`branch`	строка	Нет	Ветка в репозитории. По умолчанию: `stable`.
`tags`	массив строк	Нет	Теги AppStream (`proprietary`, `network`, `gui` и др.).

Секция runtime#

Определяет рантайм, на котором будет работать приложение.

runtime:
  id: org.example.Platform
  version: stable
  sdk: org.example.Sdk

Поле	Тип	Обязательное	Описание
`id`	строка	Да	Идентификатор рантайма.
`version`	строка	Да	Версия (ветка) рантайма.
`sdk`	строка	Нет	Идентификатор SDK. Если не указан, формируется автоматически: к идентификатору рантайма добавляется суффикс `Sdk` (например, `org.example.Platform` → `org.example.PlatformSdk`).

Примечание

Секция runtime обязательна, если не включён автономный режим (standalone.enabled: true).

Секция source#

Определяет источник файлов приложения. Структура секции зависит от значения поля type.

Тип repository (по умолчанию)#

source:
  type: repository
  repository:
    package: myapp
    version: latest
    components:
      - main

Поле	Тип	Обязательное	Описание
`package`	строка	Да	Имя deb-пакета в репозитории.
`version`	строка	Нет	Версия пакета. По умолчанию: `latest`.
`components`	массив строк	Нет	Компоненты APT-репозитория. По умолчанию: `["main"]`.

Тип local#

source:
  type: local
  local:
    path: /path/to/myapp_1.0_amd64.deb

Поле	Тип	Обязательное	Описание
`path`	строка	Да	Абсолютный путь к `.deb`-файлу.

Тип url#

source:
  type: url
  url:
    address: https://example.com/downloads/myapp_1.0_amd64.deb

Поле	Тип	Обязательное	Описание
`address`	строка	Да	URL для загрузки файла.

Тип tar#

source:
  type: tar
  tar:
    path: /path/to/app.tar.xz
    packages:
      - libc6
      - libssl3
    layout:
      - pattern: "*.so*"
        dest: lib/
      - pattern: myapp
        dest: bin/

Поле	Тип	Обязательное	Описание
`path`	строка	Да	Путь к tar-архиву. Поддерживаются форматы `.tar.gz` и `.tar.xz`.
`packages`	массив строк	Нет	Перечень имён пакетов для записи в SBOM. Автоматический анализ зависимостей для типа `tar` не выполняется.
`layout`	массив объектов	Нет	Правила размещения файлов из архива. Каждый элемент содержит поля `pattern` (glob-шаблон) и `dest` (целевой подкаталог в `files/`). Оба поля обязательны.

Секция dependencies#

Управляет анализом зависимостей deb-пакета.

dependencies:
  analyze: true
  includeRecommends: false
  includeSuggests: false
  exclude:
    - some-unwanted-package
  additional:
    - extra-needed-lib
  force:
    - specific-version-lib

Поле	Тип	По умолчанию	Описание
`analyze`	булево	`true`	Включить автоматический анализ зависимостей через `apt-cache depends`.
`includeRecommends`	булево	`false`	Включить рекомендуемые пакеты (`Recommends`).
`includeSuggests`	булево	`false`	Включить предлагаемые пакеты (`Suggests`).
`exclude`	массив строк	`[]`	Пакеты, исключаемые из списка зависимостей. Применяется после анализа.
`additional`	массив строк	`[]`	Пакеты, добавляемые к списку зависимостей принудительно.
`force`	массив строк	`[]`	Пакеты, загружаемые даже при их наличии в рантайме. Используется, когда приложению требуется версия библиотеки, отличная от версии в рантайме.

Секция files#

Определяет команду запуска и файлы интеграции с рабочим столом.

files:
  command: myapp
  desktop: /usr/share/applications/myapp.desktop
  metainfo: /usr/share/metainfo/org.example.MyApp.metainfo.xml
  icons-dir: share/icons
  icons:
    - size: 128x128
      path: share/icons/hicolor/128x128/apps/myapp.png
    - size: 64x64
      path: share/icons/hicolor/64x64/apps/myapp.png
  cleanPatterns:
    - share/doc/*
    - share/man/*

Поле	Тип	Обязательное	Описание
`command`	строка	Да	Команда запуска приложения (имя исполняемого файла или путь относительно `files/`).
`desktop`	строка	Нет	Путь к файлу `.desktop` внутри распакованного deb-пакета.
`metainfo`	строка	Нет	Путь к файлу AppStream-метаданных (`.metainfo.xml` или `.appdata.xml`).
`icons-dir`	строка	Нет	Каталог с иконками (альтернатива массиву `icons`).
`icons`	массив объектов	Нет	Список иконок с указанием размера и пути. Каждый элемент содержит `size` (например, `128x128`) и `path`.
`cleanPatterns`	массив строк	Нет	Glob-шаблоны файлов, удаляемых из `files/` после распаковки.

Примечание

Поля icons-dir и icons взаимоисключающие. Если указаны оба, приоритет имеет icons.

Секция permissions#

Определяет разрешения песочницы. Все поля являются необязательными.

permissions:
  sockets:
    - x11
    - wayland
    - pulseaudio
  devices:
    - dri
  shares:
    - network
    - ipc
  filesystems:
    - home
    - xdg-documents:ro
  persist:
    - .config
    - .cache
  env:
    - LANG=ru_RU.UTF-8
    - QT_QPA_PLATFORM=wayland
  unset-env:
    - DISPLAY
  own-name:
    - org.example.MyApp
  talk-name:
    - org.freedesktop.Notifications
  system-own-name:
    - org.example.SystemService
  system-talk-name:
    - org.freedesktop.UDisks2
  no-talk-name: []
  no-system-talk-name: []
  allow:
    - bluetooth
  inherit-extensions: []

Поле	Тип	Описание
`sockets`	массив строк	Доступ к сокетам: `x11`, `wayland`, `fallback-x11`, `pulseaudio`, `cups`, `pcsc`, `ssh-auth`, `session-bus`, `system-bus`.
`devices`	массив строк	Доступ к устройствам: `dri`, `kvm`, `shm`, `all`.
`shares`	массив строк	Разделяемые ресурсы: `network`, `ipc`.
`filesystems`	массив строк	Доступ к файловой системе. Значения: `home`, `host`, `host-os`, `host-etc`, `xdg-desktop`, `xdg-documents`, `xdg-download`, `xdg-music`, `xdg-pictures`, `xdg-videos`, произвольный путь. Суффиксы: `:ro`, `:rw`, `:create`.
`persist`	массив строк	Персистентные каталоги в `~/.var/app/<id>/`.
`env`	массив строк	Переменные окружения в формате `КЛЮЧ=ЗНАЧЕНИЕ`.
`unset-env`	массив строк	Имена переменных окружения, удаляемых из песочницы.
`own-name`	массив строк	Имена на сессионной шине D-Bus, занимаемые приложением.
`talk-name`	массив строк	Имена на сессионной шине D-Bus, к которым приложение обращается.
`system-own-name`	массив строк	Имена на системной шине D-Bus (own).
`system-talk-name`	массив строк	Имена на системной шине D-Bus (talk).
`no-talk-name`	массив строк	Запрет обращения к именам на сессионной шине.
`no-system-talk-name`	массив строк	Запрет обращения к именам на системной шине.
`allow`	массив строк	Дополнительные разрешения: `bluetooth`, `devel`.
`inherit-extensions`	массив строк	Расширения рантайма, наследуемые приложением.

Предупреждение

Если в манифесте не указаны sockets, devices и filesystems, валидатор выведет предупреждение: приложение может не работать без доступа к графической подсистеме и устройствам.

Секция extensions#

Определяет точки расширений приложения (массив объектов).

extensions:
  - name: org.example.MyApp.Plugin
    directory: share/app-plugins
    version: "1.0"
    autodelete: false
    no-autodownload: false
    subdirectories: false

Поле	Тип	Обязательное	Описание
`name`	строка	Да	Имя расширения (обратный DNS).
`directory`	строка	Да	Каталог монтирования расширения внутри приложения.
`version`	строка	Нет	Версия расширения.
`versions`	строка	Нет	Несколько версий через точку с запятой: `"1.0;1.1;2.0"`.
`autodelete`	булево	Нет	Удалять расширение при удалении приложения. По умолчанию: `false`.
`no-autodownload`	булево	Нет	Не загружать расширение автоматически. По умолчанию: `false`.
`locale-subset`	булево	Нет	Расширение является подмножеством локализации. По умолчанию: `false`.
`subdirectories`	булево	Нет	Создавать подкаталоги для вариантов расширения. По умолчанию: `false`.
`add-ld-path`	строка	Нет	Путь, добавляемый в `LD_LIBRARY_PATH`.
`download-if`	строка	Нет	Условие загрузки расширения.
`enable-if`	строка	Нет	Условие активации расширения.
`autoprune-unless`	строка	Нет	Условие, предотвращающее автоматическое удаление.
`merge-dirs`	строка	Нет	Каталоги для объединения с родительским (через точку с запятой).
`subdirectory-suffix`	строка	Нет	Суффикс подкаталогов вариантов.

Секция commands#

Определяет команды, выполняемые на различных этапах сборки.

commands:
  pre-export:
    - sed -i 's/oldstring/newstring/g' files/bin/wrapper.sh
    - rm -rf files/share/doc
    - chmod +x files/bin/helper.sh

Поле	Тип	Описание
`pre-export`	массив строк	Команды, выполняемые в сборочном каталоге (`appDir`) перед экспортом в репозиторий. Рабочий каталог содержит `files/`, `export/` и `metadata`.

Секция build#

Управляет параметрами процесса сборки.

build:
  sbom: true
  cache: true
  cacheDir: ~/.cache/aft-app
  parallel: 4
  bsign:
    enabled: false
    key: ""
    passphraseFile: ""
    detached: false
    detachedPath: ""
    elfOnly: true
    exportKey: true
    useBsignIntegrator: false
    password: ""

Параметры верхнего уровня#

Поле	Тип	По умолчанию	Описание
`sbom`	булево	`true`	Генерировать SBOM (Software Bill of Materials) в формате CycloneDX.
`cache`	булево	`true`	Использовать кеш загруженных пакетов.
`cacheDir`	строка	`~/.cache/aft-app`	Каталог для хранения кеша.
`parallel`	число	`4`	Количество параллельных загрузок пакетов.

Подсекция bsign#

Управляет подписью ELF-файлов.

Поле	Тип	По умолчанию	Описание
`enabled`	булево	`false`	Включить подпись ELF-файлов.
`key`	строка	`""`	Идентификатор GPG-ключа для bsign.
`passphraseFile`	строка	`""`	Путь к файлу с паролем ключа (для пакетного режима).
`detached`	булево	`false`	Использовать отделённые подписи (флаг `-D`).
`detachedPath`	строка	`""`	Каталог для сохранения отделённых подписей (флаг `-T`).
`elfOnly`	булево	`true`	Встраивать подпись в ELF-секцию файла (флаг `-E`).
`exportKey`	булево	`true`	Экспортировать публичный GPG-ключ в рантайм (`usr/share/astra-keys/`).
`useBsignIntegrator`	булево	`false`	Использовать `bsign-integrator` вместо `bsign`.
`password`	строка	`""`	Пароль для `bsign-integrator`.

Секция export#

Определяет параметры экспорта в OSTree-репозиторий.

export:
  repository: ./repo
  gpgSign: ""
  gpgHomedir: ~/.gnupg
  stable: true
  collection-id: ""
  generate-static-deltas: false
  prune: false

Поле	Тип	По умолчанию	Описание
`repository`	строка	`./repo`	Путь к OSTree-репозиторию. Создаётся автоматически при отсутствии.
`gpgSign`	строка	`""`	Идентификатор GPG-ключа для подписи коммита. Пустая строка — без подписи.
`gpgHomedir`	строка	`~/.gnupg`	Каталог с GPG-ключами.
`stable`	булево	`true`	Использовать ветку `stable`.
`collection-id`	строка	`""`	Collection ID репозитория. Защищает от подмены репозитория.
`generate-static-deltas`	булево	`false`	Генерировать статические дельты для эффективных обновлений.
`prune`	булево	`false`	Удалить устаревшие объекты из репозитория после экспорта.

Секция standalone#

Управляет автономным режимом (встроенный рантайм). При включении aft-app автоматически создаёт фиктивный рантайм и SDK с символическими ссылками на /app/, а содержимое rootfs импортирует в приложение. Подробнее — в разделе aft-app: сборка приложений из deb-пакетов.

standalone:
  enabled: false
  rootfs: /path/to/rootfs

Поле	Тип	По умолчанию	Описание
`enabled`	булево	`false`	Включить автономный режим.
`rootfs`	строка	`""`	Путь к корневой файловой системе. Обязательно при `enabled: true`. Каталог должен содержать `usr/` с библиотеками.

Примечание

Секция runtime при включённом автономном режиме необязательна. Если она не указана, идентификаторы формируются автоматически: <metadata.id>.Platform (рантайм) и <metadata.id>.Sdk (SDK), версия берётся из metadata.branch или stable.

Полный пример манифеста#

version: "1.0"

metadata:
  id: org.example.TextEditor
  name: Text Editor
  version: 2.4.1
  arch: amd64
  branch: stable
  tags:
    - gui
    - editor

runtime:
  id: org.example.Platform
  version: stable

source:
  type: repository
  repository:
    package: texteditor
    version: latest
    components:
      - main

dependencies:
  analyze: true
  includeRecommends: false
  includeSuggests: false
  exclude:
    - texteditor-dbg
  additional:
    - libhunspell-dev
  force: []

files:
  command: texteditor
  desktop: /usr/share/applications/texteditor.desktop
  metainfo: /usr/share/metainfo/org.example.TextEditor.metainfo.xml
  icons-dir: share/icons
  cleanPatterns:
    - share/doc/*
    - share/man/*

permissions:
  sockets:
    - x11
    - wayland
    - pulseaudio
  devices:
    - dri
  shares:
    - ipc
    - network
  filesystems:
    - home
  persist:
    - .config/texteditor
  env:
    - LANG=ru_RU.UTF-8
  own-name:
    - org.example.TextEditor
  talk-name:
    - org.freedesktop.Notifications

commands:
  pre-export:
    - chmod +x files/bin/texteditor-wrapper.sh

build:
  sbom: true
  cache: true
  parallel: 4
  bsign:
    enabled: true
    key: ABCDEF1234567890
    elfOnly: true
    exportKey: true

export:
  repository: ./repo
  gpgSign: ABCDEF1234567890
  generate-static-deltas: true

Правила валидации#

Валидация манифеста выполняется при вызове aft-app validate и автоматически перед сборкой. Ниже перечислены проверяемые правила.

Ошибки (прерывают сборку)#

Поле version должно быть указано.
Поле metadata.id должно быть указано и содержать минимум одну точку.
Поля metadata.name, metadata.version, metadata.arch должны быть указаны.
Значение metadata.arch должно быть одним из: amd64, x86_64, arm64, aarch64, i386, armhf.
Поля runtime.id и runtime.version должны быть указаны (кроме автономного режима).
Поле files.command должно быть указано.
Поле export.repository должно быть указано.
Для source.type: repository — обязательно поле source.repository.package.
Для source.type: local — обязательно поле source.local.path.
Для source.type: url — обязательно поле source.url.address.
Для source.type: tar — обязательно поле source.tar.path.
При standalone.enabled: true — обязательно поле standalone.rootfs.

Предупреждения (не прерывают сборку)#

Не указаны разрешения sockets, devices или filesystems — приложение может не работать без доступа к графической подсистеме.
Включена генерация SBOM при отключённом анализе зависимостей.

Справочник манифеста aft-app

Содержание

Справочник манифеста aft-app#

Корневые поля#

Секция metadata#

Секция runtime#

Секция source#

Тип repository (по умолчанию)#

Тип local#

Тип url#

Тип tar#

Секция dependencies#

Секция files#

Секция permissions#

Секция extensions#

Секция commands#

Секция build#

Параметры верхнего уровня#

Подсекция bsign#

Секция export#

Секция standalone#

Полный пример манифеста#

Правила валидации#

Ошибки (прерывают сборку)#

Предупреждения (не прерывают сборку)#