Содержание
README.Debian
compat
conffiles
пакет
.cron.*
dirs
пакет
.doc-base
docs
emacsen-*
пакет
.examples
пакет
.init
и
пакет
.default
install
пакет
.info
пакет
.links
{пакет
.,source/}lintian-overrides
manpage.*
пакет
.manpages
NEWS
{pre|post}{inst|rm}
пакет
.symbols
TODO
watch
source/format
source/local-options
source/options
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. В таких случаях вам необходимо создать их с
помощью текстового редактора.
Если вы хотите активировать некоторые из них, выполните следующие действия:
переименуйте файлы настройки, используя имя реального двоичного пакета;
измените содержимое файла шаблона согласно вашим нуждам;
удалите файлы шаблонов, в которых нет необходимости;
при необходимости, измените файл control
(смотрите
Раздел 4.1, «Файл control
»);
при необходимости, измените файл rules
(смотрите Раздел 4.4, «Файл rules
»);
Любые файлы настройки 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/
;
выполняется в любое другое время.
пакет
Большинство этих файлов являются сценариями оболочки, за исключением
, который должен
иметь формат crontab(5).
пакет
.cron.d
Для архивирования журнальных файлов никаких файлов
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
file
will be installed as
package
.default/etc/default/
. This
file sets defaults that are sourced by the init script. This
package
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.
package
.default
Если с оригинальной программой поставляется сценарий инициализации, то вы
можете использовать и его. Если он вам не подходит, то создайте свой в файле
с именем
. Однако,
если оригинальный сценарий инициализации хорошо написан и устанавливается в
правильное место, вам всё ещё нужно установить символьные ссылки в
пакет
.initrc*
. Для этого замените
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
or
package
.lintian-overridessource/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
в качестве первого суффикса, который
означает, что эта справочная страница описывает пользовательскую
команду. Убедитесь, что используется правильный раздел. Вот короткий список
разделов справочных страниц:
Раздел | Описание | Примечания |
---|---|---|
1 | Пользовательские команды | Запускаемые команды или сценарии |
2 | Системные вызовы | Функции, предоставляемые ядром |
3 | Библиотечные вызовы | Функции, предоставляемые системными библиотеками |
4 | Специальные файлы | Обычно находятся в каталоге /dev |
5 | Форматы файлов | Например, формат /etc/passwd |
6 | Игры | Игры и другие несерьёзные программы |
7 | Пакеты макросов | Например, макросы man |
8 | Системное администрирование | Программы, обычно запускаемые только суперпользователем |
9 | Функции ядра | Нестандартные вызовы и внутреннее устройство |
Таким образом, справочная страница для 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
:
override_dh_auto_build: docbook-to-man debian/gentoo.sgml > debian/gentoo.1 dh_auto_build
Если вы предпочитаете использовать 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
:
override_dh_auto_build: xsltproc --nonet \ --param make.year.ranges 1 \ --param make.single.year.ranges 1 \ --param man.charmap.use.subset 0 \ -o debian/ \ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\ debian/gentoo.1.xml dh_auto_build
Если ваш пакет содержит справочные страницы, то их следует устанавливать с
помощью dh_installman(1), перечислив в файле
.
пакет
.manpages
Чтобы установить справочную страницу doc/gentoo.1
для
пакета gentoo
, создайте следующий
файл gentoo.manpages
:
docs/gentoo.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/
files. See Раздел A.2, «Управление
package
.symbolsdebian/
».
пакет
.symbols
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/
.
This solves issues related to periodically changing SourceForge URLs.
project
/tar-name
-(.+)\.tar\.gz
Если автор программы подписывает 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
.patch3.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
.
[54] Смотрите dpkg(1) и руководство по политике Debian, раздел «D.2.5 Conffiles».
[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] Если вы просите поручителя загрузить ваш пакет, такое чёткое разделение и документирование ваших изменений очень важно для ускорения проверки пакета поручителем.