Перейти к основному содержимому

stplr-spec

stplr-spec — это CLI-утилита предназначенная для помощи в создании и поддержании спецификаций пакетов Stapler. Она предоставляет инструменты для управления метаданными пакетов, обновлении пакетов, сборки в изолированном окружении и др.

Исходный код

Команды stplr-spec​

Для получения справки выполните:

NAME:
   stplr-spec - cli-helper for writing Staplerfile

USAGE:
   stplr-spec [global options] [command [command options]]

COMMANDS:
   get-field         Get field value from Staplerfile
   set-field         Set field value in Staplerfile
   update-package    Update package (version, release, checksums)
   update-checksums  
   clean-build       Build package from spec in isolated environment
   help, h           Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

1. get-field​

Извлекает значение указанного поля из файла Staplerfile (например, version, release и т.д.).

$ stplr-spec get-field version
1.0.0
$ stplr-spec get-field name
foo-pkg
$ stplr-spec get-field _custom_field
value

2. set-field​

Извлекает значение указанного поля из файла Staplerfile (например, version, release и т.д.). Команда полезна в скриптах автоматизации обновления пакетов.

$ stplr-spec get-field version
1.0.0
$ stplr-spec set-field version 2.0.0
$ stplr-spec get-field version
2.0.0

3. update-checksums​

Обновляет checksums в Staplerfile путем скачивания всех sources из Staplerfile

4. update-package​

Автоматически проверяет доступность новой версии пакета и выполняет обновление.

Что делает:​

  • Проверяет наличие обновлений:

    • Если есть скрипт .stapler/update-check — выполняет его. Скрипт должен вернуть две строки через пробел:
    <текущая_версия> <новая_версия>
    # Пример
    1.2.3 1.3.0
    • Если .stapler/update-check отсутствует — используется nvchecker с конфигурацией .nvchecker.toml или предустановленный пресет.

  • Если доступна новая версия:

    • Выполняет скрипт .stapler/update-run (если он есть). Этот скрипт должен принимать новую версию в качестве первого аргумента: .stapler/update-run 1.3.0
    • Если .stapler/update-run отсутствует — выполняется стандартная логика:
      • Обновить поле version и сбросить release в 1.
      • Пересчитать checksums для всех sources.
      • Форматировать Staplerfile через shfmt.
Пресеты:​

Вместо написания скрипта можно указать пресет через поле _stapler_update_preset в Staplerfile:

  • snap — используется API Snapcraft для получения новой версии и URL. Алгоритм работы:
    1. Читает поля _snap_name и _snap_channel из Staplerfile.
    2. Запрашивает данные о snap через api.snapcraft.io.
    3. Находит нужный канал и получает: version, download.url.
    4. Записывает в Staplerfile:
      • новое version,
      • новый _snap_url,
      • сбрасывает release в 1.
    5. Сохраняет изменения, пересчитывает контрольные суммы и форматирует Staplerfile.

Пример:

# Проверить наличие обновления
$ stplr-spec update-package --only-check
1.2.3 1.3.0

# Полностью обновить пакет
$ stplr-spec update-package

4. clean-build​

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

Что делает:​

  • Загружает указанный образ (по пресету или вручную через --image).
  • Генерирует уникальные volume’ы для кеша (apt, sta) на основе хеша ID образа и имени пакета.
  • Монтирует каталог с Staplerfile внутрь контейнера /app.
  • Запускает сборочную команду из пресета (например, sta build).
  • Если передан --clean-cache, удаляет существующие volume’ы перед сборкой.
  • Если передан --export-build-cache, экспортирует кеш сборки sta в локальную папку .stplr-spec-bc-export.

Примеры использования:​

# Запустить сборку с использованием пресета aides
stplr-spec clean-build --preset aides

# Запустить без кеша
stplr-spec clean-build --preset aides --no-cache

# Очистить кеш и пересобрать
stplr-spec clean-build --preset aides --clean-cache

# Экспортировать кеш после сборки
stplr-spec clean-build --preset aides --export-build-cache