Ubuntu logo

Packaging Guide

2. Общий обзор каталога debian/

Эта статья даёт краткие пояснения к различным файлам, важным для создания пакетов Ubuntu, которые содержатся в каталоге debian/. Самыми важными из них являются changelog, control, copyright, and rules. Они требуются для всех пакетов. Многие дополнительные файлы в debian/ могут использоваться для настройки и изменения поведения пакета. Некоторые из этих файлов обсуждаются в этой статье, но это далеко не полный список.

2.1. Файл changelog

Этот файл, как следует из его названия — это список изменений, внесённых в каждую версию. Он имеет особый формат, который показывает имя пакета, версию, дистрибутив, изменения, и кто вносил изменения в данное время. Если у вас есть ключ GPG (смотрите: Подготовка), убедитесь, что вы используете в changelog те же имя и адрес электронной почты, что и в вашем ключе. Ниже приведен шаблон changelog:

package (version) distribution; urgency=urgency

 * change details
  - more change details
 * even more change details

-- maintainer name <email address>[two spaces]  date

Формат (особенно даты) важен. Дата должна быть в формате RFC 5322, который можно увидеть при выполнении команды date -R. Для удобства, можно использовать для редактирования changelog команду dch. Она обновит дату автоматически.

Пункты с незначительными изменениями отмечаются дефисом «-», в то время как в важных пунктах используется звездочка «*».

Если вы создаёте пакет «с нуля», dch --create (dch находится в пакете devscripts) создаст для вас стандартный файл debian/changelog.

Вот пример файла changelog для hello:

hello (2.8-0ubuntu1) trusty; urgency=low

  * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe <packager@example.com>  Thu, 21 Oct 2013 11:12:00 -0400

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

Ubuntu и Debian используют немного различающиеся схемы нумерации версий пакетов, чтобы избежать конфликта пакетов с одной и той же исходной версией. Если пакет Debian был изменён в Ubuntu, к концу Debian-версии добавляется ubuntuX (где X — номер редакции в Ubuntu). Таким образом, если пакет Debian hello 2.6-1 был изменён в Ubuntu, номер версии будет 2.6-1ubuntu1. Если пакет приложения в Debian не существует, то редакция Debian равна 0 (например, 2.6-0ubuntu1).

Более подробную информацию можно найти на странице changelog (Глава 4.4) документа Debian Policy Manual.

2.2. Файл control

Файл control содержит информацию, которую использует менеджер пакетов (такой, как apt-get, synaptic или adept), сборочные зависимости, информацию мэйнтейнера и многое другое.

Для пакета Ubuntu hello файл control выглядит следующим образом:

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XSBC-Original-Maintainer: Jane Doe <packager@example.com>
Standards-Version: 3.9.5
Build-Depends: debhelper (>= 7)
Vcs-Bzr: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
 The GNU hello program produces a familiar, friendly greeting. It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them. Seriously, though: this is
 an example of how to do a Debian package. It is the Debian version of
 the GNU Project's `hello world' program (which is itself an example
 for the GNU Project).

Первый абзац описывает исходный пакет, включая список пакетов, требуемых для сборки данного пакета из исходного кода, в поле Build-Depends. Он также содержит некоторую метаинформацию, такую как имя мэйнтейнера, версию Debian Policy, с которой компилируется пакет, местоположение репозитория управления версиями и домашнюю страницу апстрима.

Заметьте, что в Ubuntu мы указываем в поле Maintainer общий адрес, так как любой человек может изменить любой пакет (в отличие от Debian, где правом изменения пакетов обладают лишь отдельные люди или команда). Пакеты в Ubuntu, как правило, должны в поле Maintainer содержать Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>. Если поле Maintainer изменено, старое значение должно быть сохранено в поле XSBC-Original-Maintainer. Это можно сделать автоматически сценарием update-maintainer из пакета ubuntu-dev-tools. Для дальнейшей информации смотрите Debian Maintainer Field spec в Ubuntu wiki.

Каждый дополнительный абзац описывает бинарный пакет, который будет создан.

Более подробную информацию можно найти на странице секции control-файла (Глава 5) документа Debian Policy Manual.

2.4. Файл rules

Последний файл, который мы рассмотрим, это rules. Он выполняет всю работу по сборке нашего пакета. Это Makefile, в котором есть функции компиляции программы, её установки и создания .deb-пакета из установленных файлов. В нём есть также функция очистки файлов сборки, которая удаляет всё, кроме собственно пакета исходного кода.

Вот упрощённый пример файла rules, созданного dh_make (который можно найти в пакете dh-make):

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
       dh  $@

Давайте рассмотрим этот файл внимательнее. На каждом этапе сборки debian/rules вызывается с аргументом, который передаётся /usr/bin/dh, который, в свою очередь, вызывает необходимые команды dh_*.

dh запускает последовательность команд debhelper. Поддерживаемые последовательности соответствуют целям файла debian/rules: «build», «clean», «install», «binary-arch», «binary-indep» и «binary». Чтобы увидеть, какие команды выполняются в каждой цели, наберите:

$ dh binary-arch --no-act

Командам из последовательности binary-indep передаётся аргумент -i, чтобы они затрагивали только архитектурно-независимые пакеты, а командам из последовательности binary-arch — аргумент -a, чтобы онм затрагивали только архитектурно-зависимые пакеты.

Каждая команда debhelper при её успешном выполненении делает запись в журнале debian/package.debhelper.log (который затем удаляет dh_clean.) Таким образом dh может определить, какие команды уже были выполнены и для каких пакетов, что помогает избежать повторного выполнения этих команд.

При каждом запуске dh он изучает журнал, находит добавленные последними команды, которые относятся к указанной последовательности. Затем он продолжает выполнение со следующей команды в этой последовательности. Опции --until, --before, --after и --remaining могут изменить это поведение.

Если в debian/rules есть функция с именем, похожим на override_dh_команда, то вместо данной команды dh выполнит данную функцию. Эта функция может запустить ту же команду с другими аргументами, или же совершенно другую команду. (Замечание: для использования этой функциональности при сборке требуется пакет debhelper версии не менее 7.0.50).

За дополнительными примерами обратитесь к /usr/share/doc/debhelper/examples/ и man dh. Смотрите также раздел о файле rules (Раздел 4.9) в «Debian Policy Manual».

2.5. Дополнительные файлы

2.5.1. Файл install

Файл install используется dh_install для установки файлов в двоичный пакет. Он имеет два стандартных варианта использования:

  • Для установки в ваш пакет файлов, не установленных оригинальной системой сборки.

  • Разделение одного большого пакета источника на несколько бинарных пакетов.

В первом случае файл install должен содержать одну строку для каждого устанавливаемого файла, указывающую как файл, так и установочный каталог. Например, следующий файл install установит сценарий foo из корневого каталога пакета исходного кода в usr/bin и desktop-файл из каталога debian в usr/share/applications:

foo usr/bin
debian/bar.desktop usr/share/applications

Если пакет исходного кода производит несколько двоичных пакетов, dh установит файлы в debian/tmp вместо установки непосредственно в debian/<пакет>. Файлы, установленные в debian/tmp затем можно переместить в отдельные двоичные пакеты с помощью нескольких файлов $имя_пакета.install. Это часто делается, чтобы разбить большое количество не зависящих от архитектуры данных из зависящих от архитектуры пакетов в пакеты Architecture: all. В этом случае нужно указать только имена устанавливаемых файлов (или каталогов), без установочного каталога. Например, foo.install, содерщащий только зависящие от архитектуры файлы, может выглядеть наподобие:

usr/bin/
usr/lib/foo/*.so

В то время как foo-common.install, содержащий только не зависящие от архитектуры файлы, может выглядеть так:

/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/

Будут созданы два двоичных пакета: foo и foo-common. Для обоих требуется их собственный абзац в debian/control.

Для дополнительных подробностей смотрите man dh_install и раздел о файле install (Раздел 5.11) в «Debian New Maintainers’ Guide».

2.5.2. Файл watch

Файл debian/watch позволяет автоматически проверять наличие новых версий в апстриме с помощью инструмента uscan из пакета devscripts. Первой строкой файла watch должна быть версия формата (3 на момент написания этого руководства), а следующий строки содержат любые URL для анализа. Например:

version=3

http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

Запуск uscan в корневом каталоге исходников сравнит номер апстрим-версии в debian/changelog с последней доступной в апстриме версией. Если в апстриме найдена новая версия, она будет автоматически загружена. Например:

$ uscan
hello: Newer version (2.7) available on remote site:
  http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
  (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

Если ваши tarball-файлы обитают на Launchpad, файл debian/watch имеет немного более сложный вид (о том, почему это так, смотрите Question 21146 и Bug 231797). В этому случае используйте нечто вроде:

version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

Дополнительные сведения смотрите в man uscan и в разделе о файле watch (Раздел 4.11) «Debian Policy Manual».

Список пакетов, для которых файл watch сообщает о том, что они не синхронизированы с апстримом, смотрите Ubuntu External Health Status.

2.5.3. Файл source/format

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

  • 3.0 (native) для «родных» пакетов Debian (апстрим-версия отсутствует)

  • 3.0 (quilt) для пакетов с отдельным тарболом из апстрима

  • 1.0 для пакетов, желающих явно указать формат по умолчанию

В настоящее время по умолчанию выбирается формат пакета исходного кода 1.0, если этот файл отсутствует. В файле source/format можно указать его явно. Если вы не используете этот файл для указания формата исходного кода, Lintian выдаст предупреждение об отстутствии файла. Это чисто информационное предупреждение и его можно без опасений проигнорировать.

Рекомендуется использовать более новый формат 3.0. Он предоставляет некоторые новые возможности:

  • Поддержка дополнительных форматов сжатия: bzip2, lzma и xz

  • Поддержка нескольких архивов с оригинальным исходным кодом

  • Необязательно перепаковывать архив с оригинальным исходным кодом, чтобы удалить директорию debian.

  • Специфичные для Debian изменения теперь хранятся не в одном файле .diff.gz, а в виде нескольких патчей, совместимых с quilt, в каталоге debian/patches/

https://wiki.debian.org/Projects/DebSrc3.0 содержит дополнительную информацию касательно перехода на версию 3.0 формата исходных пакетов.

Дополнительную информацию можно найти в man dpkg-source и в Главе source/format (Глава 5.21) руководства Debian New Maintainers.

2.6. Дополнительные ресурсы

Кроме Debian Policy Manual, на который ссылается статья, руководство Debian New Maintainers’ Guide содержит более детальное описание для каждого файла. Глава 4, “Необходимые файлы в папке debian” описывает файлы control, changelog, copyright и rules. Глава 5, “Прочие файлы в папке debian” описывает дополнительные файлы, которые можно использовать.