# 2. Общий обзор каталога `debian/`

Эта статья даёт краткие пояснения к различным файлам, важным для создания пакетов Ubuntu, которые содержатся в каталоге `debian/`. Самыми важными из них являются `changelog`, `control`, `copyright`, and `rules`. Они требуются для всех пакетов. Многие дополнительные файлы в `debian/` могут использоваться для настройки и изменения поведения пакета. Некоторые из этих файлов обсуждаются в этой статье, но это далеко не полный список.

## 2.1. Файл 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.8-0ubuntu1) trusty; urgency=low

      * New upstream release with lots of bug fixes and feature improvements.

    -- Jane Doe <packager@example.com>  Thu, 21 Oct 2013 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».

## 2.2. Файл 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.5
    Build-Depends: debhelper (>= 7)
    Vcs-Bzr: 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».

## 2.3. Файл 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. Мы рекомендуем вам также использовать этот формат.

## 2.4. Файл 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».

## 2.5. Дополнительные файлы

### 2.5.1. Файл 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».

### 2.5.2. Файл 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.

### 2.5.3. Файл 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».

## 2.6. Дополнительные ресурсы

В дополнение к ссылкам на «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» описаны дополнительные файлы, которые могут быть использованы.