From Fedora Project Wiki

Использование сборочной системы Koji в Fedora

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

Установка Koji

Установка утилиты командной строки koji

Для работы со сборочной системой Koji (в т.ч. для участия в разработке Fedora) необходмо установить один пакет:

yum install fedora-packager

Пакет fedora-packager содержит набор готовых программ-сценариев для установки и настройки пользовательской среды для работы с Koji. Кроме этого, для удовлетворения установочных зависимостей при установке пакета fedora-packager будет также установлен пакет, включающий утилиту командной строки для работы со сборочной системой Koji. Данная утилита называется koji и размещается в одноименном пакете. По-умолчанию утилита koji для выполнения аутентификации на центральном узле использует Kerberos. В то же время, имеется возможность настройки конфигурации утилиты koji для выполнения аутентификации с использованием имени пользователя и пароля или с использованием SSL-сертификата. Аутентификация на центральном узле необходима для получения необходимых прав на использование некоторых функций сборочной системы. При этом большинство функций, требующих доступа только на чтение, могут быть вызваны без предварительной аутентификации.

Настройка доступа через систему учетных записей Fedora (FAS2)

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

/usr/bin/fedora-packager-setup

Каждый пользователь, предполагающий выполнять сборки пакетов Fedora с использованием сборочной системы Koji, должен выполнить команду fedora-packager-setup. Это необходимо в силу того, что каждый пользователь должен иметь свой собственный сертификат для аутентификации.

Idea.png
Вниманию пользователей Plague!
Для пользователей сборочной системы plague (сборочная система предыдущего поколения, используемая до Koji), при выполнении команды fedora-packager-setup будут использованы существующие сертификаты. Если же сборочная система plague ранее не использовалась, при выполнении указанной команды будут использованы корневые сертификаты удостоверяющего центра (УЦ) центрального узла и выдано сообщение о месте размещения вновь созданного сертификата пользователя.
Сертификаты ключей Fedora

Сборочная система Koji использует три типа скртификатов:

~/.fedora.cert (индивидуальный для каждого ответственного за сопровождение пакетов Fedora)
Данный сертификат создается при выполнении команды fedora-cert -n. Наличие данного сертификата необходимо для каждого ответственного за сопровождение пакетов. Данный сертификат должен обновляться по мере истечения его срока действия. Проверка срока действия сертификата осуществляется выполнением команды fedora-cert -v.

остальные сертификаты загружаются автоматически утилитой fedora-packager-setup и, в общем случае, не требуют дополнительных настроек

~/.fedora-upload-ca.cert (Сертификат УЦ, используемый для подписи ключей пользователей.)
Данный сертификат может быть загружен вручную с ресурса, размещенного здесь или же он будет загружен автоматически при выполнении команды fedora-packager-setup или fedora-cert -n. Последний вариант является предпочтительным.
~/.fedora-server-ca.cert (Сертификат УЦ, используемый для подписи серверных ключей сборочной системы.)
Данный сертификат может быть загружен вручную с ресурса, размещенного здесь или же он будет загружен автоматически при выполнении команды fedora-packager-setup.
Warning.png
Ошибка работы с сертификатами в RHEL6
При использовании операционной системы RHEL6 несовместимость работы входящих в ее состав пакетов openssl и nss приводит к невозможности использования сертификатов, загруженных из системы управления учетными записями Fedora, некоторыми утилитами из пакета fedpkg. [Ошибка 631000 rhel6 openssl создает секретные ключи RSA в формате PEM с использованием PKCS#8, которые в дальнейшем не воспринимаются nss]. Для решения проблемы несовместимости формата сертификатов необходимо выполнить команду: (openssl x509 -in ~/.fedora.cert -text; echo; openssl rsa -in ~/.fedora.cert) > fedora.cert.new

Конфигурация koji

Общий конфигурационный файл, используемый всеми локальными клиентами koji, имеет имя /etc/koji.conf. Для выполнения операций по сборке пакетов Fedora внесение каких-либо изменений в указанный файл не требуется, т.к. при выполнении fedora-packager-setup создается набор конфигурационных файлов в каталоге ~/.koji/ для текущего пользователя. Это, в частности, позволяет работать одновременно как с основной сборочной системой Fedora, так и со сборочными сситемами Fedora для дополнительных архитектур.

Web-интерфейс

Idea.png
Опционально
Web-интерфейс является необязательным элементом. Содержание следующего подраздела может быть пропущено.

Основной интерфейс для просмотра данных, накапливаемых сборочной системой Koji, реализован в виде web-приложения. Взаимодействие с данным приложением осуществляется через обращение по адресу http://koji.fedoraproject.org/koji/ . Большая часть интерфейса реализует доступ к функциям, предусматривающим выполнение только операций чтения данных, но, при наличии достаточных полномочий, имеется позможность после авторизации выполнять некоторые дополнительные действия. Как например:

  • Отмена сборки
  • Повторное выполнение задачи, закончившейся неуспешно
  • Настройка уведомлений

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

  • Создание/редактирование/удаление тега
  • Создание/редактирование/удаление сборочной цели
  • Разрешение/запрет использования сборочного узла

Указанный web-ресурс использует SSL-аутентификацию. Для прохождения аутентификации требуется наличие действующего SSL-сертификата, а также настройка интернет-обозревателя, позволяющая рассматривать данный сертификат как доверенный. Инструкция, описывающая необходимую для этого последовательность действий, может быть получена выполнением команды fedora-packager-setup --with-browser-cert.

Warning.png
Использование сертификата, загруженного через web-интерфейс FAS
Если сертификат ~/.fedora.cert был сгенерирован и загружен непосредственно из FAS, он должен быть преобразован в формат, приемлемый для интернет-обозревателя с помощью следующей команды:

openssl pkcs12 -export -in ~/.fedora.cert -CAfile ~/.fedora-upload-ca.cert -out ~/fedora-browser-cert.p12,

где .fedora-upload-ca.cert - загруженный сертификат.

Установка SSL-сертификатов в Firefox

Note.png
Опционально
Перечисленные ниже инструкции необходимы только для выполнения аутентификации через web-интерфейс с использованием интернет-обозревателя Firefox. В общем случае аутентификация с использованием интернет-обозревателя является необязательной.

После создания учетной записи в системе FAS, необходимо импортировать в интернет-обозреватель сертификат, созданный по команде fedora-packager-setup --with-browser-cert. В интернет-обозревателе Firefox это может быть сделано следующим образом:

1. Выполнить запуск приложения Firefox и активировать меню Правка (Edit) в панели инструментов

2. Выбрать пункт Настройки (Preferences) в появившемся списке меню

3. На отобразившейся экранной форме Настройки (Preferences) выбрать подраздел Дополнительные (Advanced)

4. В подразделе Дополнительные (Advanced) переключиться на вкладку Шифрование (Encryption)

5. Активировать экранную кнопку Просмотр сертификатов (View Certificates) для отображения экранной формы Управление сертификатами (Certificates)

6. На данной форме переключиться на вкладку Ваши сертификаты (Your Certificates) и активировать экранную кнопку Импортировать (Import)

7. Указать расположение файла, содержащего пользовательский сертификат Fedora, и активировать экранную кнопку Открыть (Open) (размещение сертификата пользователя отображается при выполнении команды fedora-packager-setup; при этом также выполняется запрос на установку пароля доступа к этому сертификату)


После выполнения перечисленных действий пользовательский сертификат Fedora будет отображаться в списке на вкладке Ваши сертификаты (Your Certificates) и появится возможность использования данного сертификата для аутентификации через web-интерфейс сборочной системы koji.

Установка SSL-сертификатов в Chromium

Note.png
Опционально
Перечисленные ниже инструкции необходимы только для выполнения аутентификации через web-интерфейс с использованием интернет-обозревателя Chromium. В общем случае аутентификация с использованием интернет-обозревателя является необязательной.

Для работы с сертификатами Chromium использует NSS Shared DB, для работы с которой необходимо предварительно установить пакет nss-tools.

pk12util -d sql:$HOME/.pki/nssdb -i fedora-browser-cert.p12

Уведомления

После успешного прохождения процедуры аутентификации с использованием web-интерфейса сборочной системы Koji появляется возможность настройки уведомлений для получения сообщений о результатах сборки сопровождаемых пакетов. Для этого после авторизации необходимо выполнить прокрутку содержимого главной страницы и перейти по ссылке Add a notification, расположенной непосредственно над списком настроенных уведомлений.

Сборка с использованием fedpkg

При каждом выполнении операции push СКВ git осуществляет автоматический перенос маркера текущей ветви так, чтобы он указывал на вершину внесенных в нее изменений. Поэтому для выполнения сборки достаточно выполнить команду:

fedpkg build

Данная команда направит в сборочную систему запрос на выполнение сборки пакета для текущей ветви.

Для сборки пакета с использованием определенной сборочной цели koji необходимо выполнить:

fedpkg build --target TARGET

В частности, сборка из ветви rawhide с использованием специальной сборочной цели как, например, dist-f14-python, включенной подразделением разработки и сопровождения выпусков (release engineering) для маркировки пакетов с обновленным программным интерфейсом (API), может быть осуществлена с помощью команды:

fedpkg build --target 'dist-f14-python'

Сцепленные сборки

Warning.png
Сцепленные сборки могут использоваться только для ветви разработки devel/ (называемой также rawhide). Выполнение сцепленных сборок пакетов для обновления существующих выпусков ОС требует настройки с помощью bodhi переопределений для правильного включения запрашиваемых пакетов в состав сборочных окружений.

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

fedpkg chain-build libwidget libgizmo

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

fedpkg chain-build libwidget libaselib : libgizmo :

сначала будет осуществлена параллельная сборка пакетов libwidget и libaselib, затем будет собран пакет libgizmo, после сборки которого - пакет из текущего каталога. Если группы не заданы выполняется последовательная сборка всех перечисленных пакетов.

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

Пробные сборки

Одной из полезных возможностей сборочной системы является возможность выполнения сборки пакетов без последующего включения результатов в состав какого-либо выпуска дистрибутива. Такая возможность называется пробной сборкой. Далее в настоящем подразделе приводится описание порядка использования как непосредственно утилиты koji, так и инструментального средства fedpkg для выполнения пробных сборок. Для осуществления пробной сборки пакета с использованием последних внесенных, но еще незакрепленных изменений необходимо выполнить последовательность команд:

rpmbuild -bs foo.spec
koji build --scratch rawhide foo.srpm

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

koji build --scratch rawhide 'git url'

Предупреждение: Пробные сборки не будут работать корректно если spec-файл использует значения %fedora, %fc9 и т.п. для выполнения различных действий. Значения перечисленных макроопределений устанавливаются сборщиком, а не самой утилитой koji, так что значение %fedora будет установлено в соответствии с настройками среды, в которой создается RPM-пакет исходных текстов, а не той, в которой данный пакет будет собран. При выполнении обычных сборок подобного явления не возникает, т.к. производится предварительная пересборка RPM-пакета исходных текстов.

Если изменения для пакета были зафиксированы в СКВ git, то пробную сборку для текущей ветви можно осуществить с помощью утилиты fedpkg, которая вызывает koji, передавая последней необходимые параметры:

fedpkg scratch-build

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

fedpkg scratch-build-<archs>

Значением <archs> явлвется список идентификаторов архитектур, разделенных символом запятой.

Кроме этого, также имеется возможность вызова операции scratch-build с указанием требуемой сборочной цели koji:

fedpkg scratch-build --target TARGET

Для получения дополнительной информации можно использовать fedpkg scratch-build --help или koji build --help.

Неуспешные сборки

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

420066 buildArch kernel-2.6.18-1.2739.10.9.el5.jjf.215394.2.src.rpm,
ia64): open (build-1.example.com) -> FAILED: BuildrootError:
error building package (arch ia64), mock exited with status 10

Для выяснения причины неуспешного завершения сборки можно исследовать сохраненные файлы журналов сборки. При этом, если файл с именем build.log существует, то проверку следует начинать с него. В противном случае сначала необходимо проверить файл init.log.

Файлы журналов сборки доступны для просмотра через web-интерфейс по адресам со страницы, содержащей сведения о неуспешно завершенной задаче. В качестве альтернативного метода для просмотра файлов журналов может использоваться клиентское приложение koji, вызванное с командой watch-logs. Более подробное описание содержится в сообщениях помощи для указанной команды.

Более сложные варианты использования утилиты koji

Утилита командной строи koji имеет мнемонические имена команд, по каждой из которых может быть получена интерактивная справка. Так, в частности, данная утилита может выводить список всех допустимых команд, а также реализует поддержку параметра --help для каждой из них. Примеры:

$ koji help

Koji commands are:
build                Build a package from source
cancel-task          Cancel a task
help                 List available commands
latest-pkg           Print the latest builds for a tag
[...] 
$ koji build --help

usage: koji build [options]  tag URL
(Specify the --help global option for a list of other help options)

options:
-h, --help            show this help message and exit
--skip-tag            Do not attempt to tag package
--scratch             Perform a scratch build
--nowait              Don't wait on build
[...] 

Использование koji для получения конфигурации сборочного окружения mock

С помощью утилиты koji возможно получение конфигурации сборочного окружения mock для последующей реконструкции сборочной среды, например, для выполнения ручной отладки.

koji mock-config --help
Usage: koji mock-config [options] name
(Specify the --help global option for a list of other help options)

Options:
  -h, --help            show this help message and exit
  --arch=ARCH           Specify the arch
  --tag=TAG             Create a mock config for a tag
  --task=TASK           Duplicate the mock config of a previous task
  --buildroot=BUILDROOT
                        Duplicate the mock config for the specified buildroot
                        id
  --mockdir=DIR         Specify mockdir
  --topdir=DIR          Specify topdir
  --topurl=URL          url under which Koji files are accessible
  --distribution=DISTRIBUTION
                        Change the distribution macro
  -o FILE               Output to a file

К примеру, для получения конфигурации последнего сборочного окружения для тега dist-f12-build может быть выполнена команда:

koji mock-config --tag dist-f12-build --arch=x86_64 --topurl=http://kojipkgs.fedoraproject.org/ dist-f12

При выполнении команды mock-config необходимо передавать параметр --topurl=http://kojipkgs.fedoraproject.org/ для получения рабочей конфигурации mock из сборочной системы Koji для Fedora.

Использование koji для управления задачами

Вывод списка задач:

koji list-tasks

Вывод списка задач текущего пользователя:

koji list-tasks --mine

Повторное выполнение ранее обработанной задачи (общий вид): koji resubmit [options] taskID

koji resubmit 3

Сборка пакетов с помощью утилиты koji

Вместо использования команды fedpkg для выполнения операции сборки пакетов также возможен непосредственный вызов утилиты командной строки koji.

Формат вызова koji для этой цели следующий:

$ koji build <build target> <git URL>

Пример:

Warning.png
Значение dist-f14 следует заменить на имя сборочной цели, используемой для сборки, например dist-rawhide
$ koji build dist-f14 'git url'

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

ПРИМЕЧАНИЕ: При использовании koji для сборки пакетов Fedora, значение git url ДОЛЖНО адресовать ресурс pkgs.fedoraproject.org. Какие-либо другие репозитории git для выполнения сборок применяться не могут.

Теги сборочной системы Koji и организация пакетов

Терминология

При работе со сборочной системой Koji необходимо различать значения таких понятий как пакет, сборка пакета и rpm-файл, являющийся результатом этой сборки. Перечисленные понятия интерпретируются следующим образом:

  • Пакет: Означает имя rpm-пакета исходных текстов. Данное понятие определяет пакет вообще, а не какую-либо его сборку или какой-либо его субпакет. Примеры: kernel, glibc, и т.д.
  • Сборка: Означает некоторую сборку пакета. Данное понятие определяет сборку некоторой версии пакета и включает все архитектуры и субпакеты. Примеры: kernel-2.6.9-34.EL, glibc-2.3.4-2.19.
  • RPM: Конкретный rpm-файл. Данное понятие определяет некоторый (суб)пакет для какой-либо архитектуры, являющийся результатом сборки. Примеры: kernel-2.6.9-34.EL.x86_64, kernel-devel-2.6.9-34.EL.s390, glibc-2.3.4-2.19.i686, glibc-common-2.3.4-2.19.ia64

Теги и сборочные цели

В сборочной системе Koji применяется организация пакетов с использованием тегов. Тег в Koji определяет некоторое подмножество пакетов:

  • Теги поддерживают наследование свойств
  • Каждый тег связан со своим (наследуемым) списком включенных в его состав пакетов
  • Владельцы пакетов (наследуемый признак) могут различаться в зависимости от тега
  • При выполнении операции сборки указывается сборочная цель, но не тег

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

Команды Koji для работы с тегами

Сборочные цели

Полный список установленных сборочных целей может быть получен выполнением команды:

$ koji list-targets

Для просмотра сведений об определенной сборочной цели применяется параметр --name:

$ koji list-targets --name dist-f14

Name                           Buildroot                      Destination
---------------------------------------------------------------------------------------------
dist-f14                     dist-f14-build                 dist-f14

В данном случае при выполнении сборки с использованием сборочной цели dist-f14 сборочное окружение будет формироваться из пакетов, помеченых тегом dist-f14-build, а пакеты, полученные в результате сборки будут помечаться тегом dist-f14.

Замечание: Сборочная цель dist-rawhide использоваться не должна. Вместо этого, если последним изданным выпуском является Fedora N, то при сборке пакета для последующего выпуска следует использовать сборочную цель dist-f{N+1}.

Теги

Полный список установленных тегов может быть получен выполнением команды:

$ koji list-tags
Пакеты

В соответствии с вышеизложенным, каждый тег связан со списком пакетов, результаты сборки которых могут помечаться данным тегом. Для просмотра списка пакетов тега используется команда list-pkgs:

$ koji list-pkgs --tag dist-f14

В отображаемом при выполнении команды списке, в первом столбце выводится имя пакета, во втором - имя тега, от которого было унаследованно данное имя, в третьем - имя владельца пакета.

Последние сборки

Для просмотра последних сборок, помеченных некоторым тегом, используется команда latest-pkg:

$ koji latest-pkg --all dist-f14

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