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

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 . В таких случаях вам необходимо создать их с помощью текстового редактора.

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

переименуйте файлы настройки, используя имя реального двоичного пакета;

измените содержимое файла шаблона согласно вашим нуждам;

удалите файлы шаблонов, в которых нет необходимости;

при необходимости, измените файл control (смотрите Раздел 4.1, «Файл control »);

при необходимости, измените файл rules (смотрите Раздел 4.4, «Файл rules »);

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

5.1. Файл README.Debian

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

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

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

5.2. Файл compat

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

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.

5.3. Файл conffiles

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

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

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

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

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

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

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

5.4. Файлы пакет .cron.*

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

пакет .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) ).

5.5. Файл dirs

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

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

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

5.6. Файл пакет .doc-base

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

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

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

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

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

5.7. Файл docs

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

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

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

5.8. Файлы emacsen-*

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

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

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

5.9. Файл пакет .examples

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

5.10. Файлы пакет .init и пакет .default

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

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 на следующие строки:

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

5.11. Файл install

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 будет выглядеть так:

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

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

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

5.12. Файл пакет .info

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

5.13. Файл пакет .links

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

5.14. Файлы lintian-overrides

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

5.15. Файлы manpage.*

Для каждой программы должна быть справочная страница. Если её нет, её необходимо создать. Команда 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] .

Если вы предпочитаете использовать SGML вместо nroff , то можете использовать шаблон manpage.sgml.ex . Для этого необходимо:

переименовать файл в gentoo.sgml ;

установить пакет docbook-to-man ;

в файл control добавить docbook-to-man в строку Build-Depends ;

добавить цель override_dh_auto_build в файл rules :

Если вы предпочитаете использовать XML вместо SGML, то можете использовать шаблон manpage.xml.ex . Для этого необходимо:

переименовать исходный файл в gentoo.1.xml ;

установить пакет docbook-xsl и обработчик XSLT (рекомендуется xsltproc );

в файл control добавить пакеты docbook-xsl , docbook-xml и xsltproc в строку Build-Depends ;

добавить цель override_dh_auto_build в файл rules :

5.16. Файл пакет .manpages

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

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

5.17. Файл NEWS

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

5.18. Файлы

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

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

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

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

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

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

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

5.19. Файл пакет .symbols

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