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

# Глава 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:

     1 Source: gentoo
     2 Section: unknown
     3 Priority: optional
     4 Maintainer: Josip Rodin <joy-mg@debian.org>
     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]:

- Приоритет `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].

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

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

- `Architecture: any`

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

- `Architecture: all`

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

Мы не будет менять строку 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`

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

- `Recommends`

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

- `Suggests`

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

- `Pre-Depends`

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

- `Conflicts`

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

- `Breaks`

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

- `Provides`

  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.

- `Replaces`

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

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

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

    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 (>=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.

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

## 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`:

     1 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
     2 Upstream-Name: gentoo
     3 Upstream-Contact: Emil Brink <emil@obsession.se>
     4 Source: http://sourceforge.net/projects/gentoo/files/
     5
     6 Files: *
     7 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
     8 License: GPL-2+
     9
    10 Files: icons/*
    11 Copyright: 1998 Johan Hanson <johan@tiq.com>
    12 License: GPL-2+
    13
    14 Files: debian/*
    15 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
    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.

## 4.3. Файл `changelog`

Это обязательный файл, его специальный формат описан в руководстве по политике 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 <joy-mg@debian.org>  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 <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
    8

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

После проверки правильности всех изменений и их описания в `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.

### 4.4.1. Цели из файла `rules`

Файл `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.

### 4.4.2. Файл `rules` по умолчанию

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

     1 #!/usr/bin/make -f
     2 # See debhelper(7) (uncomment to enable)
     3 # output every command that modifies files on the build system.
     4 #DH_VERBOSE = 1
     5
     6 # see FEATURE AREAS in dpkg-buildflags(1)
     7 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
     8
     9 # see ENVIRONMENT in dpkg-buildflags(1)
    10 # package maintainers to append CFLAGS
    11 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
    12 # package maintainers to append LDFLAGS
    13 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
    14
    15
    16 %:
    17         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`, которая запускает другие:

      dh_testdir
      dh_auto_clean
      dh_clean

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

      dh_testdir
      dh_auto_configure
      dh_auto_build
      dh_auto_test

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

      dh_testroot
      dh_prep
      dh_installdirs
      dh_auto_install
      dh_install
      dh_installdocs
      dh_installchangelogs
      dh_installexamples
      dh_installman
      dh_installcatalogs
      dh_installcron
      dh_installdebconf
      dh_installemacsen
      dh_installifupdown
      dh_installinfo
      dh_installinit
      dh_installmenu
      dh_installmime
      dh_installmodules
      dh_installlogcheck
      dh_installlogrotate
      dh_installpam
      dh_installppp
      dh_installudev
      dh_installwm
      dh_installxfonts
      dh_bugfiles
      dh_lintian
      dh_gconf
      dh_icons
      dh_perl
      dh_usrlocal
      dh_link
      dh_compress
      dh_fixperms
      dh_strip
      dh_makeshlibs
      dh_shlibdeps
      dh_installdeb
      dh_gencontrol
      dh_md5sums
      dh_builddeb

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

      make distclean

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

      ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...

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

      make

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

      make test

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

      make install \
        DESTDIR=/путь/к/пакету_версия-редакция/debian/пакет

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

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

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

### 4.4.3. Доработка файла `rules`

Есть много способов доработать файл `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 и сгенерирует переменную подстановки `${gir:Depends}` для пакетной зависимости.

- Добавление поддержки свойства автодополнения 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:

    override_dh_auto_configure:
            dh_auto_configure -- --sysconfig=/etc/gentoo

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`.

    override_dh_auto_build:
            dh_auto_build -- build

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

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

    override_dh_auto_clean:
            $(MAKE) packageclean

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

    override_dh_auto_test:

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

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

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

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

[28] Смотрите руководство по политике Debian, раздел 2.4 «Разделы» и список разделов в `sid`.

[29] Смотрите руководство по политике Debian, раздел 2.5 «Приоритеты».

[30] Смотрите руководство по политике Debian, раздел 7.7 «Связи между пакетами с исходным кодом и двоичными пакетами — Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep».

[31] Эта несколько странная ситуация является хорошо документированной возможностью, описанной в руководстве по политике Debian, сноска 55. Причина не в использовании команды dh в файле `debian/rules`, а в специфике работы dpkg-buildpackage. Аналогичный случай встречается в системе автоматической сборки Ubuntu.

[32] Подробней об этом смотрите в руководстве по политике Debian, раздел 5.6.8 «Architecture».

[33] Смотрите руководство по политике Debian, главу 7 «Объявление связей между пакетами».

[34] Эти описания составляются на английском языке. Переводы описаний выполняются через проект переводов описаний Debian — DDTP.

[35] Смотрите справочник разработчика Debian, раздел 6.2.5. «Местонахождение системы контроля версий».

[36] Если для выполнения изменения вы используете команду `dch -r`, то убедитесь, что записали файл `changelog` именно редактором.

[37] You can start learning how to write a `Makefile` from Debian Reference, 12.2. "Make". The full documentation is available as http://www.gnu.org/software/make/manual/html_node/index.html or as the `make-doc` package in the `non-free` archive area.

[38] В руководстве по политике Debian, раздел 4.9 «Главный сценарий сборки: debian/rules» этот файл описан подробно.

[39] Эта цель используется `dpkg-buildpackage` как описано в Раздел 6.1, «Полная (пере)сборка».

[40] Эта цель используется `dpkg-buildpackage -B`, как описано в Раздел 6.2, «Autobuilder».

[41] Эта цель используется `dpkg-buildpackage -A`.

[42] This uses the new `debhelper` v7+ features. Its design concepts are explained in Not Your Grandpa's Debhelper presented at DebConf9 by the `debhelper` upstream. Under `lenny`, dh_make created a much more complicated `rules` file with explicit rules and many dh_* scripts listed for each one, most of which are now unnecessary (and show the package's age). The new dh command is simpler and frees us from doing the routine work "manually". You still have full power to customize the process with `override_dh_*` targets. See Раздел 4.4.3, «Доработка файла `rules`». It is based only on the `debhelper` package and does not obfuscate the package building process as the `cdbs` package tends to do.

[43] You can verify the actual sequences of dh_* programs invoked for a given ``target`` without really running them by invoking `dh `target` --no-act` or `debian/rules -- '`target` --no-act'`.

[44] В следующем примере предполагается, что ваш `debian/compat` содержит значение, равное 9 или более, что позволяет избежать автоматического вызова команд поддержки python.

[45] Всю информацию о том, что делают сценарии dh_* и какие они имеют параметры, можно найти в их справочных страницах и документации к `debhelper`.

[46] These commands support other build environments, such as `setup.py`, which can be listed by executing `dh_auto_build --list` in a package source directory.

[47] В действительности, в `Makefile` ищется и выполняется первая из доступных целей: `distclean`, `realclean` или `clean`.

[48] В действительности, в `Makefile` ищется и выполняется первая из доступных целей: `test` или `check`.

[49] Если с пакетом устанавливается файл `/usr/share/perl5/Debian/Debhelper/Sequence/`своё_имя`.pm`, то вам нужно активировать его функцию доработки командой `dh $@ --with `своё_имя``.

[50] Команда dh_python2 предпочтительнее, чем dh_pysupport или dh_pycentral. Не используйте команду dh_python.

[51] В `lenny`, если вы хотите изменить поведение сценария dh_*, нужно найти соответствующую строку в файле `rules` правил и изменить её.

[52] Программа dh_auto_build без аргументов выполняет правила первой цели в `Makefile`:

[53] Файлы `debian/changelog` и `debian/NEWS` всегда устанавливаются автоматически. Файл журнала ищется сопоставлением имён файлов, приведённых к нижнему регистру и совпадением их с именами `changelog`, `changes`, `changelog.txt` и `changes.txt`.

Глава 3. Изменение исходного кода |  | Глава 5. Другие файлы в каталоге `debian/`