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

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

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

 1 Source: gentoo
 2 Section: unknown
 3 Priority: extra
 4 Maintainer: Josip Rodin <joy-mg@debian.org>
 5 Build-Depends: debhelper (>=9)
 6 Standards-Version: 3.9.4
 7 Homepage: <insert the upstream URL, if relevant>
 8
 9 Package: gentoo
10 Architecture: any
11 Depends: ${shlibs:Depends}, ${misc:Depends}
12 Description: <insert up to 60 chars description>
13  <insert long description, indented with spaces>

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

Строки 1-7 содержат управляющую информацию для пакета с исходным кодом. Строки 9-13 содержат управляющую информацию для двоичного пакета.

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

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

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

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

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

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

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

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

В строке 5 содержится список пакетов, необходимых для сборки вашего пакета; это значение присваивается полю Build-Depends. Также, здесь можно вставить дополнительную строку с полем Build-Depends-Indep ^[30]. Некоторые пакеты (например, gcc и make), требуемые пакетом build-essential, будут подставлены автоматически в список зависимостей. Если вам требуются дополнительные инструменты сборки — добавьте их в эту строку. В качестве разделителя элементов используется запятая. Для более подробного ознакомления с синтаксисом этой строки обратитесь к материалам по зависимостям двоичных пакетов.

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

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

$ dpkg-depcheck -d ./configure

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

$ objdump -p /usr/bin/foo | grep NEEDED

и для каждой найденной библиотеки, например, libfoo.so.6, выполните:

$ dpkg -S libfoo.so.6

Затем укажите -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].

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

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

Depends: foo (>= 1.2), libbar1 (= 1.3.4)
Conflicts: baz
Recommends: libbaz4 (>> 4.0.7)
Suggests: quux
Replaces: quux (<< 5), quux-foo (<= 7.6)

В завершение рассмотрим конструкции ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends} и прочие.

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

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

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

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

В нашем случае, мы можем оставить поле 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:

 1 Source: gentoo
 2 Section: x11
 3 Priority: optional
 4 Maintainer: Josip Rodin <joy-mg@debian.org>
 5 Build-Depends: debhelper (>=9), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 3.9.4
 7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
 9 Homepage: http://www.obsession.se/gentoo/
10
11 Package: gentoo
12 Architecture: any
13 Depends: ${shlibs:Depends}, ${misc:Depends}
14 Suggests: file
15 Description: fully GUI-configurable, two-pane X file manager
16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
17  user do (almost) all of the configuration and customizing from within the
18  program itself. If you still prefer to hand-edit configuration files,
19  they're fairly easy to work with since they are written in an XML format.
20  .
21  gentoo features a fairly complex and powerful file identification system,
22  coupled to an object-oriented style system, which together give you a lot
23  of control over how files of different types are displayed and acted upon.
24  Additionally, over a hundred pixmap images are available for use in file
25  type descriptions.
26  .
29  gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
30  for its interface.

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

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

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

В этом файле вы должны указать отсутствующую информацию, например, откуда был получен пакет, действующее уведомление об авторском праве и лицензию. Список распространённых лицензий на свободное ПО: 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 или Artistic. Их тексты можно найти в соответствующих файлах в каталоге /usr/share/common-licenses/, который есть в каждой системе Debian. В противном случае вы должны включить файл с полным текстом лицензии.

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

 1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
 2 Name: gentoo
 3 Maintainer: Josip Rodin <joy-mg@debian.org>
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
 7 License: GPL-2+
 8
 9 Files: icons/*
10 Copyright: 1998 Johan Hanson <johan@tiq.com>
11 License: GPL-2+
12
13 Files: debian/*
14 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
15 License: GPL-2+
16
17 License: GPL-2+
18  This program is free software; you can redistribute it and/or modify
19  it under the terms of the GNU General Public License as published by
20  the Free Software Foundation; either version 2 of the License, or
21  (at your option) any later version. 
22  .
23  This program is distributed in the hope that it will be useful,
24  but WITHOUT ANY WARRANTY; without even the implied warranty of
25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26  GNU General Public License for more details.
27  .
28  You should have received a copy of the GNU General Public License along
29  with this program; if not, write to the Free Software Foundation, Inc.,
30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
31  .
32  On Debian systems, the full text of the GNU General Public
33  License version 2 can be found in the file
34  `/usr/share/common-licenses/GPL-2'.

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

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

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

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

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

1  gentoo (0.9.12-1) unstable; urgency=low
2
3   * Initial release (Closes: #nnnn)  <nnnn is the bug number of your ITP>
4
5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
6

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

В строке 1 указано название пакета, версия, редакция, дистрибутив и срочность. Имя должно совпадать с названием пакета с исходным кодом. Дистрибутив должен быть unstable (нестабильный) и срочность не должна заменяться на что-либо большее, чем low (низкая) :-)

В строках 3-5 содержится заметка, в которой описывается сделанное изменение в этой версии пакета (не изменение в самой программе — для этой цели есть специальный файл, созданный автором программы, который будет установлен позднее как /usr/share/doc/gentoo/changelog.gz). Предположим, что номер вашего сообщения об ошибке ITP (Intent To Package) был 12345. Новые строки вставляются как и самая верхняя строка, со звёздочками *. Вы можете сделать это с помощью dch(1)или вручную в текстовом редакторе.

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

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

1  gentoo (0.9.12-1) UNRELEASED; urgency=low
2
3   * Initial Release. Closes: #12345
4   * This is my first Debian package.
5   * Adjusted the Makefile to fix $(DESTDIR) problems.
6
7  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
8

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

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

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

Теперь взглянем на то, какие же правила выполняются программой dpkg-buildpackage(1) для создания пакета. Обычно, файл rules это просто ещё один файл Makefile, но не тот, что прилагается вместе с исходным кодом. В отличие от остальных файлов в каталоге debian, он помечен как исполняемый.