Глава 5. Другие файлы в каталоге debian/

Содержание

5.1. Файл README.Debian
5.2. Файл compat
5.3. Файл conffiles
5.4. Файлы пакет.cron.*
5.5. Файл dirs
5.6. Файл пакет.doc-base
5.7. Файл docs
5.8. Файлы emacsen-*
5.9. Файл пакет.examples
5.10. Файлы пакет.init и пакет.default
5.11. Файл install
5.12. Файл пакет.info
5.13. Файл пакет.links
5.14. Файлы {пакет.,source/}lintian-overrides
5.15. Файлы manpage.*
5.15.1. Файл manpage.1.ex
5.15.2. Файл manpage.sgml.ex
5.15.3. Файл manpage.xml.ex
5.16. Файл пакет.manpages
5.17. Файл NEWS
5.18. Файлы {pre|post}{inst|rm}
5.19. Файл пакет.symbols
5.20. Файл TODO
5.21. Файл watch
5.22. Файл source/format
5.23. Файл source/local-options
5.24. Файл source/options
5.25. Файлы patches/*

The dh_make command had major updates since this old document was written. So some parts of this document aren't applicable any more.

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.

The debmake command is used in place of the dh_make command in my new Guide for Debian Maintainers.

Для контроля большей части того, что делает debhelper при сборке пакетов, служат необязательные файлы настройки в каталоге debian. В этой главе будет рассмотрено, для чего нужен каждый из них и его формат. В руководстве по политике Debian и справочнике разработчика Debian приведены общие принципы пакетирования.

The dh_make command will create some template configuration files under the debian directory. Take a look at all of them.

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

Некоторые шаблоны файлов настройки debhelper не могут быть созданы командой dh_make. В таких случаях вам необходимо создать их с помощью текстового редактора.

Если вы хотите активировать некоторые из них, выполните следующие действия:

Любые файлы настройки debhelper без префикса имя пакета как, например, install, относятся к первому двоичному пакету. Если есть несколько двоичных пакетов, их файлы настройки могут быть созданы с указанием их имени в имени файла настройки, например, пакет-1.install, пакет-2.install и т.д.

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

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

gentoo for Debian
-----------------
<possible notes regarding this package - if none, delete this file>
 -- Josip Rodin <joy-mg@debian.org>, Wed, 11 Nov 1998 21:02:14 +0100

Если вам нечего сюда написать, удалите этот файл. Смотрите dh_installdocs(1).

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper v10 as follows:

$ echo 10 > debian/compat

You may use compat level v9 in certain circumstances for compatibility with older systems. However, using any level below v9 is not recommended and should be avoided for new packages.

Бывает очень обидно, когда тратишь много времени и усилий на настройку программы, а при очередном обновлении все настройки исчезают. Debian предлагает решение этой проблемы через механизм пометки файлов как настроечных — conffiles [54]. Для таких файлов при обновлении пакета вам будет задан вопрос, нужно ли заменить старые файлы теми, что включены в новый пакет.

Программа dh_installdeb(1) автоматически помечает все файлы в каталоге /etc как файлы conffiles, так что, если у вашей программы есть файлы conffiles только там, вам не обязательно указывать их в этом файле. Для большинства типов пакетов единственное место (и для них так должно быть всегда), в котором содержатся файлы conffiles, это /etc и, таким образом, в этом файле нет необходимости.

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

Если программа, которую вы упаковываете, требует от пользователя изменить файлы настройки в каталоге /etc, существует два популярных способа не отмечать их как conffiles, чтобы подавить вопросы со стороны dpkg:

  • Создать символьную ссылку в каталоге /etc, указывающую на файл в каталоге /var, генерируемый сценариями сопровождающего.

  • Сгенерировать файл в каталоге /etc с помощью сценариев сопровождающего.

Информацию о сценариях сопровождающего смотрите в Раздел 5.18, «Файлы {pre|post}{inst|rm}».

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

  • пакет.cron.hourly — устанавливается как /etc/cron.hourly/пакет; выполняется один раз в час.

  • пакет.cron.daily — устанавливается как /etc/cron.daily/пакет; выполняется один раз в день.

  • пакет.cron.weekly — устанавливается как /etc/cron.weekly/пакет; выполняется один раз в неделю.

  • пакет.cron.monthly — устанавливается как /etc/cron.monthly/пакет; выполняется один раз в месяц.

  • пакет.cron.d — устанавливается как /etc/cron.d/пакет; выполняется в любое другое время.

Большинство этих файлов являются сценариями оболочки, за исключением пакет.cron.d, который должен иметь формат crontab(5).

Для архивирования журнальных файлов никаких файлов cron.* задавать ненужно — для этого есть другие средства (смотрите dh_installlogrotate(1) и logrotate(8)).

В этом файле указываются каталоги, которые необходимы для обычной установки (make install DESTDIR=..., вызываемая dh_auto_install), но которые автоматически не создаются. Обычно, это указывает на проблему в Makefile.

Файлы, указанные в файле install, не нуждаются в предварительном создании каталогов. Смотрите Раздел 5.11, «Файл install».

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

Если ваш пакет содержит документацию, отличную от справочных страниц или файлов в формате info, то для её регистрации в системе вы должны воспользоваться файлом doc-base; это позволит пользователю найти её при помощи, например, dhelp(1), dwww(1) или doccentral(1).

Обычно, к таким файлам относятся файлы в форматах HTML, PS и PDF, помещаемые в /usr/share/doc/имя_пакета/.

Вот как выглядит файл gentoo, входящий в пакет gentoo.doc-base:

Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: File Management
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html

Формат этого файла описан в справочной странице install-docs(8), а также в локальной копии руководства Debian по doc-base из пакета doc-base.

Подробная информация по установке дополнительной документации приведена в Раздел 3.3, «Установка файлов в их каталоги назначения».

В этом файле указаны имена файлов документации, которые можно установить во временный каталог с помощью dh_installdocs(1).

По умолчанию будут включены все файлы, имеющиеся в самом верхнем каталоге с исходным кодом, а именно BUGS, README*, TODO и т.д.

Для пакета gentoo также включаются несколько других файлов:

BUGS
CONFIG-CHANGES
CREDITS
NEWS
README
README.gtkrc
TODO

В этом файле указываются файлы для Emacs, которые могут быть скомпилированы во время установки пакета.

Они устанавливаются во временный каталог при помощи dh_installemacsen(1).

Если они вам не нужны, удалите их.

Команда dh_installexamples(1) устанавливает файлы и каталоги, указанные в этом файле, как файлы примеров.

Если ваш пакет содержит службу и её необходимо запускать при старте системы, вероятнее всего, вы не обратили внимания на мой изначальный совет, не так ли? :-)

Please read dh_installinit(1) dh_installsystemd(1) to provide startup script.

The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself.

Если с оригинальной программой поставляется сценарий инициализации, то вы можете использовать и его. Если он вам не подходит, то создайте свой в файле с именем пакет.init. Однако, если оригинальный сценарий инициализации хорошо написан и устанавливается в правильное место, вам всё ещё нужно установить символьные ссылки в rc*. Для этого замените dh_installinit в файле rules на следующие строки:

override_dh_installinit:
        dh_installinit --onlyscripts

Если сценарий инициализации не требуется, удалите эти файлы.

If there are files that need to be installed into your package but your standard make install won't do it, put the filenames and destinations into this install file. They are installed by dh_install(1).[55] You should first check that there is not a more specific tool to use. For example, documents should be in the docs file and not in this one.

В файле install для каждого устанавливаемого файла отводится одна строка; в ней задаётся имя файла (относительно верхнего каталога сборки), потом пробел, потом установочный каталог (относительно каталога установки). Например, если при установке не устанавливается src/bar, то файл install будет выглядеть так:

src/bar usr/bin

В результате после установки пакета в системе появится исполняемая команда /usr/bin/bar.

Также, в файле install можно указывать только имя файла без каталога установки, если не менялся относительный путь. Такой формат, обычно, используется для большого пакета, в котором результат сборки разбивается на несколько двоичных пакетов; список устанавливаемых файлов помещается в соответствующий файл пакет-1.install, пакет-2.install и т.д.

Если команда dh_install не находит файлы в текущем каталоге, то она ищет их в debian/tmp (или в любом другом месте, указанном в --sourcedir).

Если у вашего пакета есть страницы в формате info, то их нужно устанавливать при помощи dh_installinfo(1), перечислив их в файле пакет.info.

Если вам, как сопровождающему пакета, нужно создать дополнительные символьные ссылки в каталогах сборки пакета, установите их с помощью dh_link(1), перечислив полные пути файлов источника и назначения в файле пакет.links.

If lintian reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quieten it. Please read the Lintian User's Manual (https://lintian.debian.org/manual/index.html) and refrain from abusing this.

Файл пакет.lintian-overrides предназначен для двоичного пакета и устанавливается в usr/share/lintian/overrides/пакет с помощью команды dh_lintian.

Файл source/lintian-overrides предназначен для пакета с исходным кодом. Он не устанавливается.

Для каждой программы должна быть справочная страница. Если её нет, её необходимо создать. Команда dh_make создаёт несколько шаблонов справочных страниц. Они должны быть скопированы и отредактированы для каждой команды, не имеющей собственной справочной страницы. Проверьте, что удалили неиспользованные шаблоны.

Справочные страницы, как правило, пишутся на языке разметки nroff(1). Файл шаблона manpage.1.ex также написан на nroff. Смотрите справочную страницу man(7), в которой приведено краткое описание действий по редактированию подобных файлов.

Окончательное имя файла справочной страницы должно включать имя документируемой программы, поэтому мы переименуем её с manpage на gentoo. Имя файла также включает .1 в качестве первого суффикса, который означает, что эта справочная страница описывает пользовательскую команду. Убедитесь, что используется правильный раздел. Вот короткий список разделов справочных страниц:

Таким образом, справочная страница для gentoo должна называться gentoo.1. Если в исходном коде нет справочной страницы gentoo.1, то её нужно создать путём переименовывания шаблона manpage.1.ex в gentoo.1 и затем изменить его, используя информацию из примера и документации к исходной программе.

Также, вы можете использовать команду help2man для генерации справочной страницы, которая для создания использует результат запуска команды с параметрами --help и --version [56].

Если ваш пакет содержит справочные страницы, то их следует устанавливать с помощью dh_installman(1), перечислив в файле пакет.manpages.

Чтобы установить справочную страницу doc/gentoo.1 для пакета gentoo, создайте следующий файл gentoo.manpages:

docs/gentoo.1

Этот файл устанавливается командой dh_installchangelogs(1).

Файлы postinst, preinst, postrm и prerm [57] называются сценариями сопровождающего. Эти сценарии находятся в управляющей области пакета и запускаются программой dpkg при установке, обновлении или удалении пакета.

Как начинающему сопровождающему вам следует избегать ручной правки сценариев сопровождающего, так как они имеют тенденцию усложняться. Более подробную информацию смотрите в руководстве по политике Debian, глава 6 «Сценарии сопровождающего пакета и процесс установки», и взгляните на файлы примеров, предоставляемые dh_make.

Если вы не послушали меня и сделали собственные сценарии сопровождающего для пакета, вам следует убедиться, что вы сделали всё правильно, протестировав их не только для установки и обновления, но и для удаления и вычистки.

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

Когда для обновления требуются какие-то действия (например, файлы настройки разбросаны по различным каталогам в домашнем каталоге с абсолютно разной структурой), вы можете перевести пакет в безопасное состояние (например, отключив службу) и предоставить соответствующую документацию, требуемую политикой (README.Debian и NEWS.Debian). Не беспокойте пользователя меню debconf, вызываемым из сценариев сопровождающего для обновления.

Пакет ucf предоставляет conffile-подобную инфраструктуру для сохранения пользовательских изменений в файлах, которые не могут быть помечены как conffiles, например файлы, управляемые сценариями сопровождающего. Это должно минимизировать возможные проблемы, связанные с ними.

Сценарии сопровождающего являются сильной стороной Debian, из-за них люди выбирают Debian. Вы должны быть очень осторожны, чтобы не превратить их в источник раздражения.

Packaging of a library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have debian/package.symbols files. See Раздел A.2, «Управление debian/пакет.symbols».

Этот файл устанавливается командой dh_installdocs(1).

The watch file format is documented in the uscan(1) manpage. The watch file configures the uscan program (in the devscripts package) to watch the site where you originally got the source. This is also used by the Debian Package Tracker service.

Вот его содержимое:

# управляющий файл watch для uscan
version=3
http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Обычно, с указанного в файле watch URL http://sf.net/gentoo скачивается страница и в ней ищутся ссылки вида <a href=...>. Базовое имя (часть за последним /) каждой найденной ссылки сравнивается с шаблоном регулярного выражения Perl (смотрите perlre(1)) gentoo-(.+)\.tar\.gz. Из совпавших файлов загружается файл с наибольшим номером версии и запускается программа uupdate, которая создаёт из них обновлённое дерево исходного кода.

Although this is true for other sites, the SourceForge download service at http://sf.net is an exception. When the watch file has a URL matching the Perl regexp ^http://sf\.net/, the uscan program replaces it with http://qa.debian.org/watch/sf.php/ and then applies this rule. The URL redirector service at http://qa.debian.org/ is designed to offer a stable redirect service to the desired file for any watch pattern of the form http://sf.net/project/tar-name-(.+)\.tar\.gz. This solves issues related to periodically changing SourceForge URLs.

Если автор программы подписывает tarball ключом, то рекомендуется проверять его подпись с помощью параметра pgpsigurlmangle как описано в uscan(1).

В файле debian/source/format должна содержаться единственная строка, указывающая на желаемый формат пакета с исходным кодом (полный список смотрите в dpkg-source(1)). После squeeze он должен содержать либо:

  • 3.0 (native) — для родных пакетов Debian;

  • 3.0 (quilt) — для всего остального.

В новом формате пакетов с исходным кодом 3.0 (quilt) изменения записываются в виде серии заплат quilt в каталог debian/patches. Эти изменения автоматически накладываются в ходе распаковки пакета исходного кода [58]. Изменения Debian хранятся в архиве debian.tar.gz, содержащем все файлы из каталога debian. Новый формат позволяет сопровождающему включать двоичные файлы, такие как значки в формате PNG, без дополнительных ухищрений [59].

Когда программа dpkg-source распаковывает пакет с исходным кодом в формате 3.0 (quilt), она автоматически накладывает все заплаты, перечисленные в файле debian/patches/series. Вы можете избежать наложения заплат в конце распаковки, указав параметр --skip-patches.

When you want to manage Debian packaging activities under a VCS, you typically create one branch (e.g., upstream) tracking the upstream source and another branch (e.g., typically master for Git) tracking the Debian package. For the latter, you usually want to have unpatched upstream source with your debian/* files for the Debian packaging to ease merging of the new upstream source.

После того, как вы собрали пакет, исходный код, обычно, остаётся изменённым. Вам необходимо вручную убрать изменения, внесённые заплатами, с помощью запуска dquilt pop -a перед сохранением в ветку master. Вы можете автоматизировать это, добавив дополнительный файл debian/source/local-options, содержащий unapply-patches. Этот файл не включается в генерируемый пакет с исходным кодом и изменяет только поведение локальной сборки. Также, он может содержать abort-on-upstream-changes (смотрите dpkg-source(1)).

unapply-patches
abort-on-upstream-changes

Автоматически генерируемые файлы в дереве исходного кода могут немного раздражать при пакетировании, так как из-за них генерируются бесполезные большие файлы заплат. Для решения этой проблемы есть специальные модули, такие как dh_autoreconf, описанные в Раздел 4.4.3, «Доработка файла rules».

При создании пакета с исходным кодом вы можете указать регулярное выражение Perl в параметре --extend-diff-ignore для dpkg-source(1), чтобы игнорировать изменения в автоматически генерируемых файлах.

Общим решением этой проблемы с автоматически создаваемыми файлами является сохранение аргумента dpkg-source в файле пакета с исходным кодом source/options. Благодаря следующим настройкам в файлы заплат не будут включены config.sub, config.guess и Makefile.

extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

При использовании старого формата пакета с исходным кодом 1.0 создавался один большой файл diff.gz, который содержал файлы сопровождения в debian и заплаты к исходному коду. Такой пакет немного громоздок для проверки и понимания каждого изменения дерева исходного кода. Это не так уж хорошо.

В новом формате 3.0 (quilt) заплаты хранятся в файлах debian/patches/*, для создания которых применяется команда quilt. Эти заплаты и другие данные пакета — всё содержимое каталога debian — упаковывается в файл debian.tar.gz. Так как команда dpkg-source может работать с данными quilt в формате 3.0 (quilt) без пакета quilt, то его не нужно включать в зависимости Build-Depends [60].

Работа с командой quilt описана в quilt(1). Она записывает изменения исходного кода в виде набора заплат -p1 в каталоге debian/patches, а дерево исходного кода вне каталога debian остаётся нетронутым. Порядок применения этих заплат указывается в файле debian/patches/series. Вы можете легко наложить (=push), откатить (=pop) или обновить заплаты [61].

В Глава 3, Изменение исходного кода мы создали 3 заплаты в debian/patches.

Поскольку заплаты Debian расположены в debian/patches, убедитесь, что программа dquilt настроена правильно, как было описано в Раздел 3.1, «Настройка quilt».

Позднее, когда кто-то (включая вас самих) предоставляет заплату foo.patch к исходному коду, изменить пакет исходного кода 3.0 (quilt) очень просто:

$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../foo.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
... описание заплаты

Заплаты, хранимые в новом формате исходного кода 3.0 (quilt), должны быть без ненужного мусора. Вы должны убедиться в этом, запустив: dquilt pop -a; while dquilt push; do dquilt refresh; done.



[55] Этот файл заменяет устаревшую команду dh_movefiles(1), которая настраивается с помощью файла files.

[56] Заметим, что в шаблоне справочной страницы из help2man утверждается, что более подробная документация приведена в справочной системе info. Если для команды нет страницы info, то вам нужно изменить справочную страницу, созданную командой help2man.

[57] Несмотря на то, что здесь используется сокращённое выражение bash для обозначения этих файлов в виде {pre|post}{inst|rm}, в сценариях сопровождающего рекомендуется использовать только синтаксис POSIX для лучшей совместимости с системной оболочкой dash.

[58] Обзор перехода на новые форматы пакетов 3.0 (quilt) и 3.0 (native) с исходным кодом смотрите в DebSrc3.0.

[59] Фактически, новый формат также позволяет использовать несколько tar-архивов исходной программы и дополнительные методы сжатия. Описание этого выходит за рамки данного документа.

[60] Для управления набором заплат в пакетировании Debian были предложены и применяется несколько методов. Система quilt — предпочтительная система сопровождения. Также есть dpatch, dbs, cdbs и другие. Многие из них хранят заплаты в файлах debian/patches/*.

[61] Если вы просите поручителя загрузить ваш пакет, такое чёткое разделение и документирование ваших изменений очень важно для ускорения проверки пакета поручителем.