Манифест расширения#

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

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

Манифест разбирается строго: одиночное значение вместо списка, значение неподходящего типа, неизвестное поле и поле, указанное дважды, отклоняются с указанием пути до поля и номера строки. Правила разбора те же, что у приложений, и подробно описаны в блоке Манифест приложения.

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

version#

Строка версии формата манифеста. По умолчанию 1.0.

version: "1.0"

metadata#

Метаданные расширения.

id - идентификатор в формате reverse-DNS (например, org.foo.App.Extension.Codecs). Обязателен.
name - понятное имя.
version - версия расширения. По умолчанию 1.0.
arch - архитектура: amd64 или arm64. По умолчанию amd64.
branch - ветка ref. По умолчанию stable. Должна совпадать с версией точки расширения хоста, если та задана.
tags - список меток для каталога приложений.

metadata:
  id: org.foo.App.Extension.Codecs
  arch: amd64
  branch: stable

extends#

Расширяемый хост (см. блок Расширяемый хост и среда сборки).

ref - ссылка на хост. Принимается полный ref или короткая форма. Обязательна.
directory - каталог монтирования.
tag - дополнительный тег.

extends:
  ref: app/org.foo.App/x86_64/stable
  directory: lib/codecs

buildRuntime#

Среда, относительно которой собрано расширение (см. блок Расширяемый хост и среда сборки).

id - идентификатор среды.
version - её версия.
sdk - идентификатор SDK.

buildRuntime:
  id: org.foo.Platform
  version: "1.8"
  sdk: org.foo.Sdk

source#

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

Допустимые значения type: deb, url, tar, repository. По умолчанию deb. Тип repository принимается и в кратком написании repo.

deb#

Для типа deb заполняется секция local:

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

source:
  type: deb
  local:
    path: /var/cache/apt/archives/codec.deb
    additionalPaths:
      - /path/to/dep.deb

url#

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

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

tar#

path - путь к архиву (.tar.xz, .tar.gz).
packages - дополнительные пакеты из репозитория.
layout - список правил раскладки; у каждого поля pattern и dest (см. блок Раскладка содержимого).

source:
  type: tar
  tar:
    path: /opt/plugin.tar.xz
    layout:
      - { pattern: "bin/plugin", dest: bin }

repository#

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

source:
  type: repository
  repository:
    package: clang-19

dependencies#

Дополнительные пакеты из репозитория (см. блок Источники содержимого).

additional - доложить пакеты с отсечением того, что есть в среде сборки.
force - включить пакеты всегда.
exclude - не включать пакеты.

dependencies:
  force:
    - libgl1-mesa-dri
    - mesa-vulkan-drivers

layout#

Список правил раскладки содержимого (см. блок Раскладка содержимого). У каждого правила поля from (путь в извлечённом дереве) и to (путь относительно корня содержимого; пусто - корень). Секция применяется к источникам deb, url и repository; для tar-архива раскладка задаётся полем source.tar.layout.

layout:
  - { from: usr/lib/llvm-19,          to: "" }
  - { from: usr/lib/x86_64-linux-gnu, to: lib }

files#

Дополнительные файлы расширения (см. блок Раскладка содержимого).

write - список файлов, записываемых из заданного содержимого; у каждого поля path, content и executable (по умолчанию false).
copy - список файлов и каталогов, копируемых с хоста; у каждого поля src и dest.

files:
  write:
    - path: enable.sh
      executable: true
      content: |
        export PATH="/usr/lib/sdk/llvm-19/bin${PATH:+:${PATH}}"

build#

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

sbom - генерировать состав ПО. По умолчанию true.
cache - использовать кэш. По умолчанию true.
cacheDir - каталог кэша. По умолчанию ~/.cache/aft-extension.
parallel - число параллельных загрузок. По умолчанию 4.
pruneBrokenSymlinks - удалять битые символьные ссылки после раскладки. По умолчанию false.

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

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

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

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

build:
  sbom: true
  pruneBrokenSymlinks: true
  bsign:
    enabled: false

export#

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

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

export:
  repository: ./repo

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

version: "1.0"

metadata:
  id: org.foo.App.Extension.Codecs
  arch: amd64
  branch: stable

extends:
  ref: app/org.foo.App/x86_64/stable
  directory: lib/codecs

buildRuntime:
  id: org.foo.Platform
  version: "1.8"
  sdk: org.foo.Sdk

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

build:
  sbom: true

export:
  repository: ./repo

Несколько расширений описываются в одном файле через разделитель ---.

Манифест расширения

Содержание