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

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

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

version: "1.0"
metadata: { }
source: { }
additional-repos: [ ]
packages: { }
commands: { }
environment: { }
extensions: [ ]
build: { }
export: { }

version: Версия формата манифеста. По умолчанию: "1.0".

Секция metadata#

metadata:
  id: org.example.Platform
  name: Example Runtime
  description: Runtime for Example applications
  version: "1.0"
  arch: amd64
  branch: stable
  tags:
    - base

Поле	Тип	Обязательное	Описание
`id`	строка	Да	Идентификатор рантайма в формате обратного DNS.
`name`	строка	Нет	Отображаемое имя (используется в `flatpak list`).
`description`	строка	Нет	Описание (используется в AppStream metainfo).
`version`	строка	Да	Версия рантайма.
`arch`	строка	Да	Архитектура: `amd64`, `arm64`, `x86_64`, `aarch64`. По умолчанию: `amd64`.
`branch`	строка	Нет	Ветка в репозитории. По умолчанию: `stable`.
`tags`	массив строк	Нет	Теги AppStream.

Секция source#

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

Тип debootstrap#

source:
  type: debootstrap
  debootstrap:
    distribution: <имя-дистрибутива>
    suite: stable
    mirror: <url-зеркала>
    components:
      - main
      - contrib
      - non-free
    variant: minbase

Поле	Тип	Обязательное	Описание
`distribution`	строка	Да	Имя дистрибутива для debootstrap.
`suite`	строка	Нет	Suite. По умолчанию: `stable`.
`mirror`	строка	Да	URL зеркала репозитория пакетов.
`components`	массив строк	Нет	Компоненты. По умолчанию: `["main"]`.
`variant`	строка	Нет	Вариант установки. Допустимые значения: `minbase`, `buildd`, `fakechroot`. По умолчанию: `minbase`.

Тип docker#

source:
  type: docker
  docker:
    image: <имя-образа>:<тег>

Поле	Тип	Обязательное	Описание
`image`	строка	Да	Имя Docker-образа с опциональным тегом (например, `debian:bookworm`).

Тип import#

source:
  type: import
  import:
    path: /path/to/rootfs

Поле	Тип	Обязательное	Описание
`path`	строка	Да	Путь к корневой файловой системе. Поддерживаются: каталог, tar-архив (`.tar`, `.tar.gz`, `.tar.xz`, `.tar.bz2`), SquashFS-образ.

Секция additional-repos#

Дополнительные APT-репозитории, подключаемые в chroot-среде перед установкой пакетов (массив объектов).

additional-repos:
  - url: https://repo.example.com/packages
    codename: stable
    components:
      - main
    key-url: https://repo.example.com/gpg-key.gpg
  - url: https://other.example.com/repo
    codename: testing
    components:
      - main
      - contrib

Поле	Тип	Обязательное	Описание
`url`	строка	Да	URL репозитория.
`codename`	строка	Да	Кодовое имя дистрибутива (`stable`, `testing`, `bookworm`).
`components`	массив строк	Нет	Компоненты репозитория.
`key-url`	строка	Нет	URL GPG-ключа. Ключ загружается и помещается в `trusted.gpg.d/` chroot-среды.

Секция packages#

Определяет пакеты для установки в рантайм и SDK.

packages:
  runtime:
    - bash
    - coreutils
    - libc6
    - libstdc++6
    - zlib1g
    - libssl3
    - ca-certificates
  sdk:
    - build-essential
    - pkg-config
    - cmake
    - git
    - autoconf
    - automake

Поле	Тип	Описание
`runtime`	массив строк	Пакеты, устанавливаемые в рантайм. Обязательное поле.
`sdk`	массив строк	Дополнительные пакеты, устанавливаемые в SDK. SDK включает все пакеты рантайма плюс указанные здесь.

Секция commands#

commands:
  post-install:
    - ldconfig
    - update-ca-certificates
    - fc-cache -fv

Поле	Тип	Описание
`post-install`	массив строк	Команды, выполняемые в chroot после установки пакетов. Типичные применения: пересборка кеша библиотек (`ldconfig`), обновление сертификатов, генерация кеша шрифтов.

Секция environment#

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

environment:
  LANG: en_US.UTF-8
  LC_ALL: en_US.UTF-8
  QT_QPA_PLATFORM: wayland

Формат: ключ-значение. Ключ — имя переменной, значение — строка.

Секция extensions#

Определяет точки расширений рантайма (массив объектов). Структура полностью аналогична расширениям aft-app (см. Справочник манифеста aft-app).

extensions:
  - name: org.example.Platform.Locale
    directory: share/runtime/locale
    autodelete: true
    locale-subset: true
  - name: org.example.Platform.GL
    directory: lib/GL
    version: "1.0"
    versions: "1.0;1.4"
    subdirectories: true
    add-ld-path: lib
    download-if: active-gl-driver
    enable-if: active-gl-driver
    autodelete: false

Полное описание полей расширений — в секции «Секция extensions» документа Справочник манифеста aft-app.

Секция build#

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

build:
  sdk: false
  sbom: false
  clean-docs: false
  signing:
    enabled: false
    key: ""
  bsign:
    enabled: false
    key: ""
    passphraseFile: ""
    detached: false
    detachedPath: ""
    elfOnly: true
    exportKey: true
    useBsignIntegrator: false
    password: ""

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

Поле	Тип	По умолчанию	Описание
`sdk`	булево	`false`	Создать SDK-версию рантайма.
`sbom`	булево	`false`	Генерировать SBOM (CycloneDX JSON).
`clean-docs`	булево	`false`	Удалить документацию (`/usr/share/doc`, `/usr/share/man`).

Подсекция signing#

GPG-подпись коммитов в репозитории.

Поле	Тип	По умолчанию	Описание
`enabled`	булево	`false`	Включить GPG-подпись.
`key`	строка	`""`	Идентификатор GPG-ключа.

Подсекция bsign#

Подпись ELF-файлов. Поля идентичны подсекции bsign манифеста aft-app (см. Справочник манифеста aft-app).

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

Секция export#

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

export:
  repository: ./repo
  collection-id: ""
  generate-static-deltas: false
  prune: false

Поле	Тип	По умолчанию	Описание
`repository`	строка	`./repo`	Путь к OSTree-репозиторию.
`collection-id`	строка	`""`	Collection ID (защита от подмены).
`generate-static-deltas`	булево	`false`	Генерировать статические дельты.
`prune`	булево	`false`	Удалить устаревшие объекты.

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

version: "1.0"

metadata:
  id: org.example.Platform
  name: Example Runtime
  description: Base runtime with system libraries
  version: "1.0"
  arch: amd64
  branch: stable
  tags:
    - base
    - runtime

source:
  type: debootstrap
  debootstrap:
    distribution: <имя-дистрибутива>
    suite: stable
    mirror: <url-зеркала>
    components:
      - main
      - contrib
    variant: minbase

additional-repos:
  - url: https://repo.example.com/extras
    codename: stable
    components:
      - main
    key-url: https://repo.example.com/key.gpg

packages:
  runtime:
    - bash
    - coreutils
    - libc6
    - libstdc++6
    - zlib1g
    - libssl3
    - ca-certificates
    - libglib2.0-0
    - libx11-6
    - libwayland-client0
  sdk:
    - build-essential
    - pkg-config
    - cmake
    - git
    - autoconf
    - automake
    - libtool

commands:
  post-install:
    - ldconfig
    - update-ca-certificates

environment:
  LANG: en_US.UTF-8
  LC_ALL: en_US.UTF-8

extensions:
  - name: org.example.Platform.Locale
    directory: share/runtime/locale
    autodelete: true
    locale-subset: true

build:
  sdk: true
  sbom: true
  clean-docs: true
  bsign:
    enabled: true
    key: ABCDEF1234567890
    elfOnly: true
    exportKey: true

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

Многодокументный формат#

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

version: "1.0"
metadata:
  id: org.example.Platform
  version: "1.0"
  arch: amd64
source:
  type: debootstrap
  debootstrap:
    distribution: <имя-дистрибутива>
    mirror: <url-зеркала>
packages:
  runtime:
    - bash
    - libc6
export:
  repository: ./repo

---

version: "1.0"
metadata:
  id: org.example.ExtendedPlatform
  version: "1.0"
  arch: amd64
source:
  type: debootstrap
  debootstrap:
    distribution: <имя-дистрибутива>
    mirror: <url-зеркала>
packages:
  runtime:
    - bash
    - libc6
    - libx11-6
    - libwayland-client0
export:
  repository: ./repo

Каждый документ обрабатывается и экспортируется независимо.

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

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

Поле metadata.id должно быть указано.
Поле metadata.version должно быть указано.
Значение metadata.arch должно быть допустимым (amd64, arm64, x86_64, aarch64).
Секция source должна быть указана.
Для source.type: debootstrap — обязательны distribution и mirror.
Для source.type: docker — обязательно image.
Для source.type: import — обязательно path.
Массив packages.runtime должен содержать хотя бы один пакет.

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

Содержание