Манифест приложения#

Манифест - это YAML-файл, который полностью описывает сборку приложения. Он собирает в одном месте всё то же, что задаётся флагами команды package, и позволяет вести сборку воспроизводимо. Манифест собирают командой build, проверяют командой validate и могут получить из флагов командой generate-yaml.

В одном файле можно описать несколько приложений, разделив документы строкой ---; они собираются по очереди.

Ниже разобрана каждая секция и каждое поле: назначение и, где есть, значение по умолчанию. Поля без значения по умолчанию необязательны, если не указано обратное.

version#

Строка версии формата манифеста.

version: "1.0"

metadata#

Метаданные приложения.

id - идентификатор в формате reverse-DNS (минимум одна точка). Обязателен.
name - понятное имя приложения. Обязательно.
version - версия приложения. Если не задана, определяется на этапе сборки из описания пакета, а для закреплённой версии пакета берётся она.
arch - архитектура: amd64, x86_64, arm64, aarch64, i386 или armhf. По умолчанию amd64.
branch - ветка выпуска. По умолчанию stable.
tags - список меток для каталога приложений (например, proprietary).

metadata:
  id: org.astra.Thunderbird
  name: "Mozilla Thunderbird"
  version: "115.0"
  arch: amd64
  branch: stable
  tags: [proprietary]

runtime#

Среда выполнения, на которой работает приложение.

id - идентификатор среды.
version - версия среды.
sdk - идентификатор SDK. Если не задан, берётся как <id среды>.Sdk.

Для standalone-сборки эту секцию можно не заполнять: среда и SDK создаются автоматически по идентификатору приложения.

runtime:
  id: org.astra.Qt
  version: "1.8"
  sdk: org.astra.qtSdk

source#

Источник содержимого приложения. Поле type выбирает один из вариантов; заполняется одноимённая вложенная секция. Подробно про поведение каждого источника - в блоке Источники программы.

Допустимые значения type: repository, local, url, tar, system, sourcedir. По умолчанию repository.

repository#

package - имя пакета.
version - версия пакета. По умолчанию latest.
components - компоненты репозитория. По умолчанию один компонент main.

source:
  type: repository
  repository:
    package: thunderbird
    version: latest
    components: [main, contrib]

local#

path - путь к основному deb-файлу.
additionalPaths - список путей к дополнительным deb-файлам.

source:
  type: local
  local:
    path: /path/to/app.deb
    additionalPaths:
      - /path/to/dep.deb

url#

address - основная ссылка на deb.
additionalUrls - список дополнительных ссылок.

source:
  type: url
  url:
    address: https://example.com/app.deb
    additionalUrls:
      - https://example.com/dep.deb

tar#

path - путь к архиву (.tar.xz, .tar.gz, .tgz, .txz).
packages - дополнительные пакеты из репозитория.
layout - список правил раскладки. У каждого правила два поля: pattern (шаблон имени файла) и dest (каталог назначения в приложении). Оба поля обязательны: правило с пустым полем отклоняется при проверке манифеста.

source:
  type: tar
  tar:
    path: /opt/app.tar.xz
    packages: [libfoo]
    layout:
      - { pattern: "bin/app", dest: bin }

system#

binary - путь к программе или её имя в PATH.
patterns - дополнительные файлы по шаблонам пути.
includeOwningPackages - тянуть пакеты-владельцы целиком. По умолчанию true.

source:
  type: system
  system:
    binary: /usr/bin/myapp
    patterns:
      - /usr/share/myapp/*
    includeOwningPackages: true

sourcedir#

path - каталог с исходниками или готовыми бинарями.
buildCommands - список команд сборки.
buildDeps - сборочные зависимости, доступные только во время сборки. Вложенные списки: packages (из репозитория), debs (локальные файлы), urls (по ссылке), tars (архивы).
buildEnv - дополнительные переменные окружения для сборки в виде KEY=VALUE.

source:
  type: sourcedir
  sourcedir:
    path: /path/to/src
    buildCommands:
      - cmake -S . -B /tmp/b -DCMAKE_INSTALL_PREFIX=/app
      - cmake --build /tmp/b -j && cmake --install /tmp/b
    buildDeps:
      packages: [nlohmann-json3-dev]
      tars: [/opt/extra-libs.tar.xz]
    buildEnv:
      - CC=gcc

dependencies#

Управление составом приложения. Подробно - в блоке Зависимости.

analyze - разбирать зависимости. По умолчанию true.
includeRecommends - включать рекомендуемые пакеты. По умолчанию false.
includeSuggests - включать предлагаемые пакеты. По умолчанию false.
exclude - список пакетов, которые не включать.
additional - список пакетов, которые доложить (с отсечением того, что есть в среде).
force - список пакетов, которые включить всегда.

dependencies:
  analyze: true
  includeRecommends: false
  additional: [extra-lib]
  force: [libcustom]
  exclude: [unwanted]

files#

Исполняемый файл, иконки и метаданные приложения.

command - команда запуска.
desktop - путь к готовому desktop-файлу.
metainfo - путь к готовому файлу AppStream.
icons-dir - каталог иконок со структурой <размер>/<имя>.png.
icons - список конкретных иконок; у каждой поля size и path.
cleanPatterns - шаблоны файлов, удаляемых после извлечения.

files:
  command: thunderbird
  icons-dir: /path/to/icons
  cleanPatterns:
    - "*.la"

permissions#

Разрешения песочницы. Подробно - в блоке Разрешения песочницы. Все поля - списки.

sockets - сокеты (x11, wayland, pulseaudio, cups, pcsc, ssh-auth, session-bus, system-bus, fallback-x11).
devices - устройства (dri, kvm, shm, all).
shares - общий доступ (network, ipc).
filesystems - файловые системы; допускается суффикс :ro.
persist - сохраняемые между запусками каталоги.
env - переменные окружения приложения в виде KEY=VALUE.
unset-env - переменные окружения, которые убрать.
own-name - имена, которыми владеть на сессионной шине D-Bus.
talk-name - имена, к которым обращаться на сессионной шине.
system-own-name - имена, которыми владеть на системной шине.
system-talk-name - имена, к которым обращаться на системной шине.
no-talk-name - запрет обращения к именам на сессионной шине.
no-system-talk-name - запрет обращения к именам на системной шине. Записывается в политику системной шины в метаданных приложения.
allow - дополнительные разрешения: devel, multiarch, bluetooth, canbus, per-app-dev-shm.
inherit-extensions - точки расширения, наследуемые от среды выполнения. Среда должна быть установлена и должна объявлять эти точки, иначе сборка останавливается.

permissions:
  sockets: [x11, wayland, pulseaudio]
  devices: [dri]
  shares: [network, ipc]
  filesystems: [home, xdg-download:ro]
  persist: [.thunderbird]
  talk-name: [org.freedesktop.Notifications]

extensions#

Список точек расширения, которые объявляет приложение. Точка - это место, куда позже можно подключить расширение (см. раздел Создание расширений (aft-extension)). У каждой записи обязательны имя и каталог.

name - имя точки расширения (reverse-DNS). Обязательно.
directory - каталог монтирования. Обязателен.
version - одна поддерживаемая версия.
versions - несколько версий через точку с запятой.
autodelete - удалять автоматически, когда не нужно. По умолчанию false.
no-autodownload - не скачивать автоматически. По умолчанию false.
locale-subset - точка для набора локалей. По умолчанию false.
subdirectories - создавать поддиректории для вариантов. По умолчанию false.
add-ld-path - каталог, добавляемый к путям поиска библиотек.
download-if - условие скачивания.
enable-if - условие включения.
autoprune-unless - условие автоудаления.
merge-dirs - каталоги для слияния с родительскими.
subdirectory-suffix - суффикс поддиректорий.

extensions:
  - name: org.astra.Thunderbird.Locale
    directory: share/runtime/locale
    locale-subset: true

commands#

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

pre-export - список команд, выполняемых в каталоге сборки перед экспортом.

commands:
  pre-export:
    - rm -rf files/share/doc

standalone#

Режим со встроенной средой. Если включён, среда выполнения и SDK создаются автоматически, а обычная секция source не используется.

enabled - включить режим. По умолчанию false.
rootfs - путь к каталогу с системой.

standalone:
  enabled: true
  rootfs: /opt/myapp-rootfs

build#

Параметры сборки, подписи по ГОСТ и поиска уязвимостей.

sbom - генерировать состав ПО. По умолчанию true.
cache - использовать кэш. По умолчанию true.
cacheDir - каталог кэша. По умолчанию ~/.cache/aft-app.
parallel - число параллельных загрузок. По умолчанию 4.
useModel - уточнять предложенные разрешения моделью, а не только правилами. По умолчанию false. Нужен пакет aft-ml-model.
modelCmd - команда предсказания разрешений. По умолчанию aft-ml-predict.

Вложенная секция bsign - подпись ELF по ГОСТ:

enabled - включить подпись. По умолчанию false.
key - идентификатор ключа.
passphraseFile - файл с паролем для пакетной подписи.
detached - отсоединённые подписи. По умолчанию false.
detachedPath - каталог для отсоединённых подписей.
elfOnly - встраиваемая подпись в ELF. По умолчанию true.
exportKey - выложить публичный ключ в приложение. По умолчанию true.
useBsignIntegrator - использовать bsign-integrator. По умолчанию false.
password - пароль для bsign-integrator.

Вложенная секция scan - поиск уязвимостей после экспорта:

enabled - включить проверку. По умолчанию false.
ovalDir - каталог с базой определений.
failOn - уровень, начиная с которого сборка считается неуспешной.
strict - строгий режим. По умолчанию false.
severities - список проверяемых уровней.
ignoreCves - список исключаемых уязвимостей.
ignorePackages - список исключаемых пакетов.

build:
  sbom: true
  parallel: 4
  bsign:
    enabled: true
    key: "ABCD1234"
    passphraseFile: /etc/aft/bsign.pass
  scan:
    enabled: true
    failOn: high
    severities: [critical, high]

export#

Параметры экспорта в репозиторий OSTree.

repository - путь к репозиторию. По умолчанию ./repo.
bundle - путь к одиночному файлу .flatpak. Пусто - не создавать.
gpgSign - ключ GPG для подписи репозитория.
gpgHomedir - каталог GPG. По умолчанию ~/.gnupg.
stable - метка стабильной ветки. По умолчанию true.
collection-id - идентификатор набора репозитория.
generate-static-deltas - генерировать статические дельты для экономии трафика при обновлении. По умолчанию false.
prune - удалять старые объекты при обновлении репозитория. По умолчанию false.

export:
  repository: ./repo
  gpgSign: DEF28EB86746F181
  collection-id: ru.astralinux.AppRepo
  generate-static-deltas: true

Проверка манифеста#

Манифест проверяется командой validate; код возврата 0 означает, что ошибок нет. Та же проверка выполняется перед сборкой командой build, причём сразу для всех описанных в файле приложений: если ошибка хотя бы в одном, не собирается ни одно.

Проверка идёт в два прохода. Сначала разбирается сам файл, затем сверяется смысловая часть.

Разбор файла#

Манифест разбирается строго: то, что записано не по правилам, отклоняется, а не пропускается молча. Отклоняются:

одиночное значение там, где ожидается список: запись packages: mypackage без квадратных скобок;
значение неподходящего типа: строка вместо числа, число вместо логического значения;
неизвестное поле;
поле, указанное в секции дважды;
секция источника, не совпадающая с заявленным типом в source.type;
пустое обязательное поле в правиле раскладки, точке расширения или записи buildEnv не в формате KEY=VALUE.

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

Смысловая проверка#

После разбора проверяется содержательная часть: задан ли идентификатор приложения и в формате ли он reverse-DNS, заданы ли имя, архитектура из числа допустимых, среда выполнения и её версия, соответствует ли источник своему типу и заполнены ли его обязательные поля. Для standalone-сборки вместо источника проверяется путь к системе.

Полный пример#

version: "1.0"

metadata:
  id: org.astra.Thunderbird
  name: "Mozilla Thunderbird"
  version: "115.0"
  arch: amd64
  branch: stable
  tags: [proprietary]

runtime:
  id: org.astra.Qt
  version: "1.8"
  sdk: org.astra.qtSdk

source:
  type: repository
  repository:
    package: thunderbird
    version: latest
    components: [main]

dependencies:
  analyze: true
  includeRecommends: false

files:
  command: thunderbird

permissions:
  sockets: [x11, wayland, pulseaudio]
  devices: [dri]
  shares: [network, ipc]
  filesystems: [home]
  persist: [.thunderbird]

build:
  sbom: true
  bsign:
    enabled: false

export:
  repository: ./repo
  gpgSign: DEF28EB86746F181

Манифест приложения

Содержание