Общий обзор каталога debian/¶
Эта статья даёт краткие пояснения к различным файлам, важным для создания пакетов Ubuntu, которые содержатся в каталоге debian/. Самыми важными из них являются changelog, control, copyright, and rules. Они требуются для всех пакетов. Многие дополнительные файлы в debian/ могут использоваться для настройки и изменения поведения пакета. Некоторые из этих файлов обсуждаются в этой статье, но это далеко не полный список.
Файл changelog¶
Этот файл, как следует из его названия — это список изменений, внесённых в каждую версию. Он имеет особый формат, который показывает имя пакета, версию, дистрибутив, изменения, и кто вносил изменения в данное время. Если у вас есть ключ GPG (смотрите: Подготовка), убедитесь, что вы используете в changelog те же имя и адрес электронной почты, что и в вашем ключе. Ниже приведен шаблон changelog:
package (version) distribution; urgency=urgency
* change details
- more change details
* even more change details
-- maintainer name <email address>[two spaces] date
Формат (особенно даты) важен. Дата должна быть в формате RFC 5322, который можно увидеть при выполнении команды date -R. Для удобства, можно использовать для редактирования changelog команду dch. Она обновит дату автоматически.
Пункты с незначительными изменениями отмечаются дефисом «-», в то время как в важных пунктах используется звездочка «*».
Если вы создаёте пакет «с нуля», dch --create (dch находится в пакете devscripts) создаст для вас стандартный файл debian/changelog.
Вот пример файла changelog для hello:
hello (2.6-0ubuntu1) natty; urgency=low
* New upstream release with lots of bug fixes and feature improvements.
-- Jane Doe <packager@example.com> Thu, 21 Apr 2011 11:12:00 -0400
Обратите внимание, что версия имеет -0ubuntu1 добавленный к нему, это - distro версия, используемая так, чтобы упаковка могла быть обновлена (чтобы исправить ошибки, например) с новыми закачками в той же исходной версии выпуска.
Ubuntu и Debian используют немного различающиеся схемы нумерации версий пакетов, чтобы избежать конфликта пакетов с одной и той же исходной версией. Если пакет Debian был изменён в Ubuntu, к концу Debian-версии добавляется ubuntuX (где X — номер редакции в Ubuntu). Таким образом, если пакет Debian hello 2.6-1 был изменён в Ubuntu, номер версии будет 2.6-1ubuntu1. Если пакет приложения в Debian не существует, то редакция Debian равна 0 (например, 2.6-0ubuntu1).
Для дальнейшей информации смотрите раздел о файле changelog (Раздел 4.4) в «Debian Policy Manual».
Файл control¶
Файл control содержит информацию, которую использует менеджер пакетов (такой, как apt-get, synaptic или adept), сборочные зависимости, информацию мэйнтейнера и многое другое.
Для пакета Ubuntu hello файл control выглядит следующим образом:
Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XSBC-Original-Maintainer: Jane Doe <packager@example.com>
Standards-Version: 3.9.1
Build-Depends: debhelper (>= 7)
Bzr-Vcs: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/
Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
The GNU hello program produces a familiar, friendly greeting. It
allows non-programmers to use a classic computer science tool which
would otherwise be unavailable to them. Seriously, though: this is
an example of how to do a Debian package. It is the Debian version of
the GNU Project's `hello world' program (which is itself an example
for the GNU Project).
Первый абзац описывает исходный пакет, включая список пакетов, требуемых для сборки данного пакета из исходного кода, в поле Build-Depends. Он также содержит некоторую метаинформацию, такую как имя мэйнтейнера, версию Debian Policy, с которой компилируется пакет, местоположение репозитория управления версиями и домашнюю страницу апстрима.
Обратите внимание, что в Ubuntu мы указываем в поле Maintainer общий адрес, поскольку кто угодно может внести изменения в любой пакет (в отличие от Debian, где изменение пакетов обычно доступно лишь определённому человеку или команде). Обычно в пакетах Ubuntu в поле Maintainer указывается Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>. Если это поле было изменено, старое значение сохраняется в поле XSBC-Original-Maintainer. Это делается автоматически сценарием update-maintainer из пакета ubuntu-dev-tools. Дополнительную информацию смотрите в Debian Maintainer Field spec на вики-страницах Ubuntu.
Каждый дополнительный абзац описывает бинарный пакет, который будет создан.
Для получения дополнительной информации смотрите раздел о файле control (Глава 5) в «Debian Policy Manual».
Файл copyright¶
Этот файл показывает информацию о копирайте на исходный код upstream и файлы, необходимые для сборки пакетов. Ubuntu и Debian Policy (Section 12.5) требуют, чтобы каждый пакет устанавливал сжатую версию информации о копирайте и лицензии в /usr/share/doc/$(package_name)/copyright.
Как правило, информацию об авторских правах можно найти в файле COPYING в каталоге с исходным кодом программы. Этот файл должен включать такую информацию, как имена автора и упаковщика, URL, из которого получен источник, строку со значком копирайта с указанием года и владельца авторских прав, а также сам текст авторского права. Шаблон для примера:
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: Hello
Source: ftp://ftp.example.com/pub/games
Files: *
Copyright: Copyright 1998 John Doe <jdoe@example.com>
License: GPL-2+
Files: debian/*
Copyright: Copyright 1998 Jane Doe <packager@example.com>
License: GPL-2+
License: GPL-2+
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
.
You should have received a copy of the GNU General Public
License along with this package; if not, write to the Free
Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA 02110-1301 USA
.
On Debian systems, the full text of the GNU General Public
License version 2 can be found in the file
`/usr/share/common-licenses/GPL-2'.
Этот пример соответствует формату Machine-readable debian/copyright. Мы рекомендуем вам также использовать этот формат.
Файл rules¶
Последний файл, который мы рассмотрим, это rules. Он выполняет всю работу по сборке нашего пакета. Это Makefile, в котором есть функции компиляции программы, её установки и создания .deb-пакета из установленных файлов. В нём есть также функция очистки файлов сборки, которая удаляет всё, кроме собственно пакета исходного кода.
Вот упрощённый пример файла rules, созданного dh_make (который можно найти в пакете dh-make):
#!/usr/bin/make -f
# -*- makefile -*-
# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1
%:
dh $@
Давайте рассмотрим этот файл внимательнее. На каждом этапе сборки debian/rules вызывается с аргументом, который передаётся /usr/bin/dh, который, в свою очередь, вызывает необходимые команды dh_*.
dh запускает последовательность команд debhelper. Поддерживаемые последовательности соответствуют целям файла debian/rules: «build», «clean», «install», «binary-arch», «binary-indep» и «binary». Чтобы увидеть, какие команды выполняются в каждой цели, наберите:
$ dh binary-arch --no-act
Командам из последовательности binary-indep передаётся аргумент -i, чтобы они затрагивали только архитектурно-независимые пакеты, а командам из последовательности binary-arch — аргумент -a, чтобы онм затрагивали только архитектурно-зависимые пакеты.
Каждая команда debhelper при её успешном выполненении делает запись в журнале debian/package.debhelper.log (который затем удаляет dh_clean.) Таким образом dh может определить, какие команды уже были выполнены и для каких пакетов, что помогает избежать повторного выполнения этих команд.
При каждом запуске dh он изучает журнал, находит добавленные последними команды, которые относятся к указанной последовательности. Затем он продолжает выполнение со следующей команды в этой последовательности. Опции --until, --before, --after и --remaining могут изменить это поведение.
Если в debian/rules есть функция с именем, похожим на override_dh_команда, то вместо данной команды dh выполнит данную функцию. Эта функция может запустить ту же команду с другими аргументами, или же совершенно другую команду. (Замечание: для использования этой функциональности при сборке требуется пакет debhelper версии не менее 7.0.50).
За дополнительными примерами обратитесь к /usr/share/doc/debhelper/examples/ и man dh. Смотрите также раздел о файле rules (Раздел 4.9) в «Debian Policy Manual».
Дополнительные файлы¶
Файл install¶
Файл install используется dh_install для установки файлов в двоичный пакет. Он имеет два стандартных варианта использования:
- Для установки в ваш пакет файлов, не установленных оригинальной системой сборки.
- Разделение одного большого пакета источника на несколько бинарных пакетов.
В первом случае файл install должен содержать одну строку для каждого устанавливаемого файла, указывающую как файл, так и установочный каталог. Например, следующий файл install установит сценарий foo из корневого каталога пакета исходного кода в usr/bin и desktop-файл из каталога debian в usr/share/applications:
foo usr/bin
debian/bar.desktop usr/share/applications
Если пакет исходного кода производит несколько двоичных пакетов, dh установит файлы в debian/tmp вместо установки непосредственно в debian/<пакет>. Файлы, установленные в debian/tmp затем можно переместить в отдельные двоичные пакеты с помощью нескольких файлов $имя_пакета.install. Это часто делается, чтобы разбить большое количество не зависящих от архитектуры данных из зависящих от архитектуры пакетов в пакеты Architecture: all. В этом случае нужно указать только имена устанавливаемых файлов (или каталогов), без установочного каталога. Например, foo.install, содерщащий только зависящие от архитектуры файлы, может выглядеть наподобие:
usr/bin/
usr/lib/foo/*.so
В то время как foo-common.install, содержащий только не зависящие от архитектуры файлы, может выглядеть так:
/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/
Будут созданы два двоичных пакета: foo и foo-common. Для обоих требуется их собственный абзац в debian/control.
Для дополнительных подробностей смотрите man dh_install и раздел о файле install (Раздел 5.11) в «Debian New Maintainers’ Guide».
Файл watch¶
Файл debian/watch позволяет автоматически проверять наличие новых версий в апстриме с помощью инструмента uscan из пакета devscripts. Первой строкой файла watch должна быть версия формата (3 на момент написания этого руководства), а следующий строки содержат любые URL для анализа. Например:
version=3
http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz
Запуск uscan в корневом каталоге исходников сравнит номер апстрим-версии в debian/changelog с последней доступной в апстриме версией. Если в апстриме найдена новая версия, она будет автоматически загружена. Например:
$ uscan
hello: Newer version (2.7) available on remote site:
http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
(local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
and symlinked hello_2.7.orig.tar.gz to it
Если ваши тарболы «живут» на Launchpad, файл debian/watch будет немного более сложным (о том, почему это так, смотрите Question 21146 и Bug 231797). В этом случае используйте что-то наподобие:
version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz
Дополнительные сведения смотрите в man uscan и в разделе о файле watch (Раздел 4.11) «Debian Policy Manual».
Список пакетов, для которых файл watch сообщает о том, что они не синхронизированы с апстримом, смотрите Ubuntu External Health Status.
Файл source/format¶
Этот файл указывает формат пакета исходного кода. Он должен содержать одну строку, показывающую выбранный формат:
- 3.0 (native) для «родных» пакетов Debian (апстрим-версия отсутствует)
- 3.0 (quilt) для пакетов с отдельным тарболом из апстрима
- 1.0 для пакетов, желающих явно указать формат по умолчанию
В настоящее время по умолчанию выбирается формат пакета исходного кода 1.0, если этот файл отсутствует. В файле source/format можно указать его явно. Если вы не используете этот файл для указания формата исходного кода, Lintian выдаст предупреждение об отстутствии файла. Это чисто информационное предупреждение и его можно без опасений проигнорировать.
Рекомендуется использовать более новый формат 3.0. Он предоставляет некоторые новые возможности:
- Поддержка дополнительных форматов сжатия: bzip2, lzma и xz
- Поддержка нескольких архивов с оригинальным исходным кодом
- Необязательно перепаковывать архив с оригинальным исходным кодом, чтобы удалить директорию debian.
- Специфичные для Debian изменения теперь хранятся не в одном файле .diff.gz, а в виде нескольких патчей, совместимых с quilt, в каталоге debian/patches/
http://wiki.debian.org/Projects/DebSrc3.0 подытоживает дополнительную информацию, касающуюся перехода на формат пакетов исходого кода 3.0.
Для получения дополнительных подробностей смотрите man dpkg-source и раздел о файле source/format (Раздел 5.21) в «Debian New Maintainers’ Guide».
Дополнительные ресурсы¶
В дополнение к ссылкам на «Debian Policy Manual» в каждом вышеприведённом разделе, «Debian New Maintainers’ Guide» содержит более подробное описание каждого файла. Глава 4, «Required files under the debian directory» описывает файлы control, changelog, copyright и rules. В Главе 5, «Other files under the debian directory» описаны дополнительные файлы, которые могут быть использованы.