Обсуждение участника: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

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

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

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

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

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

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

Экосистема 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

Настройка пользователя

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

# usermod -aG rpm <user>

Настройка Git

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

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

Настройка RPM

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

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

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

Создание пользователей Hasher

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

# hasher-useradd <user>

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

Инициализация Hasher

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

$ mkdir ~/hasher
$ mkdir ~/.hasher
$ hsh --initroot-only ~/hasher

Для оптимизации производительности лучше сделать ~/hasher символической ссылкой на каталог в tmpfs (например, $TMP/hasher при типичных настройках дистрибутива "из коробки"):

$ rm -rf ~/hasher
$ mkdir -p $TMP/hasher
$ ln -sr $TMP/hasher ~/hasher

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

Автоматизировать такой mkdir можно будет добавлением этой команды в ~/.hasher/config (это конфигурационный файл в виде исполнимого скрипта).

Настройка Hasher

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

packager="`rpm --eval %packager`"
no_sisyphus_check="packager,buildhost,gpg"
apt_config="$HOME/.hasher/apt.conf
allowed_mountpoints=/dev/pts,/proc
#mkdir -p $TMP/hasher
lazy_cleanup=1

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

Настройка 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, результаты работы которой следует добавить в репозиторий отдельным коммитом, например, так: git commit -m 'gear-store-tags' .gear/tags/.

Файл .gear/rules

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

specfile

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

Пример:

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

Name: cfengine
Version: 3.12.0

Триггеры

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

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

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

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

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

Процесс работы над 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

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

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

В случае, если нам необходимо добавить 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 --commit <task id>