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

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

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

 1 Source: gentoo
 2 Section: unknown
 3 Priority: optional
 4 Maintainer: Josip Rodin <[email protected]>
 5 Build-Depends: debhelper (>=10)
 6 Standards-Version: 4.0.0
 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>

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

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]:

Значения раздела и приоритета учитываются в интерфейсах управления пакетами (например, в 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.

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

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

$ dpkg-depcheck -d ./configure

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

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

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

$ 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 <[email protected]>
 5 Build-Depends: debhelper (>=10), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 4.0.0
 7 Vcs-Git: https://anonscm.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: https://anonscm.debian.org/git/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.

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:

 1 Format: https://www.buy-develop.eu.org/doc/packaging-manuals/copyright-format/1.0/
 2 Upstream-Name: gentoo
 3 Upstream-Contact: Emil Brink <[email protected]>
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Files: *
 7 Copyright: 1998-2010 Emil Brink <[email protected]>
 8 License: GPL-2+
 9
10 Files: icons/*
11 Copyright: 1998 Johan Hanson <[email protected]>
12 License: GPL-2+
13
14 Files: debian/*
15 Copyright: 1998-2010 Josip Rodin <[email protected]>
16 License: GPL-2+
17
18 License: GPL-2+
19  This program is free software; you can redistribute it and/or modify
20  it under the terms of the GNU General Public License as published by
21  the Free Software Foundation; either version 2 of the License, or
22  (at your option) any later version. 
23  .
24  This program is distributed in the hope that it will be useful,
25  but WITHOUT ANY WARRANTY; without even the implied warranty of
26  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27  GNU General Public License for more details.
28  .
29  You should have received a copy of the GNU General Public License along
30  with this program; if not, write to the Free Software Foundation, Inc.,
31  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
32  .
33  On Debian systems, the full text of the GNU General Public
34  License version 2 can be found in the file
35  '/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=medium
2
3   * Initial release. (Closes: #nnnn)  <nnnn is the bug number of your ITP>
4
5  -- Josip Rodin <[email protected]>  Mon, 22 Mar 2010 00:37:31 +0100
6

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

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.

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

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 <[email protected]>  Mon, 22 Mar 2010 00:37:31 +0100
8

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

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

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

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.