Глава 4. Обязательные файлы в каталоге debian

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

В каталоге c исходным кодом программы появился новый подкаталог debian . В нём содержится несколько файлов, которые нужно отредактировать для изменения свойств пакета. Наиболее важные из них: control , changelog , copyright и rules ; они обязательны для всех пакетов [27] .

4.1. Файл control

Этот файл содержит информацию, которая используется программами dpkg , dselect , apt-get , apt-cache , aptitude и некоторыми другими инструментами для работы c пакетами. Он описан в руководстве по политике Debian, в главе 5 «Управляющие файлы и их поля».

Вот, например, файл control , который был создан для нас программой dh_make :

(номера строк добавлены для наглядности)

Lines 1–7 are the control information for the source package. Lines 9–13 are the control information for the binary package.

В строке 1 содержится название пакета с исходным кодом.

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

Возможно вы уже заметили, что архив Debian разбит на несколько областей: main (свободное ПО), non-free (не совсем свободное ПО) и contrib (свободное ПО, зависящее от несвободного ПО). Каждая из них делится на разделы, чтобы приближённо разделить пакеты по категориям. Так, в admin содержатся программы только для администратора, в devel хранятся инструменты разработки ПО, в doc содержится документация, в libs содержатся библиотеки, в mail содержатся почтовые серверы и программы чтения почты, в net содержатся сетевые приложения и службы, в x11 содержатся программы для X11, которые не вошли куда-то ещё, и так далее [28] .

В нашем случае мы должны указать x11 (префикс main/ указывать не обязательно — он подставляется по умолчанию).

В строке 3 указывается насколько важен данный пакет [29] :

Приоритет optional , обычно, назначается новым пакетам, которые не конфликтуют с другими, имеющими приоритет required , important или standard .

Значения раздела и приоритета учитываются в интерфейсах управления пакетами (например, в aptitude ) при сортировке и выборе пакетов. При размещении пакета в архиве Debian значения этих полей могут быть изменены администратором архива, о чём вам будет сообщено по электронной почте.

Так как наш пакет имеет обычный приоритет и не конфликтует с другими, мы укажем значение приоритета optional .

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

Line 5 includes the list of packages required to build your package as the Build-Depends field. You can also have the Build-Depends-Indep field as an additional line here. [30] Some packages like gcc and make which are required by the build-essential package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary package dependencies to find out more about the syntax of these lines.

Для всех пакетов, упаковываемых с помощью команды dh , в файле debian/rules вам потребуется указать debhelper (>=9) в поле Build-Depends для соответствия требованиям политики Debian, касающимся цели clean .

Source packages which have binary packages with Architecture: any are rebuilt by the autobuilder. Since this autobuilder procedure installs only the packages listed in the Build-Depends field before running debian/rules build (see Раздел 6.2, «Autobuilder»), the Build-Depends field needs to list practically all the required packages, and Build-Depends-Indep is rarely used.

В пакетах с исходным кодом, в двоичных пакетах которых указано Architecture: all , поле Build-Depends-Indep может содержать все требуемые пакеты, не перечисленные в Build-Depends , для соответствия требованиям политики Debian, касающимся цели clean .

Если вы не знаете, какое из двух полей использовать — остановитесь на поле Build-Depends [31] .

Для выяснения того, какие пакеты требуются для сборки, выполните команду:

Для ручного, более точного поиска зависимостей программы /usr/bin/foo выполните:

and for each library listed (e.g., libfoo.so.6 ), execute

Затем укажите -dev версию каждого пакета в поле Build-Depends . Если для этой цели воспользоваться ldd , то вы, помимо прочего, узнаете неявные библиотечные зависимости библиотеки и столкнётесь с проблемой избыточных сборочных зависимостей.

Кроме того, пакет gentoo требует для сборки пакеты xlibs-dev , libgtk1.2-dev и libglib1.2-dev . Укажите их после пакета debhelper .

В строке 6 указывается версия документа руководства по политике Debian, стандартам которого следует данный пакет. Прочитайте его при создании пакета.

В строке 7 можно указать URL домашней страницы программы.

В строке 9 содержится имя двоичного пакета. Обычно, оно совпадает с именем пакета с исходным кодом, но это не является обязательным требованием.

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

Генерируемый двоичный пакет зависит от архитектуры, обычно определяемой компилируемым языком.

Генерируемый двоичный пакет не зависит от архитектуры, обычно в нём содержится текст, изображения или сценарии интерпретируемого языка.

Мы не будет менять строку 10, так как программа написана на C. Утилита dpkg-gencontrol (1) подставит соответствующее значение архитектуры машины, на которой будет скомпилирован пакет с исходным кодом.

Если ваш пакет не зависит от архитектуры (например, это документ, сценарий оболочки или Perl), укажите значение all и прочитайте Раздел 4.4, «Файл rules », в котором описаны правила использования binary-indep вместо binary-arch .

В строке 11 показана одна из мощнейших сторон пакетной системы Debian. Пакеты могут быть связаны друг с другом различными способами. Кроме поля Depends за отношения между пакетами отвечают Recommends , Suggests , Pre-Depends , Breaks , Conflicts , Provides и Replaces .

Инструменты управления пакетами, обычно, одинаковым образом обрабатывают эти связи; если это так, то будет приведён комментарий (смотрите dpkg (8) , dselect (8) , apt (8) , aptitude (1) и т.д.).

Вот упрощённое описание связей между пакетами [33] :

Пакет не будет установлен, пока не установлены пакеты, от которых он зависит. Используйте этот тип зависимости, если ваша программа гарантировано не будет работать (или вызовет какие-нибудь серьезные проблемы) при отсутствии какого-то пакета.

Используйте это поле для пакетов, которые не обязательны, но обычно используются с вашей программой. При установке программы все интерфейсы управления пакетами предложат пользователю установить и рекомендуемые пакеты. Утилиты aptitude и apt-get по умолчанию (которое можно изменить) автоматически устанавливают рекомендуемые пакеты вместе с пакетом. Утилита dpkg игнорирует это поле.

Используйте это поле для пакетов, которые отлично дополнят вашу программу, но не требуются для её работы. При установке программы интерфейсы управления пакетами, обычно, не предлагают пользователю установить такие пакеты. В aptitude можно включить автоматическую установку этих предлагаемых (suggested) пакетов (по умолчанию не выполняется). Программы dpkg и apt-get игнорируют это поле.

В этом поле указываются более важные зависимости, чем в Depends . Пакет не будет установлен, если какие-либо пакеты из числа таких зависимостей не установлены, либо не правильно настроены . Используйте это поле очень осторожно и только после обсуждения в рассылке debian-devel@lists.debian.org. Ещё лучше — не используйте его вообще :-)

Пакет не будет установлен, пока все перечисленные в этом поле пакеты не будут удалены. Используйте это поле только, если ваша программа не будет запускаться, либо возникнут серьёзные проблемы при наличии этих пакетов.

Если пакет будет установлен, то работоспособность всех перечисленных пакетов будет нарушена. Чаще всего, в поле Breaks указываются пакеты с уточнением версии типа «старее чем». Утилиты управления пакетами, обычно, предлагают обновить перечисленные пакеты до более новых версий.

For some types of packages where there are multiple alternatives, virtual names have been defined. You can get the full list in the virtual-package-names-list.txt.gz file. Use this if your program provides a function of an existing virtual package.

Используйте данное поле, если ваш пакет заменяет файлы из другого пакета или же полностью заменяет другой пакет (в этом случае вы также должны использовать поле Conflicts ). В этом случае файлы из указанного пакета будут перезаписаны файлами из вашего.

Формат всех этих полей одинаков. Он представляет собой список имён пакетов, разделённых запятыми. Здесь также могут быть указаны имена альтернативных пакетов, разделённые вертикальной чертой | (символ канала).

Для каждого пакета в списке можно указать версии, которых касается данная зависимость. Версии указываются в круглых скобках после имени пакета и должны состоять из символа сравнения, за которым следует номер версии. Допустимыми символами сравнения являются: << , <= , = , >= и >> для «строго раньше», «раньше или равно», «в точности равно», «равно или позже» и «строго позже», соответственно. Например:

В завершение рассмотрим конструкции $ , $ , $ и прочие.

Утилита dh_shlibdeps (1) вычисляет зависимости двоичного пакета от общих библиотек. Она генерирует список исполняемых файлов ELF и общих библиотек, которые находит для каждого двоичного пакета. Этот список подставляется вместо $ .

Утилита dh_perl (1) вычисляет зависимости Perl. Она генерирует список зависимостей от perl или perlapi для каждого двоичного пакета. Этот список подставляется вместо $ .

Некоторые команды пакета debhelper могут добавлять зависимости к вашему генерируемому пакету. Каждая команда генерирует список необходимых пакетов для каждого двоичного пакета. Этот список подставляется вместо $ .

Утилита dh_gencontrol (1) генерирует файл DEBIAN/control для каждого двоичного пакета, заменяя $ , $ , $ и т.д на полученные значения.

В нашем случае, мы можем оставить поле Depends без изменений и добавить после него строчку Suggests: file , так как пакет gentoo использует некоторые возможности пакета file .

В строке 9 указан URL домашней страницы программы. Предположим, что это будет http://www.obsession.se/gentoo/.

В строке 12 содержится краткое описание пакета. Размер экрана у большинства пользователей имеет 80 столбцов, поэтому постарайтесь ограничить описание шестьюдесятью символами. В нашем случае, заполним поле следующим текстом: fully GUI-configurable, two-pane X file manager .

В строке 13 указывается длинное описание. Это должен быть абзац, содержащий более полную информацию о пакете. Каждая строка должна начинаться с пробела. В тексте не должно быть пустых строк. Если пустая строка всё же требуется, то поставьте точку ( . ) в первом столбце. Не выводите более одной пустой строки после длинного описания [34] .

Давайте вставим поля Vcs-* для указания местонахождения системы контроля версий между строкой 6 и 7 [35] . Предположим, что пакет gentoo в качестве VCS использует сервис Debian Alioth Git по адресу git://git.debian.org/git/collab-maint/gentoo.git .

Вот обновлённый файл control :

(номера строк добавлены для наглядности)

4.2. Файл copyright

Этот файл содержит информацию об авторских правах и лицензионное соглашение исходной программы. Его содержание определяется в руководстве по политике Debian, разделе 12.5 «Информация об авторских правах», а формат описан в DEP-5: автоматизируемый debian/copyright .

Шаблон файла copyright можно создать с помощью dh_make . Укажем параметр --copyright gpl2 , чтобы получить файл шаблона для пакета gentoo , выпущенного с лицензией GPL-2.

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, 3-Clause BSD, CC0-1.0, MPL-1.1, MPL-2.0 or the Artistic license), you can just refer to the appropriate file in the /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.

Вкратце, вот как должен выглядеть файл copyright для пакета gentoo :

(номера строк добавлены для наглядности)

Следуйте HOWTO, написанному ftpmaster-ами, и пошлите анонс в debian-devel-announce: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

4.3. Файл changelog

Это обязательный файл, его специальный формат описан в руководстве по политике Debian, раздел 4.4 «debian/changelog». Этот формат используется программой dpkg и другими для получения информации о номере версии, редакции, разделе и срочности пакета.

Для вас он также важен, так как является хорошим местом для описания всех изменений, которые вы сделали. Это поможет людям, скачавшим ваш пакет, определить, какие выпуски есть у пакета, о которых они должны знать. Он будет сохранён как /usr/share/doc/gentoo/changelog.Debian.gz в двоичном пакете.

Программа dh_make создает файл по умолчанию, похожий на этот:

(номера строк добавлены для наглядности)

Line 1 is the package name, version, distribution, and urgency. The name must match the source package name; distribution should be unstable , and urgency should be set to medium unless there is any particular reason for other values.

Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes — there is a special file for that purpose, created by the upstream authors, which you will later install as /usr/share/doc/gentoo/changelog.gz ). Let's assume your ITP (Intent To Package) bug report number was 12345 . New lines must be inserted just below the uppermost line that begins with * (asterisk). You can do it with dch (1) . You can edit this manually with a text editor as long as you follow the formatting convention used by the dch (1) .

In order to prevent a package being accidentally uploaded before completing the package, it is a good idea to change the distribution value to an invalid distribution value of UNRELEASED .

Теперь файл будет выглядеть так:

(номера строк добавлены для наглядности)

После проверки правильности всех изменений и их описания в changelog , измените имя выпуска с UNRELEASED на значение целевого дистрибутива unstable (или даже на experimental ). [36]

Дополнительную информацию об обновлении файла changelog можно найти далее в Глава 8, Обновление пакета.

4.4. Файл rules

Now we need to take a look at the exact rules that dpkg-buildpackage (1) will use to actually create the package. This file is in fact another Makefile , but different from the one(s) in the upstream source. Unlike other files in debian , this one is marked as executable.

Файл rules , как и любой Makefile , состоит из нескольких правил, каждое из которых описывает цель и способ её достижения [37] . Новое правило начинается с объявления цели в первой колонке. Следующие за ним строки начинаются с кода TAB (ASCII 9); в них описывается команды достижения цели. Пустые строки и строки, начинающиеся с # (решётка), считаются комментариями и игнорируются [38] .

A rule that you want to execute is invoked by its target name as a command line argument. For example, debian/rules build and fakeroot make -f debian/rules binary execute rules for build and binary targets, respectively.

Упрощённое объяснение целей:

Цель clean служит для удаления всех скомпилированных, сгенерированных и бесполезных файлов в дереве сборки (требуемая).

Цель build служит для сборки исходного кода в скомпилированные программы и отформатированные документы в дереве сборки (требуемая).

Цель build-arch служит для сборки исходного кода в независящие от архитектуры скомпилированные программы в дереве сборки (требуемая).

Цель build-indep служит для сборки исходного кода в независящие от архитектуры отформатированные документы в дереве сборки (требуемая).

Цель install служит для установки файлов в дерево файлов для каждого двоичного пакета из каталога debian (необязательная). Цели binary* непосредственно зависят от этой цели.

Цель binary служит для создания всех двоичных пакетов (комбинация целей binary-arch и binary-indep ) (требуемая) [39] .

Цель binary-arch служит для создания двоичных пакетов, зависящих от архитектуры ( Architecture: any ), в родительском каталоге (требуемая) [40] .

Цель binary-indep служит для создания двоичных пакетов, независящих от архитектуры ( Architecture: all ), в родительском каталоге (требуемая) [41] .

Цель get-orig-source служит для получения самой новой версии пакета с оригинальным исходным кодом с сайта разработчика (необязательная).

Возможное непонимание должно уйти после того, как вы посмотрите на содержимое файла rules по умолчанию, который создаётся программой dh_make .

Новая версия dh_make генерирует очень простой, но эффективный файл rules по умолчанию, использующий команду dh :

(Для наглядности добавлены номера строк и удалены некоторые комментарии. В реальном файле rules начальные пробельные символы имеют код TAB.)

Вероятно, вы знакомы с назначением строки 1 по сценариям оболочки и Perl. Она указывает операционной системе, что этот файл нужно обработать с помощью /usr/bin/make .

Строку 4 можно раскомментировать, установив значение переменной DH_VERBOSE равным 1. При этом команда dh будет выводить команды dh_* , которые она выполняет. Также, здесь вы можете добавить строку export DH_OPTIONS=-v . В этом случае каждая команда dh_* будет выводить все команды, которые она выполняет. Это помогает понять что в действительности происходит в этом простом файле rules и при решении проблем. Новая команда dh является основной инструментов debhelper и не скрывает своих действий от вас.

Lines 16 and 17 are where all the work is done with an implicit rule using the pattern rule. The percent sign means "any targets", which then call a single program, dh , with the target name. [42] The dh command is a wrapper script that runs appropriate sequences of dh_* programs depending on its argument. [43]

При запуске debian/rules clean выполняется команда dh clean , которая запускает другие:

debian/rules build runs dh build , which in turn runs the following:

fakeroot debian/rules binary runs fakeroot dh binary , which in turn runs the following [44] :

fakeroot debian/rules binary-arch runs fakeroot dh binary-arch , which in turn runs the same sequence as fakeroot dh binary but with the -a option appended for each command.

fakeroot debian/rules binary-indep runs fakeroot dh binary-indep , which in turn runs almost the same sequence as fakeroot dh binary but excluding dh_strip , dh_makeshlibs , and dh_shlibdeps with the -i option appended for each remaining command.

Назначение команд dh_* практически полностью совпадает с их именами [45] . Вот несколько наиболее примечательных команд с упрощённым описанием, предполагающим использование типичной среды сборки на основе Makefile [46] :

Если существует Makefile с целью distclean , то dh_auto_clean , обычно, выполняет следующее [47] :

Команда dh_auto_configure , обычно, выполняет следующее (если существует ./configure ; список аргументов сокращён для повышения читаемости):

Команда dh_auto_build , обычно, выполняет следующее для первой цели в Makefile (если он существует):

Команда dh_auto_test , обычно, выполняет следующее (если существует Makefile с целью test ; строка сокращена для повышения читаемости) [48] :

Команда dh_auto_install , обычно, выполняет следующее (если существует Makefile с целью install ; строка сокращена для повышения читаемости):

Цели, которым требуется команда fakeroot , содержат dh_testroot . Если вы не притворитесь root с помощью этой команды, то выполнение завершится с ошибкой.

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

Хотя цель install не является обязательной, она всё равно поддерживается. Команда fakeroot dh install работает также как fakeroot dh binary , но останавливается после dh_fixperms .

Есть много способов доработать файл rules , созданный новой программой dh .

Работу команды dh $@ можно изменить следующим образом [49] :

Добавление поддержки команды dh_python2 (лучший выбор для Python) [50] :

В Build-Depends укажите пакет python .

Используйте dh $@ --with python2 .

Это позволяет работать с модулями Python, использующими инфраструктуру python .

Добавление поддержки команды dh_pysupport (устарела):

В Build-Depends укажите пакет python-support .

Используйте dh $@ --with pysupport .

Это позволяет работать с модулями Python, использующими инфраструктуру python-support .

Добавление поддержки команды dh_pycentral (устарела):

В Build-Depends укажите пакет python-central .

Вместо dh $@ используйте dh $@ --with python-central .

При этом отключается команда dh_pysupport .

Это позволяет работать с модулями Python, использующими инфраструктуру python-central .

Добавление поддержки команды dh_installtex :

В Build-Depends укажите пакет tex-common .

Вместо dh $@ используйте dh $@ --with tex .

Она регистрирует шрифты в формате Type 1, правила переносов или форматы в TeX.

Добавление поддержки команд dh_quilt_patch и dh_quilt_unpatch :

В Build-Depends укажите пакет quilt .

Вместо dh $@ используйте dh $@ --with quilt .

Эта команда накладывает и откатывает заплаты на исходный код из файлов каталога debian/patches для пакетов с исходным кодом версии 1.0 .

Она не требуется, если вы используете пакеты с исходным кодом новой версии 3.0 (quilt) .

Добавление поддержки команды dh_dkms :

В Build-Depends укажите пакет dkms .

Вместо dh $@ используйте dh $@ --with dkms .

Это команда позволяет корректно использовать DKMS для пакетов с модулями ядра.

Добавление поддержки команд dh_autotools-dev_updateconfig и dh_autotools-dev_restoreconfig :

В Build-Depends укажите пакет autotools-dev .

Вместо dh $@ используйте dh $@ --with autotools-dev .

Эта команда обновляет и восстанавливает config.sub и config.guess .

Добавление поддержки команд dh_autoreconf и dh_autoreconf_clean :

В Build-Depends укажите пакет dh-autoreconf .

Вместо dh $@ используйте dh $@ --with autoreconf .

Эта команда обновляет файлы GNU Build System и восстанавливает их после сборки.

Добавление поддержки команды dh_girepository :

Укажите пакет gobject-introspection в Build-Depends .

Вместо dh $@ используйте dh $@ --with gir .

Эта команда вычислит зависимости пакетов, содержащих описательные (introspection) данные GObject и сгенерирует переменную подстановки $ для пакетной зависимости.

Добавление поддержки свойства автодополнения bash :

Укажите пакет bash-completion в Build-Depends .

Вместо dh $@ используйте dh $@ --with bash-completion .

Эта команда установит дополнения bash согласно файлу настройки debian/ пакет .bash-completion .

Многие команды dh_* , вызываемые новой командой dh , могут быть настроены в соответствующих конфигурационных файлах в каталоге debian . Смотрите Глава 5, Другие файлы в каталоге debian/ и справочную страницу к каждой команде для настройки этих параметров.

Некоторые команды dh_* , вызванные новой командой dh , могут потребовать от вас запустить их с некоторыми аргументами, выполнить вместе с ними дополнительные команды или пропустить их. В таких случаях надо создать цель override_dh_ foo с правилами в файле rules только для той команды dh_ foo , которую вы собираетесь изменить. Она воспринимается как запусти меня вместо той [51] .

Заметим, что команды dh_auto_* пытаются делать больше, чем было описано (очень) поверхностно ранее, для того, чтобы учесть все возможные ситуации. Использование упрощённых эквивалентов команд вместо целей override_dh_* — плохая идея (за исключением цели override_dh_auto_clean ), так как это может привести к удалению важных функций debhelper .

Так, например, если вы хотите хранить системные файлы настройки пакета gentoo (использующего Autotools) в каталоге /etc/gentoo вместо обычного /etc , то можете переопределить аргумент --sysconfig=/etc , заданный по умолчанию, в команде dh_auto_configure , которая передаст его ./configure :

The arguments given after -- are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than directly invoking the ./configure command here since it will only override the --sysconfig argument and retain any other, benign arguments to the ./configure command.

Если Makefile из исходного кода gentoo требует от вас указания build в качестве цели для сборки [52] , то для этого можно создать цель override_dh_auto_build .

Это гарантирует выполнение $(MAKE) со всеми аргументами по умолчанию, заданными в командах dh_auto_build и аргументе build .

Если Makefile из исходного кода gentoo требует от вас указания цели packageclean для очистки пакета Debian, а не distclean или clean , то для этого можно создать цель override_dh_auto_clean .

Если Makefile из исходного кода gentoo содержит цель test , которую вы не хотите выполнять для процесса сборки пакета Debian, то можно использовать пустую цель override_dh_auto_test , чтобы пропустить это действие.

Если в пакете gentoo используется необычный журнальный файл с именем FIXES , то по умолчанию dh_installchangelogs не установит этот файл. Для его установки укажите команде dh_installchangelogs имя FIXES в качестве аргумента [53] .

При работе с новой командой dh , используйте явные цели, перечисленные в Раздел 4.4.1, «Цели из файла rules », остальные же (кроме get-orig-source ) могут привести к сложностям понимания их конечного эффекта. Если возможно, ограничьтесь явно заданными целями override_dh_* и полностью независимыми целями.

[27] Для простоты в этой главе файлы в каталоге debian указаны без начального debian/ .