Обсуждение участника:Nir

Руководство мейнтейнера ALT Linux

Введение

Данная статья предназначена для централизации всей информации о процессе работы над репозиторием Sisyphus и интеграции в сообщество ALT Linux Team.

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

• желание внести свой вклад в развитие открытого ПО и сделать мир лучше;
• желание "отполировать резюме" и показать рекрутёрам свои навыки;
• желание решить вполне себе практическую проблему - например, воспользоваться конкретной программой;
• необходимость решения проблем эксплуатации дистрибутива в коммерческой или государственной структуре.

Кто такой мейнтейнер

Мейнтейнер (дистрибутива или пакета) - это человек, который занимается тем, что интегрирует ПО в дистрибутив и сопровождает его впоследствии. То есть делает пакет для установки программы из централизованного репозитория, чинит обнаруженные в программе баги, общается с разработчиками программы, старается реагировать на нужды пользователей (багрепорты, вопросы).

В понимании проекта ALT Linux - мейнтейнер должен быть членом ALT Linux Team (Команды ALT Linux).

Что такое ALT Linux Team

ALT Linux Team - команда независимых разработчиков, которые совместно работают над поддержкой наборов программ в репозитории Sisyphus и собирают дистрибутивы на основе этого репозитория.

Как стать членом ALT Linux Team

Существует процедура принятия в ALT Linux Team, описанная на странице Join (присоединение). Обычно, этот процесс происходит естественно, когда человек активно участвует в работе сообщества:

• тестирует ПО и заводит багрепорты о найденных багах;
• помогает чинить баги - присылает патчи;
• пакетирует новое ПО или помогает поддерживать существующие пакеты.

Взаимодействие членов команды осуществляется с помощью разнообразных средств связи (сложилось исторически):

• Sisyphus - репозиторий ПО;
• bugzilla.altlinux.org - багтрекер проекта;
• lists.altlinux.org - списки рассылки проекта;
• forum.altlinux.org - форум сообщества.
• #altlinux и #altlinux-devel - IRC каналы;

Процедура Join

Формально, Join выглядит как создание бага на ALT Linux Bugzilla в разделе Development, с параметрами:

• Product == Team Accounts
• Component == Join

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

• публичный ключ SSH - для доступа к ресурсам сборочницы;
• публичный GPG-ASCIIARMOR ключ для подписи коммитов;
• указать никнейм ментора из команды;
• указать желаемый почтовый адрес вида <nickname>@altlinux.org. Ник должен быть длиннее трёх символов. Посмотреть, занят ли выбранный адрес можно на странице http://git.altlinux.org/people/

В качестве теста на членство в команде принимается работа в виде Gear-репозитория новой программы или возрождение выпавшей из сборок.

Чтобы указать имя ментора (члена команды, который научит собирать и спопровождать пакеты), необходимо предварительно получить его согласие на менторинг. Оптимальный вариант - договориться об этом в личной переписке по e-mail.

Актуальный список менторов (вечно перегружены и плохо пингуются, при возможности лучше найти "своего"):

• sin@
• mike@
• iv@ - только оффлайн менторинг
• nir@ - только оффлайн менторинг

Проверка ключа

ssh-keygen -l -f ./id_ed25519.pub

Почта должна при этом совпадать с alias, выбранным для почты @altlinux.org.

gpg2 --import-options show-only ./pubring.pub

Почта должна совпадать с alias на altlinux.org. Также, и имя и почта должны совпадать с тем, что будет установлено в настройках Git.

Работа с пакетной базой

Архитектура средств управления пакетами

Экосистема ALT Linux обладает многими уникальными наработками и своей интересной историей и архитектурой.

Введение в Gear-репозитории

Gear-репозиторий представляет собой репозиторий Git DVCS, содержаший RPM specfile и специальную директорию .gear с инструкциями по сборке пакета для RPM. Практически всегда (но это не является неприкосновенным правилом) в репозитории также хранится и код программы.

К сожалению, Gear, как и Git - очень сложный и гибкий инструмент вида "всё наружу". Есть много вариантов хранения программ в gear repo, которые могут создать проблемы начинающему мейнтейнеру или заставить поломать голову опытного. Не существует однообразного рецепта работы с gear repo, так что не стесняйтесь посоветоваться с участниками сообщества по тем или иным вопросам (также специально создана рассылка devel-newbies@).

Есть некоторые общие рекомендации, которых можно придерживаться:

• хранить код программы с редкими исправлениями удобно в ветке master - там же, где находятся specfile и директория .gear;
• хранить код программы отдельно, в ветке upstream, удобно, когда в программу вносится много изменений и история правок specfile или правил Gear мешает следить за ходом работы.

Нюансы сборки пакетов

• При жалобах на зашитый в ПО RPATH на крайний случай удаляйте его при сборке с помощью программы chrpath. Раньше использование RPATH было очень популярно (особенно в системе сборки automake/libtool), но потом мейнтейнеры пришли к выводу, что это мешает искать библиотеки в стандартных путях. Потому, не оставляйте RPATH без особой необходимости.
• Если у программы есть плагины (особенно с развесистыми или взаимно противоречащими зависимостями), документация, заголовочные файлы библиотек - разместите их в отдельных подпакетах.
• Если у программы есть жёсткие опциональные зависимости (например, варианты зависимости от MySQL/MariaDB и от PostgreSQL) - соберите программу в нескольких вариантах, чтобы позволить пользователям не тянуть лишние зависимости, когда они не нужны.
• Если пользователям могут одновременно понадобиться обе версии программы - старая и новая - соберите два пакета с разными именами. Также обдумайте интеграцию с системой Alternatives и вариант небольшого скрипта-обёртки при таком подходе.
• Если программа предоставляет сервер/сервис - удостоверьтесь в наличии предоставляемых файлов .service для systemd и инитскрипта для sysvinit.
• Политика дистрибутива такова, что не должно быть программ с suid-битом (как sudo) "из коробки". Существует много вариантов решения проблемы, одним из которых является добавление поддержки control(8). В данном случае необходимо проконсультироваться с членами ALT Linux Team касательно разумного выхода из сложившейся ситуации.
• Если Вы импортировали RPM specfile из другого дистрибутива - оставьте прежний changelog, а свои изменения дописывайте отдельно - это дань уважения авторам.
• При сборке gear repo предлагается хранить исходный код отдельно от инструкций сборки в том случае, если проект активно развивается и необходимо видеть его "чистую" историю изменений в Git. В том случае, если проект неактивный, имеет много собственных специфичных патчей - предлагается хранить исходный код в одной ветке с правилами сборки.
• В случае сборки разделяемых библиотек и фреймворков необходимо поставлять .pc файлы libtool и файлы конфигурации .cmake для CMake. Также необходимо убедиться, что файлы конфигурации, будучи использованы соответствующими инструментами, позволят найти необходимые библиотеки и заголовочные файлы. Одним из оптимальных способов будет написание небольшого интеграционного теста, который будет запускаться после сборки пакета.

Подготовка локального сборочного окружения

Установка пакетов для разработки

Для разработки пакетов нам необходим сборочный тулчейн - rpm, hasher, gear и вспомогательные программы.

Обновите систему, чтобы получить свежие версии пакетов программ:

# apt-get update
# apt-get dist-upgrade
# reboot

и после перезагрузки установите следующие пакеты:

# apt-get install git \
	gear \
	hasher \
	hasher-priv \
	hasher-rich-chroot \
	hasher-rich-chroot-user-utils \
	rpm-utils \
	rpm-build \
	rpm-build-licenses \
	rpm-macros-cmake \
	rpm-macros-make \
	rpm-macros-generic-compat \
	apt-repo \
	apt-repo-tools

Настройка Git

Начальная настройка Git выполняется тремя командами:

$ git config --global user.name "Vasiliy Petrov"
$ git config --global user.email "vasip@altlinux.org"
$ git config --global user.signingkey <keyid> 

keyid стоит указывать тот, который был сгенерирован для Join.

Настройка RPM

Добавьте в файл ~/.rpmmacros следующие строки, совпадающие с конфигурацией GPG2 и Git:

%packager Vasiliy Petrov <vasip@altlinux.org>
%_gpg_name vasip@altlinux.org

# Завершать сборку с ошибкой, если обнаружились незапакованные файлы
%define _unpackaged_files_terminate_build 1

Настройка Hasher

Добавьте пользователя в группу rpm, чтобы Hasher не выкачивал пакеты для chroot каждый раз заново:

# usermod -aG rpm <user>

Hasher использует двух пользователей внутри своего изолированного окружения, чтобы предотвратить атаки на хост-систему из пакетов. Нам необходимо сконфигурировать этих пользователей для аккаунта, от имени которого будет производиться процесс сборки пакетов. Сделать это можно следующей командой:

# hasher-useradd <user>

Где <user> - имя пользователя. Для того, чтобы изменения к пользователю (попадание в две вспомогательных группы hasher) вступили в силу, необходимо выйти из аккаунта и зайти снова. Иногда можно получить ошибку вида:

hsh: /usr/libexec/hasher-priv/getconf.sh: cannot access getconf helper

Если это происходит после перелогина в систему - значит, что новые настройки не были подхвачены. Может помочь перезагрузка машины.

Далее создайте директорию настроек Hasher и сборочную директорию с последующей их инициализацией:

$ mkdir ~/hasher
$ mkdir ~/.hasher

Далее создайте файл `~/.hasher/config` примерно следующего содержания:

packager="`rpm --eval %packager`"
no_sisyphus_check="packager,buildhost,gpg"
allowed_mountpoints=/dev/pts,/proc,/dev/shm
lazy_cleanup=1
# share_ipc=1
# Необходимо в случае, когда требуется разрешить доступ в сеть из Hasher chroot.
# Данная опция не должна приеняться без особой необходимости.
# share_network=1
# нужен для сборки с репозиториями отличающимися от системного:
# apt_config="$HOME/.hasher/apt.conf"

для завершения процесса настройки.

Можно проверить работоспособность hasher, создав сборочное окружение:

$ hsh --initroot-only ~/hasher

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

Настройка SSH

Управление заданиями в сборочной инфраструктуре осуществляется с помощью SSH. Для каноничного использования серверов SSH нужно прописать такие строки в ~/.ssh/config:

# Sisyphus infrastructure
Host git.alt
  HostName gitery.altlinux.org
  User git_<username>
  Port 222
  IdentityFile ~/.ssh/id_rsa

Host girar
  HostName gyle.altlinux.org
  User git_<username>
  Port 222
  IdentityFile ~/.ssh/id_rsa

Создание Gear-репозитория из исходных кодов

Мы будем создавать Gear-репозиторий с хранением кода в отдельной ветви - upstream и несколькими зависимыми пакетами (документация, плагины).

Сначала создайте директорию проекта и инициализируйте её:

mkdir program
cd program
git init

В директории проекта могут быть следующие файлы:

• .gear/rules - файл "правил", согласно которым формируется архив для последущей сборки в Hasher;
• .gear/tags/list - описание тегов для Gear.

Перед продолжением работы стоит отметить, что в Gear-репозиториях может отсутствовать ветка master. Зачастую ветки именуются на основании того, для какой платформы (версии репоизтория Sisyphus) они предназначены, так как разные срезы репозитория могут отличаться по структуре.

Далее нам необходимо задать базовую структуру репозитория. Создаём директорию настроек gear repo:

mkdir -p .gear
touch .gear/rules

Также нам необходимо создать файл с инструкциями сборки приложения:

touch program.spec

Для продолжения работы следует принять к сведению следующую информацию:

Gear производит сборку пакета из Git tag. В связи с тем, что на сборку отправляется конкретный тег - в его истории должен быть доступен как исходный код, так и правила сборки. Потому при хранении исходного кода в отдельной ветке необходимо производить операцию

merge -s ours <code_branch>

в ветку с инструкциями сборки. Это позволит создать единую историю изменений из двух веток.

Файл .gear/tags/list

Файл .gear/tags/list содержит информацию о соответствии хэшей Git тегам Gear.

Обычно создаётся командой gear-store-tags -avc и правится командой gear-update-tag, результаты работы которой следует добавить в репозиторий отдельным коммитом, например, так: git commit -m 'gear-store-tags' .gear/tags/. Выглядеть файл list может так:

cfbb5bba7b9d811ca4734973f5b68296ae305424 v1.2

Рядом с .gear/tags в таком случае должен лежать файл с id коммита в качестве имени (.gear/tags/cfbb5bba7b9d811ca4734973f5b68296ae305424) формата:

object 21c9b06871f49c57f770bce99ed4300df8ec7972
type commit
tag v1.2
tagger Jeremy White <jwhite@codeweavers.com> 1591374242 +0000

Tag for version 1.2

Файл .gear/rules

Файл .gear/rules содержит инструкции по упаковке исходного кода и патчей в архив, из которого будет производиться сборка RPM. В простейшем виде он может выглядеть так:

tar: .

Другой пример:

tar: KITScenarist name=@name@-@version@

указывает запаковать директорию KITScenarist из проекта. По умолчанию архив будет иметь имя директории:

KITScenarist-1.0.0.tar

. В то же время в specfile прописано имя:

%name-%version.tar

Чтобы два имени архива совпали, необходимо указать имя целевого архива в Gear rules. В противном случае макрос %setup не сможет найти необходимый архив с исходниками.

Существует директива copy (а также copy?, которую не рекомендуется применять из-за неявности):

copy: fastfix.patch

Она необходима для прикладывания патчей из репозитория в архив. Директивы выполняются в порядке их чтения сверху вниз, потому она должна находиться перед директивой tar. Применяется в случаях, когда код надо запатчить быстро, а апстрим проекта тянет с применением изменений.

Ещё одна интересная директива - spec. Она указывает расположение specfile в том случае, если он находится в нестандартном месте (не в корне репозитория проекта). На текущий момент предлагается размещать specfile в директории .gear и отправлять файлы в виде pull request в апстрим проектов. Таким образом можно будет сделать сборку не чем-то обособленным, а вполне себе публичной деятельностью. Файл rules при этом будет выглядеть примерно так:

spec: .gear/nice-project.spec
tar: .

specfile

Кроме метаинформации для Gear касательно версионирования изменений в репозитории необходимо также оформить .spec файл. Данный файл содержит метаинформацию для результирующего пакета, changelog и инструкции по сборке ПО в виде shell-скриптов. Данный файл представляет из себя скрипт в особом формате.

Пример:

# Определяем макрос, который сигнализирует о том, что в случае обнаружения
# незапакованных файлов сборка должна упасть с ошибкой
%define _unpackaged_files_terminate_build 1

Name: cfengine
Version: 3.12.0
Release: alt1
# Epoch: 1

Summary: Configuration management system
License: %gpl2plus
Group: Other
Url:
BuildArch: x86-64

Requires: gcc

BuildRequires(pre): rpm-build-licenses
BuildRequires: gcc

Source0: %name-%version.tar

%description:
Configuration management system.

%prep
%setup -q

%install

%files

%changelog

Типичный набор директив в specfile включает в себя (но не ограничивается этим):

%define
Name	Имя пакета. Регистрозависимо. Принято именовать пакеты в нижнем регистре не смотря на названия программ.
Version	Версия программы.
Release
Epoch	Обычно не используется. Вводится в новых сборках пакетов при необходимости даунгрейда пакета (например, когда в новой версии обнаружилась регрессия и надо обновить пакет на старую версию).
Summary	Краткое описание пакета.
License	Краткое название лицензии. Зачастую указывается в виде макроса из пакета rpm-build-licenses
Group	Группа пакетов
Url	Ссылка на сайт проекта.
BuildArch	Архитектура, для которой пакет предназначен или noarch, если пакет платформо-независимый (например, документация или картинки).
Requires	Зависимости пакета от других пакетов. Рекомендуется указывать по одной зависимости в строчке, так как их изменения удобно отслеживать в истории коммитов.
BuildRequires	Сборочные зависимости пакета. Дополнительные зависимости, которые нужны только для сборки.
BuildRequires(pre)	Сборочные зависимости пакета, которые будут установлены до разбора specfile. Зачастую в этой секции производится установка пакетов с RPM макросами.
Source0	Обычно выглядит как %name-%version.tar и представляет из себя название архива с исходниками, который будет распакован в сборочную директорию.
%description
%prep
%install
%files
%changelog

Триггеры

Триггеры это специальные скрипты, выполнение которых происходит при соответствии некоторых условий. Например, срабатывание при обновлении, когда версия установленного пакета ниже определённой. См. /usr/share/doc/rpm-4.*/triggers.

%triggerin	Срабатывает после установки пакета.
%triggerun	Срабатывает перед удалением пакета, если цель триггера установлена в системе.
%triggerpostun	Данный триггер срабатывает в ситуации обновления пакета, после удаления предыдущей версии пакета. Не срабатывает при простом удалении пакета.

Доработка существующего пакета

Процесс работы над существующим пакетом

Источниками существующих пакетов могут быть:

• gears - Git-репозитории специально оформленные инструкциями по сборке пакетов RPM;
• srpms - Пакеты SRPM, зачастую импортированные из других RPM-based дистрибутивов. Также SRPM могут применяться в ситуациях очень больших проектов, когда работа с Git неоправданно замедляет процесс сборки. К таким проектам, например, относится LibreOffice.

Процесс работы над Gears

Первоначально необходимо сделать персональную копию репозитория (форк, в терминологии GitHub), над которой и вести дальнейшую работу. Далее будет рассмотрена работа над CFEngine 3 в качестве примера.

Копируем репозиторий себе:

ssh git.alt clone /gears/c/cfengine.git

В случае, если мы начинаем работу над новым пакетом, необходимо репозиторий создать командой:

ssh git.alt init-db cfengine

Клонируем репозиторий на локальную машину для дальнейшей работы:

git clone git.alt:/people/имя/packages/cfengine.git

Далее стоит попытаться собрать пакет в текущей конфигурации, чтобы убедиться, что локальная сборочная система работает корректно. Выполнить эту задачу возможно с помощью утилиты gear-hsh. Она предназначена для сборки пакета в chroot и её успешное выполнение гарантирует 90% успеха при отправке пакета в сборочницу.

Переключитесь в директорию проекта:

cd cfengine

И выполните команду:

gear-hsh --verbose --lazy-cleanup --commit -- --verbose

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

• создан chroot для сборки;
• сформирован тарбол с исходным кодом программы и перемещён в chroot;
• будут скачаны и установлены пакеты сборочных зависимостей (указаны в spec файле в качестве BuildRequires директивы);
• будет запущен процесс распаковки тарбола с кодом, его сборки, тестирования и упаковки в RPM.

В случае проблем при сборке пакета в chroot иногда бывает необходимо доустановить пакеты, при том apt отсутствует внутри chroot. Сделать это можно командой:

hsh-install <package_name>

В случае, если нам необходимо добавить Git remote (например, git.alt) к существующему репозиторию, стоит воспользоваться следующей командой:

git remote add git.alt git.alt:/people/имя/packages/cfengine.git

Процесс работы над SRPMS

Существуют ситуации, когда работа над пакетом в виде git-репозитория может быть неудобна. Например, большое ПО типа LibreOffice может занимать огромный объём дискового пространства и иметь очень сложную историю. Вытягивание изменений и их отправка при этом сильно замедляются. К этому добавляются накладные расходы на создание тарбола для сборки пакета. В некотором роде данную проблему можно решить, если хранить исходный код в виде Source RPM - SRPM.

SRPM пакеты в ALT представлены Git репозиториями http://git.altlinux.org/srpms/ . История репозиториев отражает все успешные сборки SRPM. Происходит это в связи с процессом: SRPM распаковывается и собирается. Если сборка проходит успешно, то использованный исходный код автоматически коммитится в историю репозитория. Сами же SRPM пакеты лежат на зеркалах.

Отправка пакета в сборочницу

Сборка пакета осуществляется из определённого тега. После сборки пакет попадает в "карман" - мини-репозиторий. Один карман может содержать несколько пакетов. Это позволяет группировать пакеты по задачам для последующего тестирования.

Каждый пакет относится к платформе. Узнать список платформ для которых можно выполнить сборку пакета можно командой

ssh girar task new --help

Чтобы начать собирать пакеты необходимо создать сборочную "задачу" (которая станет карманом):

ssh girar task new p9

Далее необходимо добавить репозитории для сборки. Отправить на сборку можно репозиторий, который находится в песональном подкаталоге packages на git.altlinux.org командой:

ssh girar task add <task id> repo cfengine.git 3.12.2-alt1

Далее необходимо собственно запустить процесс сборки указанных репозиториев (на тестовую сборку, без отправки в основной репозиторий):

ssh girar task run --test-only <task id>

Стоит отметить, что опция --test-only является умолчальной, но не для всех сборочниц (которые бывают разные), так что рекомендуется не забывать добавлять её. После успешной сборки, если не возникает вопросов по пакетам, возможно отправить задачу в репозиторий. Для этого необходимо сделать не-тестовую сборку командой:

ssh girar task run -m "Build_reason" --commit <task id>

или (для подробного сообщения с пробелами):

ssh girar task run --commit <task id> -m -

Где "build_reason" - сообщение о причинах отправки на сборку, без пробелов.

Команды сборочницы

Просмотр списка веток:

ssh girar acl --list

Просмотр списка членов группы:

ssh girar acl p9 @maint show

Развёртывание локальной сборочницы

Сборочница состоит из контрольных машин, которые управляют заданиями и сборочных нод.

Создание собственного репозитория

Для решения задачи предоставления собственного специфичного репозитория, например, в ситуации, когда производитель проприетарного ПО хочет также поставлять свои пакеты для дистрибутива, существует команда genbasedir. Данная программа анализирует директорию с пакетами RPM и генерирует файлы метаданных.