Ctrl+K
Ctrl+K
Ctrl+K

Отладка приложений и подготовка репозиториев

Отладка приложений и подготовка репозиториев#

Отладка Flatpak-приложений#

Запуск оболочки внутри песочницы#

Для интерактивной отладки можно запустить оболочку вместо основного приложения:

flatpak run --command=bash org.example.MyApp

Это откроет bash внутри песочницы приложения с теми же разрешениями и той же файловой системой, которые видит само приложение. Можно исследовать содержимое /app, /usr и проверить наличие библиотек и конфигурации.

flatpak run --command=sh org.example.MyApp

Можно использовать sh, если bash отсутствует в рантайме.

Запуск в режиме разработки#

Флаг --devel снимает часть ограничений песочницы и монтирует SDK вместо рантайма (если SDK установлен):

flatpak run --devel org.example.MyApp

В этом режиме доступны инструменты разработки из SDK (компиляторы, отладчики, strace, gdb), а системный вызов ptrace разрешён.

Комбинация с оболочкой:

flatpak run --devel --command=bash org.example.MyApp

Подробный вывод#

Для получения детальной информации о процессе запуска используется переменная окружения FLATPAK_DEBUG:

FLATPAK_DEBUG=1 flatpak run org.example.MyApp

Для отладки GTK-приложений:

flatpak run --env=G_MESSAGES_DEBUG=all org.example.MyApp

Для отладки Qt-приложений:

flatpak run --env=QT_LOGGING_RULES='*.debug=true' org.example.MyApp

Просмотр информации о приложении#

Общая информация:

flatpak info org.example.MyApp

Подробная информация с разрешениями:

flatpak info --show-permissions org.example.MyApp

Просмотр метаданных:

flatpak info --show-metadata org.example.MyApp

Путь к развёрнутым файлам приложения:

flatpak info --show-location org.example.MyApp

Подключение к работающему приложению#

Команда flatpak enter подключается к песочнице уже запущенного приложения:

flatpak enter <PID> /bin/bash

Где <PID> — идентификатор процесса приложения. Получить его можно через:

flatpak ps

Примечание

flatpak enter требует привилегий суперпользователя.

Переопределение разрешений#

Для тестирования различных конфигураций разрешений можно использовать flatpak override без пересборки приложения:

Добавить разрешение:

flatpak override --user --share=network org.example.MyApp

Убрать разрешение:

flatpak override --user --nofilesystem=home org.example.MyApp

Просмотреть текущие переопределения:

flatpak override --user --show org.example.MyApp

Сбросить все переопределения:

flatpak override --user --reset org.example.MyApp

Переопределения сохраняются между запусками. Флаг --user применяет изменения только для текущего пользователя, без него — глобально (требует root).

Типичные проблемы#

Приложение не запускается без вывода ошибок

Запустить с оболочкой и проверить наличие бинарного файла:

flatpak run --command=bash org.example.MyApp
ls -la /app/bin/
ldd /app/bin/myapp   # проверить зависимости

Отсутствует библиотека

Проверить, есть ли библиотека в рантайме или приложении:

flatpak run --command=bash org.example.MyApp
find /usr/lib /app/lib -name "libexample*" 2>/dev/null

Приложение не видит файлы пользователя

Проверить разрешения файловой системы:

flatpak info --show-permissions org.example.MyApp | grep filesystems

Нет звука, нет доступа к сети, нет GPU-ускорения

Проверить наличие соответствующих разрешений (pulseaudio, network, dri) и при необходимости добавить через flatpak override.

Подготовка репозиториев#

Файлы .flatpakrepo#

Файл .flatpakrepo упрощает подключение репозитория для конечного пользователя. Это текстовый файл в формате INI, содержащий все необходимые параметры подключения.

Структура файла:

[Flatpak Repo]
Title=Название репозитория
Url=https://repo.example.com/flatpak
Homepage=https://example.com
Comment=Краткое описание репозитория
Description=Подробное описание репозитория
Icon=https://example.com/icon.png
GPGKey=<base64-кодированный GPG-ключ>

Поля:

  • Title (обязательное) — отображаемое название репозитория;

  • Url (обязательное) — URL OSTree-репозитория;

  • Homepage — URL сайта проекта;

  • Comment — краткое описание (одна строка);

  • Description — подробное описание;

  • Icon — URL иконки;

  • GPGKey — публичный GPG-ключ репозитория в кодировке base64.

Получение base64-представления GPG-ключа:

gpg --export <ID-ключа> | base64 --wrap=0

Подключение репозитория через .flatpakrepo:

flatpak remote-add --if-not-exists <имя> <путь-или-url>.flatpakrepo

Файл можно разместить на веб-сервере. При открытии в браузере (если в системе установлен Flatpak) пользователю будет предложено подключить репозиторий.

flatpak build-sign#

Команда подписывает существующие коммиты в OSTree-репозитории GPG-ключом. Используется, когда коммит был экспортирован без подписи или требуется добавить подпись другим ключом.

Синтаксис:

flatpak build-sign [ПАРАМЕТРЫ] РЕПОЗИТОРИЙ [ИДЕНТИФИКАТОР [ВЕТКА]]

Если ИДЕНТИФИКАТОР не указан, подписываются все коммиты в репозитории.

Параметры:

--gpg-sign=<ID-ключа>

Идентификатор GPG-ключа для подписи (можно указывать многократно).

--gpg-homedir=<путь>

Каталог с GPG-ключами.

--runtime

Подписать рантайм (а не приложение).

--arch=<архитектура>

Архитектура.

Примеры:

Подписать конкретное приложение:

flatpak build-sign --gpg-sign=<ID-ключа> repo org.example.MyApp stable

Подписать все коммиты в репозитории:

flatpak build-sign --gpg-sign=<ID-ключа> repo

flatpak build-commit-from#

Команда создаёт новый коммит на основе существующей ссылки (ref) в репозитории. Позволяет изменить метаданные, ветку или подпись без повторного экспорта из сборочного каталога.

Синтаксис:

flatpak build-commit-from [ПАРАМЕТРЫ] DST-REPO DST-REF

Позиционные аргументы:

  • DST-REPO — целевой репозиторий;

  • DST-REF — целевая ссылка (например, app/org.example.MyApp/x86_64/stable).

Параметры:

--src-repo=<путь>

Исходный репозиторий (если отличается от целевого).

--src-ref=<ссылка>

Исходная ссылка (если отличается от целевой).

--untrusted

Не доверять исходному репозиторию (пересчитать все контрольные суммы).

--force

Перезаписать существующий коммит в целевой ссылке.

--subject=<текст>, -s

Описание нового коммита.

--body=<текст>, -b

Расширенное описание коммита.

--update-appstream

Обновить AppStream-данные.

--no-update-summary

Не обновлять файл summary.

--gpg-sign=<ID-ключа>

Подписать новый коммит GPG-ключом.

--gpg-homedir=<путь>

Каталог с GPG-ключами.

--end-of-life=<причина>

Пометить как снятое с поддержки.

--end-of-life-rebase=<идентификатор>

Пометить как снятое с поддержки с перенаправлением.

--token-type=<значение>

Тип токена для доступа.

--timestamp=<временная-метка>

Временная метка коммита.

--collection-id=<идентификатор>

Collection ID репозитория.

--subset=<имя>

Подмножество.

--disable-fsync

Отключить fsync() для ускорения записи.

--no-summary-index

Не обновлять индекс summary.

Типичные сценарии использования:

Копирование приложения между репозиториями:

flatpak build-commit-from \
    --src-repo=repo-staging \
    --src-ref=app/org.example.MyApp/x86_64/beta \
    --gpg-sign=<ID-ключа> \
    repo-production app/org.example.MyApp/x86_64/stable

Переподпись существующего коммита:

flatpak build-commit-from \
    --gpg-sign=<новый-ID-ключа> \
    repo app/org.example.MyApp/x86_64/stable

Пометка приложения как устаревшего с перенаправлением:

flatpak build-commit-from \
    --end-of-life-rebase=org.example.NewApp \
    repo app/org.example.OldApp/x86_64/stable

Рабочий процесс публикации#

Ниже описан типичный процесс подготовки репозитория для распространения.

  1. Сборка и экспорт — приложение собирается и экспортируется в локальный репозиторий командами flatpak build-export или инструментами AFT.

  2. Подпись коммитов — если коммит не был подписан при экспорте:

    flatpak build-sign --gpg-sign=<ID-ключа> repo

  3. Обновление метаданных — пересоздание индекса и подпись summary:

    flatpak build-update-repo \
    --title="Название репозитория" \
    --generate-static-deltas \
    --gpg-sign=<ID-ключа> \
    --prune \
    repo

    Подробное описание параметров flatpak build-update-repo — в разделе Ручная сборка командами flatpak build.

  4. Формирование .flatpakrepo — создание файла для удобного подключения:

    cat > myrepo.flatpakrepo << 'EOF'
[Flatpak Repo]
Title=My Repository
Url=https://repo.example.com/flatpak
Homepage=https://example.com
GPGKey=<вывод gpg --export <ID> | base64 -w0>
EOF

  5. Размещение — репозиторий и файл .flatpakrepo размещаются на HTTP/HTTPS-сервере.

  6. (Опционально) Создание бандлов — для автономного распространения:

    flatpak build-bundle repo org.example.MyApp.flatpak org.example.MyApp stable

    Подробное описание flatpak build-bundle — в разделе Ручная сборка командами flatpak build.

Содержание