Содержание
debian/rules
debian/control
debian/changelog
debconf
.orig.tar.{gz,bz2,xz}
Debian's quality is largely due to the Debian Policy, which defines explicit baseline requirements that all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very talented people have created great tools, tools which help you, the Debian maintainer, create and maintain excellent packages.
Эта глава содержит описание некоторых лучших практик для разработчиков Debian. Все рекомендации являются только рекомендациями, а не требованиями или правилами. Они представляют собой лишь субъективные подсказки, советы и указания, позаимствованные у других разработчиков Debian. Выбирайте то, что лучше всего подходит именно вам.
The following recommendations apply to the debian/rules
file. Since debian/rules
controls the build process
and selects the files that go into the package (directly or indirectly),
it's usually the file maintainers spend the most time on.
Основная причина использования сценариев-помощников в файле
debian/rules
заключается в том, что последние позволяют
сопровождающим распространять общую логику на множество пакетов и
использовать её. Рассмотрим для примера вопрос установки пунктов меню: вам
необходимо поместить файл в /usr/share/menu
(или, если
это требуется, /usr/lib/menu
для выполняемых двоичных
файлов меню), а также добавить команды сценариям сопровождающего для
регистрации и отмены регистрации этих пунктов меню. Поскольку это довольно
частая задача, зачем каждому сопровождающему переписывать всё это
самостоятельно, а иногда и с ошибками? Кроме того, допустим, что каталог
меню изменился, в этом случае пришлось бы изменить каждый пакет.
Сценарии-помощники могут позаботиться об этих проблемах. Допустим, вы соблюдаете конвенции, ожидаемые сценарием-помощником, а последний заботится обо всех деталях. Если политика изменится, то это изменение может быть отражено в сценарии-помощнике; тогда пакеты нужно будет лишь собрать заново с новой версией помощника без каких-либо изменений вручную.
Раздел A, «Обзор инструментов Debian для сопровождающего»
содержит описание различных помощников. Наиболее часто используемой и
лучшей (по нашему мнению) системой-помощником является debhelper
. Предшествующие системы-помощники,
такие как debmake
, были монолитны:
вы не могли выбрать только ту часть помощника, которая кажется вам полезной,
вам приходилось использовать этот помощник для всего сразу. Тем не менее,
debhelper
представляет собой ряд
отдельных небольших программ dh_*. Например,
dh_installman устанавливает и сжимает страницы
руководства, dh_installmenu устанавливает файлы меню и
так далее. Таким образом, этот помощник предлагает достаточный уровень
гибкости, позволяющий использовать небольшие сценарии-помощники там, где это
подходит, а также команды, добавленные в файл
debian/rules
вручную.
Вы можете начать своё знакомство с debhelper
с чтения debhelper(1) и изучения примеров, которые поставляются вместе с
содержащим этот помощник пакетом. dh_make из пакета
dh-make
(см. раздел A.3.2, «dh-make
»), может использоваться для
перевода ванильного пакета с исходным кодом в debhelper
ианизированый пакет. Этот короткий
путь не должен, однако, создать у вас впечатление, что вам не нужно
беспокоиться о понимании каждого отдельного помощника
dh_*. Если вы собираетесь использовать помощник, вам
следует потратить время на изучение того, как этот помощник используется, и
изучить его ожидания и поведение.
Большие, сложные пакеты могут содержать множество ошибок, с которыми вам
предстоит иметь дело. Если вы исправляете несколько ошибок напрямую в
исходном коде, и при этом вы недостаточно внимательны, дифференцировать
различные заплаты, которые вы применили, может стать довольно трудной
задачей. Пакет может превратиться в бардак, когда вам придётся обновить его
для новой версии из основной ветки разработки, содержащей некоторые (но не
все) применённые вами исправления. Вы не можете просто взять полный набор
diff'ов (напр., из .diff.gz
) и определить то, какой
набор заплат представляет собой тот единый компонент кода, содержащий
исправление ошибок для основной ветки разработки.
Fortunately, with the source format “3.0 (quilt)” it is now possible to keep
patches separate without having to modify debian/rules
to set up a patch system. Patches are stored in
debian/patches/
and when the source package is unpacked
patches listed in debian/patches/series
are
automatically applied. As the name implies, patches can be managed with
quilt.
При использовании более старого формата пакетов с исходным кодом “1.0” также
можно выделить заплаты, но тогда необходимо использовать выделенную систему
заплат: файлы заплат поставляются в файле заплат Debian
(.diff.gz
), который обычно располагается в каталоге
debian/
. Единственное отличие состоит в том, что в
таком случае заплаты не применяются непосредственно командой
dpkg-source, но правилом build
файла
debian/rules
, через зависимость от правила
patch
. И наоборот, они отменяются в правиле
clean
, через зависимость от правила
unpatch
.
quilt is the recommended tool for this. It does all of
the above, and also allows one to manage patch series. See the quilt
package for more information.
Для обработки заплат существуют и другие инструменты, такие как
dpatch, и система заплат, интегрированная в cdbs
.
A single source package will often build several binary packages, either to
provide several flavors of the same software (e.g., the vim
source package) or to make several small
packages instead of a big one (e.g., so the user can install only the subset
needed, and thus save some disk space, see for example the lyx
source package).
Со вторым случае можно легко управиться при помощи настроек в файле
debian/rules
. Вам нужно лишь переместить
соответствующие файлы из каталога сборки во временные деревья пакета. Вы
можете сделать это при помощи команд install или
dh_install из пакета debhelper
. Не забудьте проверить разные
изменения различных пакетов на предмет того, что вы правильно установили
межпакетные зависимости в файле debian/control
.
The first case is a bit more difficult since it involves multiple recompiles
of the same software but with different configuration options. The
vim
source package is an example of
how to manage this using a hand-crafted debian/rules
file.
Следующие практики относятся к файлу debian/control
.
Они дополняют Политику описаний
пакетов.
Описание пакета, как оно определено в соответствующем поле файла
control
, содержит резюме пакета и длинное описание
этого пакета. раздел 6.2.1, «Общие принципы описания пакетов» описывает общие принципы обеих этих частей описания
пакета. Далее, раздел 6.2.2, «Резюме пакета или короткое описание» содержит принципы, относящиеся к резюме, а раздел 6.2.3, «Длинное описание»
представляет собой принципы, относящиеся к описанию.
Описание пакета должно быть написано для среднего пользователя, среднего человека, который будет использовать и извлекать пользу из данного пакета. Например, пакеты для разработки предназначены для разработчиков, и могут быть описаны техническим языком. Описания приложений общего назначения, таких как текстовые редакторы, должны быть написаны для менее подкованного в техническом плане пользователя.
Наш обзор описаний пакетов привёл нас к заключению, что большая часть описаний пакетов являются техническими, то есть они не написаны так, чтобы быть понятными технически не подкованным пользователям. Если ваш пакет предназначен не только для технических пользователей, это является проблемой.
Как следует писать описания для технически не подкованных пользователей? Избегайте жаргона. Избегайте указания на другие приложения или наборы приложений, которые могут быть незнакомы пользователю — GNOME или KDE это нормально, так как пользователи вероятно знакомы с этими терминами, но термин GTK+ скорее всего им не знаком. Попытайтесь вообще не допускать какого-либо знания. Если вам нужно использовать технические термины, определите их.
Будьте объективны. Описания пакетов — это не то место, где следует пропагандировать свой пакет, не важно, насколько вы его любите. Помните, что читатель может и не заботиться о тех же вещах, что и вы.
Указания на названия любых других пакетов ПО, названия протоколов, стандартов или спецификаций должны иметь каноническую форму, если таковая существует. Например, используйте X Window System, X11 или X; но не X Windows, X-Windows или X Window. Используйте GTK+, а не GTK или gtk. Используйте GNOME, а не Gnome. Используйте PostScript, а не Postscript или postscript.
Если у вас возникли проблемы с написанием описания, вы можете отправить его
по адресу <debian-l10n-english@lists.debian.org>
с запросом помощи.
Политика говорит, что строка резюме (короткое описание) должна быть точной, не должна повторять имя пакета, но также должна быть информативной.
Резюме представляет собой фразу, описывающую пакет, а не полное предложение, поэтому пунктуация, характерная для предложений, тут неуместна: дополнительные заглавные буквы или точка в конце (как знак полной остановки) не нужны. Также следует пропустить любой начальный неопределённый или определённый артикль — "a", "an" или "the". Таким образом, например:
Package: libeg0 Description: exemplification support library
Технически это именная фраза без артиклей в противоположность глагольной
фразе. Хорошая эвристика состоит в том, что должно быть возможно подставить
имя
пакета вместо его
резюме
в следующую формулу:
Пакет имя пакета
предоставляет {a,an,the,some}
резюме пакета
.
Наборы связанных пакетов могут использовать альтернативную схему, которая разделяет резюме на две части, на, во-первых, описание всего набора и, во-вторых, резюме роли конкретного пакета в этом наборе:
Package: eg-tools Description: simple exemplification system (utilities) Package: eg-doc Description: simple exemplification system - documentation
Эти резюме следуют изменённой формуле. В ней пакет "имя
пакета
" имеет резюме "набор пакетов
(роль
)" или "набор
пакетов
- роль
", элементы резюме
должны быть сформулированы так, чтобы они подходили под следующую формулу:
Пакет имя пакета
предоставляет {a,an,the}
роль
для набора
пакетов
.
Длинное описание является первичной информацией, доступной пользователю о пакете до того, как он его установит. Оно должно предоставлять всю информацию, которая необходима для того, чтобы пользователь мог решить устанавливать ему этот пакет или нет. Допускайте, что пользователь уже прочитал резюме пакета.
Длинное описание должно состоять из полных и законченных предложений.
Первый абзац длинного описания должен содержать ответ на следующие вопросы: кто делает этот пакет? какие задачи он помогает решить пользователю? Важно описать это без использования технических терминов, если, конечно, аудиторией данного пакета не являются с необходимостью технически подкованные пользователи.
The following paragraphs should answer the following questions: Why do I as a user need this package? What other features does the package have? What outstanding features and deficiencies are there compared to other packages (e.g., if you need X, use Y instead)? Is this package related to other packages in some way that is not handled by the package manager (e.g., is this the client for the foo server)?
Будьте внимательны, избегайте орфографических и грамматических ошибок.
Проверьте описание на ошибки. И ispell, и
aspell имеют специальные режимы для проверки файлов
debian/control
:
ispell -d american -g debian/control
aspell -d en -D -c debian/control
Обычно пользователи ожидают найти в описании пакета ответы на следующие вопросы:
Что этот пакет делает? Если он является дополнением для другого пакета, то в описании следует поместить краткое описание того пакета, дополнением которого является данный пакет.
Почему я хочу получить этот пакет? Ответ на этот вопрос связан с ответом на предыдущий вопрос, но это разные вопросы (это клиент электронной почты; он классный, быстрый, работает с PGP и LDAP, а также с IMAP, он имеет X, Y и Z).
Если этот пакет не должен быть установлен напрямую, но тянется за другим пакетом, это обстоятельство должно быть явно указано.
Если пакет является экспериментальным
, либо имеются
другие причины, по которым этот пакет не следуем использовать, если имеются
другие пакеты, которые следует использовать вместо данного, это также должно
быть отдельно указано.
How is this package different from the competition? Is it a better implementation? more features? different features? Why should I choose this package?
Мы рекомендуем вам добавить ссылку на домашнюю страницу пакета в поле
Homepage
раздела Source
в файле
debian/control
. Добавление этой информации в само
описание пакета считается устаревшей нормой.
В файле debian/control
имеются дополнительные поля для
указания размещения системы контроля версий.
Значением этого поля должна быть ссылка вида https://
,
указывающая на копию репозитория системы управления версиями, используемой
для сопровождения данного пакета, которую можно просмотреть в веб-браузере,
если таковая имеется.
Подразумевается, что данная информация будет полезна для конечного
пользователя, который захочет ознакомиться с последней работой, связанной с
этим пакетом (напр., захочет найти заплату для исправления ошибки,
обозначенной с системе отслеживания ошибок тегом
pending
).
Value of this field should be a string identifying unequivocally the
location of the Version Control System repository used to maintain the given
package, if available. *
identifies the Version Control
System; currently the following systems are supported by the package
tracking system: arch
, bzr
(Bazaar),
cvs
, darcs
, git
,
hg
(Mercurial), mtn
(Monotone),
svn
(Subversion). It is allowed to specify different VCS
fields for the same package: they will all be shown in the PTS web
interface.
Подразумевается, что эта информация будет полезна пользователю, которых осведомлён о принципах работы данной системы управления версиями и желает собрать текущую версию пакета из исходного кода, размещённого там. Другие способы использования этой информации могут включать автоматическую сборку последней версии данного пакета из системы управления версиями. Для этого размещение, указанное в данном поле, не должно иметь привязку к версии и должно указывать на основную ветку (это касается систем управления версиями, поддерживающих эту возможность). Кроме того, указываемое размещение должно быть доступно конечному пользователю; для выполнения этого требования может потребоваться указание на анонимный доступ к репозиторию вместо указания версии, доступной через SSH.
В следующем примере демонстрируется пакет vim
в соответствующем поле которого указан
репозиторий Subversion. Заметьте, что URL приведён по схеме
svn://
(а не по схеме svn+ssh://
), а
также то, что указана ветвь trunk/
. Также
демонстрируется использование полей Vcs-Browser
и
Homepage
, описанных выше.
Source: vim Section: editors Priority: optional <snip> Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim Vcs-Browser: https://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim Homepage: http://www.vim.org
Следующие практики дополняют Политику о файлах изменений.
Записи в файле изменений ревизии пакета описывают изменения данной ревизии и только их. Сосредоточьтесь на описании существенных и заметных для пользователя изменений, которые были произведены с момента выпуска последней версии.
Обратите внимание на то, что было изменено — кто, как и когда обычно менее важно. Указав это, не забудьте вежливо указать людей, которые оказали заметную помощь в создании пакета (напр., тех, что выслал заплаты).
Нет необходимости указывать тривиальные и очевидные изменения. Также вы
можете объединять несколько изменений в одну запись. С другой стороны, не
будьте чересчур кратки, если внесли крупное изменение. Будьте особенно
ясны, если были произведены изменения, которые оказывают влияние на
поведение программы. Для указания дальнейших объяснений используйте файл
README.Debian
.
Используйте общепринятый вариант английского языка, чтобы большинство читателей смогли вас понять. Избегайте аббревиатур, технического языка и жаргона, когда вы описываете изменения, закрывающие ошибки, особенно это касается ошибок, о которых сообщили пользователи, и которые не кажутся вам в каком-то особом смысле технически сложными. Будьте вежливы, не ругайтесь.
Иногда желательно указать в начале записи об изменениях имена файлов, которые были изменены. Тем не менее, нет необходимости явно указывать каждый изменённый файл, особенно если изменения были небольшими или повторяющимися. Используйте шаблоны с метасимволами.
Если вы ссылаетесь на ошибки, не предполагайте у пользователей какого-либо знания. Сообщите, в чём заключалась проблема, как она была исправлена, и добавьте строку closes: #nnnnn. Дополнительную информацию см. в разделе 5.8.4, «Когда ошибки исправляются путём новых загрузок».
The release team have indicated that they expect most uploads to
unstable
to use urgency=medium. That is, you should choose
urgency=medium unless there is some
particular reason for the upload to migrate to testing
more quickly or slowly (see Раздел 5.14.2, «Обновления из нестабильного выпуска»). For
example, you might select urgency=low if
the changes since the last upload are large and might be disruptive in
unanticipated ways.
Записи об изменениях не должны описывать общие проблемы при создании пакета (Эй, если вы ищете foo.conf, он находится в /etc/бла-бла-бла/.), поскольку предполагается, что администраторы и пользователи по меньшей мере отдалённо знакомы с тем, как такие вещи обычно улаживаются в системах Debian. Сообщите, тем не менее, о том, что вы изменили расположение файла настройки, если вы произвели такое изменение.
Единственными закрываемыми с помощью записей об изменениях ошибками должны быть те, которые фактически исправляются именно в этой ревизии пакета. Закрытие несвязанных ошибок в журнале изменений является плохой практикой. См. раздел 5.8.4, «Когда ошибки исправляются путём новых загрузок».
Записи об изменениях не должны использоваться для случайных дискуссий с теми, кто сообщил об ошибках (Я не наблюдаю ошибки сегментирования, когда запускаю foo с опцией bar; вышлите дополнительную информацию), общих утверждений о жизни, Вселенной и вообще (извините, загрузка этой версии заняла так много времени, но у меня была простуда), или просьб о помощи (список ошибок этого пакета очень велик, пожалуйста, помогите мне с этим). Скорее всего всё это не будет замечено целевой аудиторией, но может надоедать тем людям, которые хотят читать информацию о фактических изменениях в пакете. Подробную информацию о том, как использовать систему отслеживания ошибок см. в разделе 5.8.2, «Ответ на ошибки».
Традиционно ошибки, исправленные в загрузках, которые произведены не сопровождающими, упоминаются в первой записи об изменениях той загрузки, которая произведена собственно сопровождающим. Поскольку сейчас у нас имеется система отслеживания версий, достаточно сохранить записи об изменениях, сделанных несопровождающими, и просто упомянуть этот факт в вашей записи об изменениях.
Следующие примеры демонстрируют некоторых общие ошибки или примеры плохого стиля в записях об изменениях.
* Fixed all outstanding bugs.
Очевидно, эта запись не сообщает читателям ничего полезного.
* Applied patch from Jane Random.
Что это была за заплата?
* Late night install target overhaul.
Что это была за переделка? Упоминание поздней ночи предполагается как сообщение о том, что этому коду не следует доверять?
* Fix vsync fw glitch w/ ancient CRTs.
Too many acronyms (what does "fw" mean, "firmware"?), and it's not overly clear what the glitch was actually about, or how it was fixed.
* This is not a bug, closes: #nnnnnn.
Во-первых, вовсе не нужно загружать пакет, чтобы сообщить эту информацию; вместо этого используйте систему отслеживания ошибок. Во-вторых, отсутствует объяснение того, почему данный отчет об ошибке ошибкой не является.
* Has been fixed for ages, but I forgot to close; closes: #54321.
If for some reason you didn't mention the bug number in a previous changelog entry, there's no problem, just close the bug normally in the BTS. There's no need to touch the changelog file, presuming the description of the fix is already in (this applies to the fixes by the upstream authors/maintainers as well; you don't have to track bugs that they fixed ages ago in your changelog).
* Closes: #12345, #12346, #15432
Где описание? Если вы не можете придумать описание, начните со вставки заголовка каждой отдельной ошибки.
Важные новости об изменениях в пакете можно также поместить в файл
NEWS.Debian
. Новости будут отображены такими
инструментами как apt-listchanges
до
всех остальных журналов изменений. Это является предпочтительным способом
сообщения пользователям о существенных изменениях в пакете. Это лучше, чем
использование примечаний debconf
,
поскольку этот способ менее надоедлив и пользователь может вернуться и
просмотреть файл NEWS.Debian
после установки. И это
лучше, чем указание крупных изменений в файле
README.Debian
, поскольку пользователь легко может не
заметить вашего сообщения.
Формат этот файла такой же как и формат файла журнала изменений, но забудьте
о звёздочках и описывайте каждую новость в отдельном полном параграфе, если
это необходимо, вместо того, чтобы давать более краткие резюме, которые
подходят для журнала изменений. Хорошо бы пропустить ваш файл через
dpkg-parsechangelog
для проверки форматирования,
поскольку в отличии от журнала изменений он не будет проверен автоматически
во время сборки. Ниже приведён пример настоящего файла
NEWS.Debian
:
cron (3.0pl1-74) unstable; urgency=low The checksecurity script is no longer included with the cron package: it now has its own package, checksecurity. If you liked the functionality provided with that script, please install the new package. -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
Файл NEWS.Debian
устанавливается как
/usr/share/doc/
.
Он сжимается, и он всегда имеет данное имя даже в родных пакетах Debian.
Если вы используете пакет
/NEWS.Debian.gzdebhelper
,
dh_installchangelogs
установит файлы
debian/NEWS
за вас.
В отличии от файлов журналов вам не нужно обновлять файлы
NEWS.Debian
в каждом выпуске. Обновляйте их только
если имеется что-то действительно заслуживающее упоминания, что должно быть
известно пользователю. Если у вас нет никаких новостей, не нужно добавлять
файл NEWS.Debian
в ваш пакет. Отсутствие новостей
— уже хорошие новости!
Maintainer scripts include the files debian/postinst
,
debian/preinst
, debian/prerm
and
debian/postrm
. These scripts take care of any package
installation or deinstallation setup that isn't handled merely by the
creation or removal of files and directories. The following instructions
supplement the Debian Policy.
Сценарии сопровождающего должны быть идемпотентны. Это означает, что вам следует убедиться, что не произойдёт ничего плохого в том случае, когда сценарий будет вызван дважды, хотя обычно он вызывается только один раз.
Стандартные ввод и вывод могут быть перенаправлены (напр., конвейерами) с целью записи журнала для отладки, поэтому вам не следует считать, что они представляют собой лишь tty.
Все подсказки и интерактивные настройки должны быть сведены к минимуму.
Когда это необходимо, для предоставления интерфейса следует использовать
пакет debconf
. Помните, что
подсказки в любом случае могут быть выведены лишь на этапе
настройки
сценария postinst
.
Делайте сценарии сопровождающего насколько простыми, насколько это
возможно. Мы предлагаем использовать чистые сценарии оболочки POSIX.
Помните, если вам нужны какие-либо возможности bash, сценарий
сопровождающего должен содержать строку, объявляющую использование bash.
Оболочка POSIX или Bash предпочтительны по отношению к Perl, поскольку они
позволяют debhelper
легко добавлять
что-то новое в эти сценарии.
Если вы изменяете ваши сценарии сопровождающего, проверьте удаление пакета, двойную установку и очистку. Убедитесь, что очищенный пакет убран полностью, то есть, очистка должна удалить любые напрямую или косвенно созданные любым сценарием сопровождающего файлы.
Если вам необходимо проверить существование команды, используйте что-то вроде этого:
if which install-docs > /dev/null; then ...
Вы можете использовать эту функцию для поиска $PATH
для
имения команды, переданной в качестве аргумента. Она возвращает истинное
значение (ноль), если команда была найдена, и ложь, если нет. В
действительности, это наиболее переносимый способ, поскольку
command -v
, type и
which не совместимы с POSIX.
Хотя which является допустимой альтернативой, так как она
поставляется в требуемом пакете debianutils
, она находится не на корневом
разделе. То есть, она располагается в /usr/bin
, а не в
/bin
, поэтому её нельзя использовать в сценариях,
которые запускаются до монтирования раздела /usr
.
Хотя, большинство сценариев не имеют такой проблемы.
Debconf
is a configuration
management system that can be used by all the various packaging scripts
(postinst
mainly) to request feedback from the user
concerning how to configure the package. Direct user interactions must now
be avoided in favor of debconf
interaction. This will enable non-interactive installations in the future.
Debconf является превосходным инструментом, но часто он плохо используется. Многие общие ошибки приведены на странице руководства debconf-devel(7). Вам следует прочитать это руководство, если вы решили использовать debconf. Кроме этого, здесь мы приводим ниже лучшие практики использования этого инструмента.
Эти принципы включают некоторые рекомендации по типографии и стилю письма, общие соображения об использовании debconf, а также более конкретные рекомендации для некоторых частей дистрибутива (например, системы установки).
Поскольку debconf возник в Debian, им часто злоупотребляют, и дистрибутив Debian получил изрядную долю критики за злоупотребление debconf необходимостью отвечать на большое количество вопросов для установки даже очень небольшого пакета.
Keep usage notes to what they belong: the NEWS.Debian
,
or README.Debian
file. Only use notes for important
notes that may directly affect the package usability. Remember that notes
will always block the install until confirmed or bother the user by email.
Carefully choose the questions' priorities in maintainer scripts. See debconf-devel(7) for details about priorities. Most questions should use medium and low priorities.
Большинство сопровождающих Debian не являются носителями английского языка. Поэтому написание правильно сформулированных шаблонов может быть для них нелегким делом.
Используйте список рассылки <debian-l10n-english@lists.debian.org>
(и злоупотребляйте
им). Пусть ваши шаблоны будут вычитаны.
Плохо написанные шаблоны создают плохое представление о вашем пакете, вашей работе... и даже самом Debian.
Избегайте технического жаргона насколько это возможно. Если некоторые термины звучат знакомо для вам, они всё равно могут быть непонятны остальным. Если вы не можете избежать этих терминов, попытайтесь объяснить их (используйте подробное описание). Если вы пишете описание, пытайтесь балансировать на грани подробности и простоты.
Debconf templates may be translated. Debconf, along with its sister package po-debconf, offers a simple framework for getting templates translated by translation teams or even individuals.
Используйте шаблоны на основе gettext. Установите po-debconf
в вашу систему, используемую для
разработки, и прочтите документацию этого пакета (man
po-debconf является хорошим началом).
Avoid changing templates too often. Changing template text induces more
work for translators, which will get their translation fuzzied. A fuzzy
translation is a string for which the original changed since it was
translated, therefore requiring some update by a translator to be usable.
When changes are small enough, the original translation is kept in PO files
but marked as fuzzy
.
Если вы планируете изменить ваши оригинальные шаблоны, для связи с
переводчиками используйте систему оповещения, предоставляемую пакетом
po-debconf
, а именно
podebconf-report-po. Наиболее активные переводчики очень
отзывчивы, и включение их работы вместе с вашими изменёнными шаблонами
позволит избежать вам дополнительных загрузок. Если вы используете шаблоны
на основе gettext, имя переводчика и его адрес электронной почты указаны в
заголовках PO-файлов и будут использоваться командой
podebconf-report-po.
Рекомендованное использование этой утилиты:
cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"
This command will first synchronize the PO and POT files in
debian/po
with the template files listed in
debian/po/POTFILES.in
. Then, it will send a call for
new translations, in the <debian-i18n@lists.debian.org>
mailing list. Finally, it will
also send a call for translation updates to the language team (mentioned in
the Language-Team
field of each PO file) as well as the
last translator (mentioned in Last-translator
).
Всегда ценится точный срок, отведённый для работы над переводом, чтобы переводчики могли организовать свою работу. Помните, что некоторые команды переводчиков используют формализованный процесс перевода/проверки, и задержка менее 10 дней считается чрезвычайно короткой. Более короткая задержка слишком сильно давит на команды переводчиков и должна устанавливаться только для очень небольших изменений.
Если у вас возникли сомнения, вы также можете связаться с командой перевода
данного языка (debian-l10n-xxxxx@lists.debian.org) или списком рассылки
<debian-i18n@lists.debian.org>
.
Когда текст шаблона debconf был изменён, и вы уверены, что это изменение не влияет на переводы, будьте добры по отношению к переводчикам и отмените статус неясных строк для их переводов.
Если вы не сделаете этого, весь шаблон не будет переведён пока переводчик не вышлет вам обновление.
Чтобы отменить статус неясных строк для переводов, вы
можете использовать msguntypot (часть пакета po4a
).
Создание файлов POT и PO заново.
debconf-updatepo
Создание копии POT-файла.
cp templates.pot templates.pot.orig
Создание копии всех PO-файлов.
mkdir po_fridge; cp *.po po_fridge
Изменение файлов шаблона debconf для исправления ошибок.
Создание файлов POT и PO заново (опять).
debconf-updatepo
Сейчас исправление опечатки привело к тому, что все переводы были отмечены как неясные, и это несчастное изменение является единственным различием между файлами PO вашего основного каталога и сохранёнными во временном каталоге файлами. Вот как решить эту проблема.
Отбросьте неясный перевод, восстановите перевод из сохранённых во временном каталоге файлов.
cp po_fridge/*.po .
Вручную слейте файлы PO с новым POT-файлов, но учтите бесполезные неясности.
msguntypot -o templates.pot.orig -n templates.pot *.po
Очистите.
rm -rf templates.pot.orig po_fridge
Templates text should not make reference to widgets belonging to some debconf interfaces. Sentences like If you answer Yes... have no meaning for users of graphical interfaces that use checkboxes for boolean questions.
Строки шаблонов должны также избегать в своём описании упоминания значений по умолчанию. Во-первых, это излишне, так как значения видны пользователям. Также это излишне потому, что значения по умолчанию могут различаться в зависимости от выбора сопровождающего (например, когда база данных debconf была автоматизирована).
Вообще говоря, попытайтесь избежать указания на действия пользователя. Просто представляйте факты.
You should avoid the use of first person (I will do this... or We recommend...). The computer is not a person and the Debconf templates do not speak for the Debian developers. You should use neutral construction. Those of you who already wrote scientific publications, just write your templates like you would write a scientific paper. However, try using the active voice if still possible, like Enable this if ... instead of This can be enabled if....
As a way of showing our commitment to our diversity statement, please use gender-neutral constructions in your writing. This means avoiding pronouns like he/she when referring to a role (like "maintainer") whose gender is unknown. Instead, you should use the plural form (singular they).
Эта часть содержит информацию, которая по большей части заимствована из страницы руководства debconf-devel(7).
Запрашивает у пользователя пароль. Используйте с осторожностью; помните, что пароль, вводимый пользователем, будет записан в базу данных debconf. Вероятно, вам следует как можно скорее очистить это значение в базе данных.
Выбор одного значения из нескольких предложенных. Выбор должен быть
определён в поле с именем 'Choices'. Разделите возможные значения запятыми
и пробелами, например так: Choices: yes, no, maybe
.
Если варианты выбора представляют собой переводимые строки, поле 'Choices'
может быть отмечено как переводимое так:
__Choices
. Двойное подчёркивание выделит каждый вариант
выбора в отдельную строку.
Также система po-debconf предлагает интересные возможности для отметки только некоторых вариантов выбора в качестве переводимых. Пример:
Template: foo/bar Type: Select #flag:translate:3 __Choices: PAL, SECAM, Other _Description: TV standard: Please choose the TV standard used in your country.
В этом примере только строка 'Other' является переводимой, остальные же представляют собой акронимы, которые не нужно переводить. Этот пример разрешает включение в файлы PO и POT только варианта 'Other'.
Система флагов для шаблонов debconf предлагает множество таких возможностей. В странице руководства po-debconf(7) приведены все эти возможности.
Подобен типу данных select, но пользователь может выбрать любое число вариантов из списка вариантов (или не выбрать ни один из них).
Этот тип данных не является вопросом самим по себе, а представляет собой примечание, которое может быть показано пользователю. Он должен использоваться только для важных примечаний, которые пользователи действительно должны заметить, поскольку debconf приложит максимум усилий для гарантии того, что пользователь заметит это примечание; установка будет остановлена до нажатия клавиши, в некоторых случаях пользователю будет даже выслано это примечание по почте.
This type is designed to handle error messages. It is mostly similar to the note type. Front ends may present it differently (for instance, the dialog front end of cdebconf draws a red screen instead of the usual blue one).
Рекомендуется использовать этот тип для любых сообщений, не которые необходимо обратить внимание пользователя для внесения исправлений любого вида.
Описания шаблонов имеют две части: краткую и расширенную. Краткое описание даётся в строке Description: данного шаблона.
Краткое описание должно быть коротким (50 символов или около того), чтобы оно могло быть обработано большинством интерфейсов debconf. Краткое описание также помогает переводчикам, поскольку переводы обычно длиннее оригиналов.
The short description should be able to stand on its own. Some interfaces do not show the long description by default, or only if the user explicitly asks for it or even do not show it at all. Avoid things like: "What do you want to do?"
Краткое описание не обязательно должно быть полным предложением. Это лишь часть, она должна быть краткой и эффективной рекомендацией.
Расширенное описание не должно слово в слово повторять краткое описание. Если вы не можете придумать длинное описание, то для начала подумайте ещё. Напишите в debian-devel. Попросите помощи. Прослушайте курс письма! Расширенное описание очень важно. Если в конце концов вы всё еще не можете ничего придумать, оставьте его пустым.
Расширенное описание должно состоять из полных предложений. Параграфы должны быть короткими и удобочитаемыми. Не смешивайте две идеи в одном параграфе, лучше разделите их на два.
Не будьте слишком подробны. Пользователи обычно игнорируют слишком длинные экраны. По опыту, 20 строк — это та граница, которую вам не следует пересекать, поскольку это означает, что в классическом диалоговом интерфейсе придётся прокручивать экран, а большинство пользователей этого просто не делают.
Расширенное описание никогда не должно включать в себя вопрос.
Для ознакомления с конкретными правилами, зависящими от типа шаблона (string, boolean и т. д.), прочтите нижеследующий текст.
This field should be used for select and multiselect types. It contains the possible choices that will be presented to users. These choices should be separated by commas.
Без конкретного указания за исключением следующего: используйте соответствующий тип из предыдущего раздела.
Ниже приведены конкретные инструкции для правильного написания Description (краткого и расширенного описаний) в зависимости от типа шаблона.
Краткое описание является приглашением, а не заголовком. Избегайте приглашений в виде вопросов (IP Address?) в пользу открытых приглашений (IP address:). Рекомендуется использовать двоеточие.
Расширенное описание дополняет краткое описание. В расширенной части объясните пользователю, что спрашивается, а не задавайте ему тот же вопрос при помощи более длинных слов. Используйте полные предложения. Краткие стиль письма крайне не рекомендуется.
The short description should be phrased in the form of a question, which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember that translations are often longer than original versions).
Опять же, избегайте обращения к конкретным виджетам интерфейса. Частой ошибкой таких шаблонов являются ответы на конструкции Да-типа.
The short description is a prompt and not a title. Do not use useless "Please choose..." constructions. Users are clever enough to figure out they have to choose something... :)
Расширенное описание должно заканчивать краткое описание. Оно может отсылать к доступным вариантам выбора. Также оно может содержать напоминание о том, что пользователь может выбрать более одного варианта из доступных, если выбран шаблон multiselect (хотя интерфейс обычно делает это очевидными).
Краткое описание должно рассматриваться как заголовок.
Расширенное описание представляет собой то, что будет отображено в качестве более подробного объяснения данного примечания. Фразы, подробный стиль письма.
Do not abuse debconf. Notes are the most
common way to abuse debconf. As written in the debconf-devel manual page:
it's best to use them only for warning about very serious problems. The
NEWS.Debian
or README.Debian
files
are the appropriate location for a lot of notes. If, by reading this, you
consider converting your Note type templates to entries in
NEWS.Debian
or README.Debian
,
please consider keeping existing translations for the future.
Если скорее всего поле Choices будет часто меняться, попробуйте использовать трюк __Choices. Так каждый индивидуальный выбор будет выделен в отдельную строку, что поможет переводчикам делать их работу.
If the default value for a select template is likely to vary depending on the user language (for instance, if the choice is a language choice), please use the _Default trick, documented in po-debconf(7).
This special field allows translators to put the most appropriate choice according to their own language. It will become the default choice when their language is used while your own mentioned Default Choice will be used when using English.
Do not use an empty default field. If you don't want to use default values, do not use Default at all.
If you use po-debconf (and you should; see Раздел 6.5.2.2, «Будьте добры к переводчикам»), consider making this field translatable, if you think it may be translated.
Пример, взятый из шаблонов пакета geneweb:
Template: geneweb/lang Type: select __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv) # This is the default choice. Translators may put their own language here # instead of the default. # WARNING : you MUST use the ENGLISH NAME of your language # For instance, the French translator will need to put French (fr) here. _Default: English[ translators, please see comment in PO files] _Description: Geneweb default language:
Note the use of brackets, which allow internal comments in debconf fields. Also note the use of comments, which will show up in files the translators will work with.
The comments are needed as the _Default trick is a bit confusing: the translators may put in their own choice.
This section contains global information for developers to make translators' lives easier. More information for translators and developers interested in internationalization are available in the Internationalisation and localisation in Debian documentation.
Подобно тем, кто занимается переносами, перед переводчиками стоит сложная задача. Они работают над многими пакетами и должны сотрудничать с большим количеством разных сопровождающих. Более того, по большей части они не являются носителями английского языка, поэтому вам следует быть с ними особенно вежливыми.
The goal of debconf
was to make
package configuration easier for maintainers and for users. Originally,
translation of debconf templates was handled with
debconf-mergetemplate. However, that technique is now
deprecated; the best way to accomplish debconf
internationalization is by using the
po-debconf
package. This method is
easier both for maintainer and translators; transition scripts are provided.
При использовании po-debconf
,
перевод сохраняется в файлах .po
(формате, извлечённом
из gettext). Специальные файлы шаблонов содержат
оригинальные сообщения и пометки для тех полей, которые могут быть
переведены. Когда вы изменяете значение поля, которое может быть
переведено, вызывая команду debconf-updatepo, перевод
отмечается как требующий внимания переводчиков. Тогда, во время сборки,
программа dh_installdebconf заботится обо всей требуемой
магии по добавлению шаблона вместе с обновлёнными переводами в двоичные
пакеты. За подробностями обратитесь к странице руководства po-debconf(7).
Интернационализация документации очень важна для пользователей, но требует большого труда. Не существует способа сделать так, чтобы не нужно было делать эту работу, но вы можете упростить её для переводчиков.
Если вы сопровождаете документацию любого размера, для переводчиков будет
проще, если они будут иметь доступ к системе управления исходным кодом. Это
позволяет переводчикам видеть разницу между двумя версиями документации,
поэтому, например, они могут видеть, что нужно перевести заново.
Рекомендуется, чтобы в переведённой документации содержалась информация о
том, на базе какой системы управления изменениями исходного кода
основывается разработка документации. Интересная система предоставляется
doc-check из пакета debian-installer
, которая показывает статус
перевода для любого данного языка и использует структурированные комментарии
для текущей редакции файла, который должен быть переведён, для переведённого
файла, редакции оригинального файла, на котором основан перевод. Вероятно,
вы захотите использовать и предоставлять такую информацию в вашей системе
управления версиями.
If you maintain XML or SGML documentation, we suggest that you isolate any language-independent information and define those as entities in a separate file that is included by all the different translations. This makes it much easier, for instance, to keep URLs up to date across multiple files.
Some tools (e.g. po4a
, poxml
, or the translate-toolkit
) are specialized in extracting
the translatable material from different formats. They produce PO files, a
format quite common to translators, which permits seeing what needs to be
re-translated when the translated document is updated.
Поддержка файлов autoconf config.sub
и config.guess
в актуальном состоянии является
критической задачей для тех, кто занимается переносом, особенно на более
волатильные архитектуры. Некоторые очень хорошие практики по созданию
пакетов для любого пакета, использующего autoconf и/или
automake были синтезированы в /usr/share/doc/autotools-dev/README.Debian.gz
из
пакета autotools-dev
package.
Настойчиво рекомендуем прочитать этот файл и следовать приведённым в нём
рекомендациям.
По ряду причина для библиотек всегда трудно создавать пакеты. Политика налагает множество ограничений для облегчения из сопровождения и для того, чтобы гарантировать, что обновления будут настолько просты, насколько это возможно, когда выходит новая версия из основной ветки разработки. Поломка в библиотеке может вызвать поломку множества зависимых пакетов.
Хорошие практики по созданию пакетов для библиотек были сгруппированы в справочнику по созданию пакетов библиотек.
Обязательно пройдите по ссылке Политика документации.
Если ваш пакет содержит документацию, собираемую из XML или SGML, рекомендуем вам не добавлять исходный код в форматах XML или SGML в двоичный пакет (-ы). Если пользователи захотят получить исходный код документации, им следует загрузить пакет с исходным кодом.
Политика определяет, что документация должна поставляться в формате HTML. Мы также рекомендуем поставлять документацию в формате PDF и в виде обычного текста, если это удобно, и если возможно обеспечить вывод достаточного качества. Тем не менее, предоставление документации, исходным форматом которой является HTML, в виде обычного текста не является подходящим.
Крупные руководства должны при установке регистрироваться в doc-base
. Дополнительную информацию см. в
документации пакета doc-base
.
Политика Debian (раздел 12.1) указывает, что справочные страницы должны поставляться со всякой программой, утилитой и функцией, и предлагает поставку справочных страниц для других объектов, таких как файлы настройки. Если та работа, для которой вы создаёте пакеты, не имеет таких справочных страниц, постарайтесь написать их самостоятельно для включения в ваш пакет и отправки в основную ветку разработки.
The manpages do not need to be written directly in the troff format. Popular source formats are DocBook, POD and reST, which can be converted using xsltproc, pod2man and rst2man respectively. To a lesser extent, the help2man program can also be used to write a stub.
Некоторые конкретные типы пакетов имеют свои специальные подполитики и соответствующие правила и практики создания пакетов:
Perl related packages have a Perl
policy; some examples of packages following that policy are
libdbd-pg-perl
(binary perl module)
or libmldbm-perl
(arch independent
perl module).
Python related packages have their Python policy; see /usr/share/doc/python/python-policy.txt.gz
in the python
package.
Связанные с Emacs пакеты имеют Политику Emacs.
Связанные с Java пакеты имеют свою Политику Java.
OCaml related packages have their own policy, found in /usr/share/doc/ocaml/ocaml_packaging_policy.gz
from the ocaml
package. A good
example is the camlzip
source
package.
Пакеты, предоставляющие XML или SGML DTD должны соответствовать
рекомендациям из пакета sgml-base-doc
.
Пакеты Lisp должны регистрироваться в common-lisp-controller
, об этом
см. /usr/share/doc/common-lisp-controller/README.packaging
.
Добавление большого количества независящих от архитектуры данных в пакеты с программами не является в каком бы то ни было смысле необычным явлением при создании пакетов. Например, аудио файлы, наборы иконок, шаблоны обоев рабочего стола или другие графические файлы. Если размер этих данных незначителен по сравнению с размером остального пакета, возможно лучшим решением будет сохранение всех данных в одном пакете.
However, if the size of the data is considerable, consider splitting it out
into a separate, architecture-independent package
(_all.deb
). By doing this, you avoid needless
duplication of the same data into ten or more .debs, one per each
architecture. While this adds some extra overhead into the
Packages
files, it saves a lot of disk space on Debian
mirrors. Separating out architecture-independent data also reduces
processing time of lintian (see Раздел A.2, «Инструменты для проверки пакетов на предмет ошибок и соответствия стандартам») when run over the entire Debian archive.
Если вам требуется определённая локаль во время сборки, вы можете создать временный файл с помощью следующих команд:
Если вы установите LOCPATH
значение, эквивалентное
/usr/lib/locale
, а значение LC_ALL
будет имя той локали, которую вы создаёте, у вас будет то, что вам нужно при
работе из-за учётной записи суперпользователя. Что-то вроде этого:
LOCALE_PATH=debian/tmpdir/usr/lib/locale LOCALE_NAME=en_IN LOCALE_CHARSET=UTF-8 mkdir -p $LOCALE_PATH localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET # Используйте локаль LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date
deborphan — программам, помогающая пользователям определить то, какие пакеты могут быть безопасно удалены из системы, т. е. те, от которых не зависит более ни один пакет. По умолчанию поиск осуществляется только в разделах libs и oldlibs для обнаружения неиспользуемых библиотек. Но когда вы передали этой программе необходимых аргумент, она пытается найти все бесполезные пакеты.
Например, с аргументом --guess-dummy
,
deborphan пытается найти все переходные пакеты, которые
нужны для обновления, но которые теперь могут быть легко удалены. Для этого
она ищет строку dummy или transitional в их кратком описании.
Поэтому когда вы создаёте такой пакет, убедитесь, что этот текст добавлен в ваше краткое описание. Если вы хотите ознакомиться с примерами, запустите: apt-cache search .|grep dummy или apt-cache search .|grep transitional.
Also, it is recommended to adjust its section to oldlibs
and its priority to optional
in order to ease
deborphan's job.
Существует два вида оригинальных tar-архивов с исходным кодом: чистый исходный код и запакованный заново исходный код основной ветки разработки.
Определяющей характеристикой чистого tar-архива с исходным кодом является
то, что файл .orig.tar.{gz,bz2,xz}
побайтово идентичен
tar-архиву, который официальной распространялся автором основной ветки
разработки.[6] Это позволяет использовать
контрольные суммы для простой проверки, что все изменения между версией
Debian и версией основной ветки содержаться в db=iff-файле Debian. Кроме
того, если оригинальный исходный код имеет большой размер, авторы основной
ветки разработки и другие, кто уже имеют tar-архив из основной ветки, могут
сохранить время, затрачиваемое на скачивание, в том случае, если они хотят
подробно проверить ваш пакет.
There are no universally accepted guidelines that upstream authors follow regarding the directory structure inside their tarball, but dpkg-source is nevertheless able to deal with most upstream tarballs as pristine source. Its strategy is equivalent to the following:
Он распаковывает tar-архив в пустой временный каталог, выполняя
zcat путь/к/имя-пакета
_версия-основной-ветки
.orig.tar.gz | tar xf -
Если после этого временный каталог не содержит ничего кроме одного каталога
и не содержит других файлов, dpkg-source переименовывает
этот каталог в
.
Имя каталога верхнего уровня в tar-архиве не имеет значения и просто
забывается.
имяпакета
-версия-основной-ветки
(.orig)
В противном случае, tar-архив основной ветки должен быть запакован без
общего каталога верхнего уровня (позор автору основной ветки!). В этом
случае dpkg-source переименовывает
самостоятельно временный каталог в
.
имяпакета
-версия-основной-ветки
(.orig)
Вы должны загружать пакеты с чистым исходным кодом, если это возможно, но имеются причины, по которым это может быть невозможно. Это имеет место, когда основная ветка вообще не поставляет исходный код в виде сжатого при помощи gzip tar-архива, либо если tar-архив основной ветки содержит не свободный в соответствии с критериями DFSG материал, который вам следует удалить до момента осуществления загрузки.
В этих случаях разработчик должен создать подходящий файл
.orig.tar.{gz,bz2,xz}
самостоятельно. Мы говорим о
таком tar-архиве как о запакованном заново исходном коде основной ветки.
Заметьте, что запакованный заново исходный код основной ветки отличается от
родного пакета Debian. Запакованный заново исходный код содержит
специфичные для Debian изменения в отдельных файлах
.diff.gz
или
.debian.tar.{gz,bz2,xz}
и всё ещё имеет номер версии,
составленный из версия-основной-ветки
и
версия-debian
.
Возможны такие случаи, когда желательно запаковать исходный код заново, даже
несмотря на то, что основная ветка разработки поставляет
.tar.{gz,bz2,xz}
, который в принципе может использовать
в его чистой форме. Наиболее очевидным случаем является ситуация, когда
может быть достигнута значительная экономия места путём
повторной упаковки tar-архива или путём удаления действительно ненужного
хлама из архива основной ветки. Используйте это на своё усмотрение, но
будьте готовы защищать своё решение, если вы запаковали заново исходный код,
которые мог бы быть чистым.
Запакованный заново .orig.tar.{gz,bz2,xz}
должен быть документирован в получившемся
пакете с исходным кодом. Подробная информация о том, как был получен
запакованный заново исходный код, а также о том, как этот процесс может быть
воспроизведён, должна быть предоставлена в
debian/copyright
. Также рекомендуется предоставлять
цель get-orig-source
в вашем файле
debian/rules
, которая повторяет этот процесс, это
описано в Руководстве по политике, Основной сборочный
сценарий: debian/rules
.
не должен содержать какие-либо файлы, которые получены не от авторов основной ветки разработки, или содержание которых было изменено вами.[7]
должен, за исключением случаев, когда это
невозможно по юридическим причинам, сохранять всю целиком сборочную
инфраструктуру и инфраструктуру для переноса, предоставляемую автором
основной ветки разработки. Например, то, что какой-то файл используется
только для сборки под MS-DOS, не является достаточным основанием для его
удаления. Сходным образом, Makefile
, предоставляемый
основной веткой разработки не должен быть удалён, даже если ваш файл
debian/rules
перезаписывает его, запуская сценарий
настройки.
(Обоснование: Обычно пользователи Debian, желающие собрать ПО для отличных от Debian платформ, загружают исходный код с зеркала Debian, а не пытаются найти каноничный выпуск основной ветки разработки).
должен использовать
в качестве имени каталога верхнего уровня в своём tar-архиве. Это позволяет
отличить чистые tar-архивы от запакованных заново.
имяпакета
-версия-основной-ветки
.orig
должен быть сжат с помощью gzip или bzip с максимальным сжатием.
Sometimes it is necessary to change binary files contained in the original
tarball, or to add binary files that are not in it. This is fully supported
when using source packages in “3.0 (quilt)” format; see the
dpkg-source(1)
manual page for details. When using the older format “1.0”, binary files
can't be stored in the .diff.gz
so you must store a
uuencoded (or similar) version of the file(s) and decode
it at build time in debian/rules
(and move it in its
official location).
A debug package is a package that contains additional information that can be used by gdb. Since Debian binaries are stripped by default, debugging information, including function names and line numbers, is otherwise not available when running gdb on Debian binaries. Debug packages allow users who need this additional debugging information to install it without bloating a regular system with the information.
The debug packages contain separated debugging symbols that
gdb can find and load on the fly when debugging a program
or library. The convention in Debian is to keep these symbols in
/usr/lib/debug/
, where
path
path
is the path to the executable or library.
For example, debugging symbols for /usr/bin/foo
go in
/usr/lib/debug/usr/bin/foo
, and debugging symbols for
/usr/lib/libfoo.so.1
go in
/usr/lib/debug/usr/lib/libfoo.so.1
.
Debug symbol packages can be generated automatically for any binary package
that contains executable binaries, and except for corner cases, it should
not be necessary to use the old manually generated ones anymore. The package
name for a automatic generated debug symbol package ends in
-dbgsym
.
The dbgsym
packages are not installed into the regular
archives, but in dedicated archives. That means, if you need the debug
symbols for debugging, you need to add this archives to your apt
configuration and then install the dbgsym
package you are
interested in. Please read https://wiki.debian.org/HowToGetABacktrace on how to do that.
Before the advent of the automatic dbgsym
packages, debug
packages needed to be manually generated. The name of a manual debug
packages ends in -dbg
. It is recommended to migrate such
old legacy packages to the new dbgsym
packages whenever
possible. The procedure to convert your package is described in https://wiki.debian.org/AutomaticDebugPackages but the gist is to
use the --dbgsym-migration='pkgname-dbg (<<
currentversion~)'
switch of the dh_strip
command.
However, sometimes it is not possible to convert to the new
dbgsym
packages, or you will encounter the old manual
-dbg packages in the archives, so you might need to deal with them. It is
not recommended to create manual -dbg packages for new packages, except if
the automatic ones won't work for some reason.
One reason could be that debug packages contains an entire special debugging build of a library or other binary. However, usually separating debugging information from the already built binaries is sufficient and will also save space and build time.
This is the case, for example, for debugging symbols of Python extensions.
For now the right way to package Python extension debug symbols is to use
-dbg
packages as described in https://wiki.debian.org/Python/DbgBuilds.
To create -dbg
packages, the package maintainer has to
explicitly specify them in debian/control
.
The debugging symbols can be extracted from an object file using objcopy --only-keep-debug. Then the object file can be stripped, and objcopy --add-gnu-debuglink used to specify the path to the debugging symbol file. objcopy(1) explains in detail how this works.
Заметьте, отладочный пакет должен зависеть от пакета, для которого он предоставляет отладочные символы, и эта зависимость должна быть зависимостью от конкретной версии. Например:
Depends: libfoo (= ${binary:Version})
The dh_strip command in debhelper
supports creating debug packages, and
can take care of using objcopy to separate out the
debugging symbols for you. If your package uses debhelper/9.20151219
or newer, you don't need to
do anything. debhelper
will generate
debug symbol packages (as package
-dbgsym) for you with no
additional changes to your source package.
Метапакет обычно является пустым пакетом, который облегчает установку
связанного набора пакетов, которые со временем могут развиваться. Это
достигается благодаря тому, что метапакет зависит от всех пакетов данного
набора. Благодаря мощи APT, сопровождающий метапакета может изменять
зависимости, и пользовательская система будет автоматически получать
дополнительные пакеты. Кроме того, отброшенные пакеты, которые были
установлены автоматически, будут помечены как кандидаты на удаление (и даже
будут автоматически удалены с помощью aptitude).
gnome
и linux-image-amd64
являются примерами метапакетов
(собранных из пакетов с исходным кодом meta-gnome2
и linux-latest
).
The long description of the meta-package must clearly document its purpose so that the user knows what they will lose if they remove the package. Being explicit about the consequences is recommended. This is particularly important for meta-packages that are installed during initial installation and that have not been explicitly installed by the user. Those tend to be important to ensure smooth system upgrades and the user should be discouraged from uninstalling them to avoid potential breakages.
[6] We cannot prevent upstream authors from changing the tarball they distribute
without also incrementing the version number, so there can be no guarantee
that a pristine tarball is identical to what upstream
currently distributing at any point in time. All that
can be expected is that it is identical to something that upstream once
did distribute. If a difference arises later (say, if
upstream notices that they weren't using maximal compression in their
original distribution and then re-gzip it), that's just
too bad. Since there is no good way to upload a new
.orig.tar.{gz,bz2,xz}
for the same version, there is
not even any point in treating this situation as a bug.
[7] As a special exception, if the omission of non-free files would lead to the
source failing to build without assistance from the Debian diff, it might be
appropriate to instead edit the files, omitting only the non-free parts of
them, and/or explain the situation in a README.source
file in the root of the source tree. But in that case please also urge the
upstream author to make the non-free components easier to separate from the
rest of the source.