Глава 2. Первые шаги

# Глава 2. Первые шаги

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.

Давайте попробуем создать свой собственный пакет (или, ещё лучше, адаптировать существующий).

## 2.1. Порядок сборки пакета Debian

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

- получение копии исходного ПО, обычно в формате сжатого tar

  - ``пакет`-`версия`.tar.gz`

- добавление специальных изменений Debian в исходную программу в каталог `debian` и создание неродного (non-native) пакета с исходным кодом (то есть, набора входных файлов, используемых для сборки пакета Debian) в формате `3.0 (quilt)`

  - ``пакет`_`версия`.orig.tar.gz`
  - ``пакет`_`версия`-`редакция`.debian.tar.gz` [4]
  - ``пакет`_`версия`-`редакция`.dsc`

- сборка двоичных пакетов Debian для получения обычных файлов пакетов для установки в формате `.deb` (или в формате `.udeb`, который используется Debian Installer) из пакета Debian с исходным кодом

  - ``пакет`_`версия`-`редакция`_`архитектура`.deb`

Заметим, что в именах файлов пакетов Debian для разделения ``пакета`` и ``версии`` используется символ `_` (подчёркивание), а не `-` (дефис), как в имени оригинального tar-файла.

В именах файлов, представленных выше, замените часть ``пакет`` на имя пакета, часть ``версия`` на версию исходной программы, часть ``редакция`` на редакцию Debian и часть ``архитектура`` на архитектуру, для которой предназначен пакет, в соответствии с политикой Debian [5].

Каждый шаг, показанный ранее, детально описан на примерах в последующих разделах.

## 2.2. Выбор программы

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

- команду aptitude

- веб-страницу пакетов Debian

- the Debian Package Tracker web page

Если пакет уже есть, то просто установите его! :-) Если случится так, что он окажется брошенным (orphaned) — то есть сопровождающий передал его Debian QA Group, то вы сможете подобрать его, если он ещё будет доступен. Также вы можете взять пакет, если его сопровождающий послал «запрос об усыновлении» (Request for Adoption, RFA) [6].

Есть несколько ресурсов для получения информации о состоянии владения пакетом:

- Команда wnpp-alert из пакета `devscripts`

- Требующие доработки и будущие пакеты

- Журналы сообщений об ошибках Debian: ошибки в псевдо-пакете `wnpp` в `unstable`

- Пакеты Debian, которым нужна забота

- Просмотр ошибок `wnpp` на основе категорий debtag

Попутно отметим, что в Debian уже есть пакеты для большинства типов программ, и их количество в архиве Debian намного больше, чем участников с правом загрузки. Поэтому работа над пакетами, которые уже включены в архив, намного предпочтительней (и с большей вероятностью получит поручительство) с точки зрения других разработчиков [7]. Этого можно достичь различными путями:

- подобрать брошенный, но пока активно используемый пакет

- войти в одну из команд по пакетированию

- исправлять ошибки в очень популярных пакетах

- подготовить пакет для QA или NMU загрузки

If you are able to adopt the package, get the sources (with something like `apt-get source `packagename``) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable to your case.

Если пакет новый и вы решили, что он нужен в Debian, то сделайте следующее:

- Во-первых, вы должны знать, что программа работает и вы, поработав с ней некоторое время, сочли её полезной.

- You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the `wnpp` pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not — find another interesting program that nobody is maintaining.

- У программы обязательно должна быть лицензия.

  - Для секции `main` политика Debian требует, чтобы программа удовлетворяла критериям Debian по определению Свободного ПО (DFSG) и не зависела от пакетов вне `main` для компиляции или выполнения. Это предпочтительный вариант.

  - Для секции `contrib` она должна удовлетворять DFSG, но может зависеть от пакетов вне `main` для компиляции или выполнения.

  - Для секции `non-free` она может не удовлетворять DFSG, но должна быть распространяема.

  - Если вы не уверены в том, где должна размещаться программа, отправьте текст лицензии в debian-legal@lists.debian.org и попросите совета.

- The program should not introduce security and maintenance concerns into the Debian system.

  - The program should be well documented and its code needs to be understandable (i.e., not obfuscated).

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

  - Программа определённо не должна требовать запуска с помощью setuid root, а ещё лучше — вообще не требовать прав доступа setuid или setgid к чему-либо.

  - Программа не должна работать как служба, размещаться в каталогах `*/sbin` или открывать порты с правами root.

Of course, the last one is just a safety measure, and is intended to save you from enraging users if you do something wrong in some setuid daemon… When you gain more experience in packaging, you'll be able to package such software.

Как начинающий сопровождающий, не беритесь за сложные пакеты, пока не научитесь пакетировать самые простые.

- Простые пакеты

  - одиночный двоичный пакет, архитектура = all (набор данных, например обои для рабочего стола)

  - одиночный двоичный пакет, архитектура = all (исполняемые файлы, написанные на интерпретируемых языках, таких как оболочка POSIX)

- Пакеты средней сложности

  - одиночный двоичный пакет, архитектура = any (исполняемые двоичные файлы ELF, скомпилированные из исходного кода на C и C++)

  - несколько двоичных пакетов, архитектура = any + all (пакеты с исполняемыми двоичными файлами ELF + документация)

  - исходный код в формате, отличном от `tar.gz` или `tar.bz2`

  - исходный код с содержимым, не подлежащим распространению

- Пакеты повышенной сложности

  - пакет для интерпретируемого модуля, используемого другими пакетами

  - пакет для обычной библиотеки ELF, используемого другими пакетами

  - несколько двоичных пакетов, включающих пакет с библиотекой ELF

  - исходный код, получаемый из нескольких источников

  - пакеты с модулями ядра

  - пакеты с заплатами к ядру

  - любой пакет со сложными сценариями сопровождающего

Пакетирование пакетов повышенной сложности не слишком трудно, но требует больше знаний. Вы должны найти нужное руководство для каждой сложной функции. Например, для некоторых языков есть своя документация с политикой:

- Политика для Perl

- Политика для Python

- Политика для Java

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball, `hello-sh-1.0.tar.gz`, created as follows may offer a good starting point:[8]

    $ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
    $ cat > hello <<EOF
    #!/bin/sh
    # (C) 2011 Foo Bar, GPL2+
    echo "Hello!"
    EOF
    $ chmod 755 hello
    $ cd ..
    $ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

## 2.3. Получение программы и ознакомление со сборкой

Итак, первое, что вы должны сделать — найти и скачать исходный код программы. Предполагается, что вы уже взяли файл с домашней страницы автора. Исходный код программ для Unix обычно предоставляется в виде архива в формате tar+gzip с расширением `.tar.gz`, tar+bzip2 с расширением `.tar.bz2` или tar+xz с расширением `.tar.xz`. Внутри архива обычно есть каталог с именем ``пакет`-`версия``, в котором находятся все файлы исходного кода программы.

If the latest version of the source is available through a Version Control System (VCS) such as Git, Subversion, or CVS, you need to get it with `git clone`, `svn co`, or `cvs co` and repack it into tar+gzip format yourself by using the `--exclude-vcs` option.

Если исходный код выбранной программы поставляется в другом виде (например, имя файла оканчивается на `.Z` или `.zip`[9]), распакуйте его соответствующими средствами и перепакуйте его.

Если исходный код выбранной программы поставляется с содержимым, не удовлетворяющим DFSG, то вам также нужно распаковать его и удалить это содержимое и перепаковать его, добавив в версию исходного кода пометку `dfsg`.

В качестве примера взята программа gentoo — менеджер файлов, использующий GTK+ [10].

В своём домашнем каталоге создайте каталог с именем `debian`, `deb` или с любым удобным (например, в нашем случае можно было бы использовать `~/gentoo`). Поместите скачанный архив в этот каталог и распакуйте его (`tar xzf gentoo-0.9.12.tar.gz`). Убедитесь, что при этом не возникло никаких, даже, казалось бы, не относящихся к делу ошибок, так как их появление означает, что они могут возникнуть и на машинах других людей, у которых их инструменты распаковки посчитают это за реальную ошибку. В командной строке оболочки вы должны увидеть следующее:

    $ mkdir ~/gentoo ; cd ~/gentoo
    $ wget http://www.example.org/gentoo-0.9.12.tar.gz
    $ tar xvzf gentoo-0.9.12.tar.gz
    $ ls -F
    gentoo-0.9.12/
    gentoo-0.9.12.tar.gz

В результате вы получите подкаталог `gentoo-0.9.12`. Перейдите в этот каталог и внимательно прочитайте имеющуюся документацию. Обычно, полезными оказываются файлы `README*`, `INSTALL*`, `*.lsm` или `*.html`. Вы должны найти инструкции, которые позволят вам правильно скомпилировать и установить программу (скорее всего, в каталог `/usr/local/bin`; вы должны будете установить программу в другой каталог, подробнее об этом в Раздел 3.3, «Установка файлов в их каталоги назначения»).

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

## 2.4. Простые системы сборки

В простых программах обычно используется файл `Makefile` и для компиляции достаточно выполнить команду `make`[11]. Некоторые из них поддерживают команду `make check`, по которой выполняется самопроверка. Установка в каталог назначения обычно выполняется с помощью `make install`.

Теперь скомпилируйте программу и попробуйте её запустить, чтобы убедиться, что она правильно работает и что при установке и запуске ничто другое не было испорчено.

Вы также можете попытаться воспользоваться командой `make clean` (или лучше `make distclean`) для очистки каталога сборки. Иногда есть даже команда `make uninstall`, которая позволит удалить все установленные файлы.

## 2.5. Популярные переносимые системы сборки

Многие свободные программы написаны на языках C и C++. В некоторых из них для переносимости между платформами используются Autotools или CMake. Эти инструменты используются для генерации `Makefile` и других необходимых исходных файлов. Такие программы обычно собираются с помощью `make; make install`.

Autotools — это система сборки GNU, состоящая из Autoconf, Automake, Libtool и gettext. Её использование можно определить по включённым в исходный архив файлам `configure.ac`, `Makefile.am` и `Makefile.in` [12].

Первый шаг автоматизации с помощью Autotools обычно выполняет автор программы. Он запускает команду `autoreconf -i -f` в каталоге с исходным кодом и затем распространяет сгенерированные файлы вместе с исходным кодом.

    configure.ac-----+-> autoreconf -+-> configure
    Makefile.am -----+        |      +-> Makefile.in
    src/Makefile.am -+        |      +-> src/Makefile.in
                              |      +-> config.h.in
                          automake
                          aclocal
                          aclocal.m4
                          autoheader

Для правки файлов `configure.ac` и `Makefile.am` требуется знание инструментов autoconf и automake. Смотрите `info autoconf` и `info automake`.

Второй шаг автоматизации с помощью Autotools обычно выполняет пользователь. Он получает распространяемый код и запускает `./configure && make` для компиляции программы в исполняемый`двоичный файл`.

    Makefile.in -----+                +-> Makefile -----+-> make -> двоичный файл
    src/Makefile.in -+-> ./configure -+-> src/Makefile -+
    config.h.in -----+                +-> config.h -----+
                     |
      config.status -+
      config.guess --+

Вы можете изменять различные переменные в файле `Makefile`. Например каталог установки по умолчанию изменяется с помощью параметра в командной строке: `./configure --prefix=/usr`.

Хотя это не обязательно, обновление `configure` и других файлов с помощью `autoreconf -i -f` может улучшить совместимость исходного кода [13].

Альтернативной системой сборки является CMake. Её можно определить по наличию файла `CMakeLists.txt`.

## 2.6. Имя и версия пакета

Если оригинальный исходный код программы содержится в файле `gentoo-0.9.12.tar.gz`, то в качестве (исходного) имени пакета можно взять `gentoo`, а в качестве версии исходной программы — `0.9.12`. Имя и версия используются в файле `debian/changelog`, который описан далее в Раздел 4.3, «Файл `changelog`».

Although this simple approach works most of the time, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (`a-z`), digits (`0-9`), plus (`+`) and minus (`-`) signs, and periods (`.`). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing packages. It is a good idea to keep its length within 30 characters. [14]

Если для имени автор программы использовал какие-то общие слова, например `test-suite`, то лучше назначить другое имя, которое явно описывает содержимое и не засоряет пространство имён [15].

You should choose the upstream version to consist only of alphanumerics (`0-9A-Za-z`), plus signs (`+`), tildes (`~`), and periods (`.`). It must start with a digit (`0-9`). [16] It is good idea to keep its length within 8 characters if possible. [17]

If upstream does not use a normal versioning scheme such as `2.30.32` but uses some kind of date such as `11Apr29`, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the `debian/changelog` file. If you need to invent a version string, use the `YYYYMMDD` format such as `20110429` as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as `0.1` in the future, use the `0~YYMMDD` format such as `0~110429` as the upstream version.

Строки версий [18] можно сравнить с помощь dpkg(1) следующим образом:

     $ dpkg --compare-versions версия1 операция версия2

Правило сравнения версий вкратце можно описать так:

- Строки сравниваются от начала к концу.

- Буквы больше, чем цифры.

- Числа сравниваются как целые.

- Буквы сравниваются согласно порядку кодов ASCII.

- Для символов точки (`.`), плюса (`+`) и тильды (`~`) правила следующие:

  `0.0` < `0.5` < `0.10` < `0.99` < `1` < `1.0~rc1` < `1.0` < `1.0+b1` < `1.0+nmu1` < `1.1` < `2.0`

Иногда бывает, что автор выпускает предварительную версию `gentoo-0.9.12.tar.gz` с именем `gentoo-0.9.12-ReleaseCandidate-99.tar.gz`. Чтобы правильно сработало обновление пакета, вам нужно переименовать файл с исходным кодом в `gentoo-0.9.12~rc99.tar.gz`.

## 2.7. Настройка dh_make

Для указания вашего адреса электронной почты и имени, которые будут использоваться в пакетах инструментами сопровождения Debian, настройте переменные окружения `$DEBEMAIL` и `$DEBFULLNAME` [19]:

    $ cat >>~/.bashrc <<EOF
    DEBEMAIL="ваш.адрес.эл.почты@example.org"
    DEBFULLNAME="Имя Фамилия"
    export DEBEMAIL DEBFULLNAME
    EOF
    $ . ~/.bashrc

## 2.8. Начальный неродной пакет Debian

Обычно, пакеты Debian являются неродными (non-native) пакетами Debian, создаваемыми из внешнего исходного кода. Если вы хотите создать неродной пакет Debian из исходного кода `gentoo-0.9.12.tar.gz`, то можете сгенерировать начальный неродной пакет Debian с помощью команды dh_make следующим образом:

    $ cd ~/gentoo
    $ wget http://example.org/gentoo-0.9.12.tar.gz
    $ tar -xvzf gentoo-0.9.12.tar.gz
    $ cd gentoo-0.9.12
    $ dh_make -f ../gentoo-0.9.12.tar.gz

Здесь замените имя файла именем вашего архива с исходным кодом [20]. Подробней смотрите dh_make(8).

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package — it creates only one binary package, i.e., one `.deb` file — so we will select the first option (with the `s` key), check the information on the screen, and confirm by pressing ``ENTER``. [21]

После выполнения dh_make в родительском каталоге создался исходный архив tar с именем `gentoo_0.9.12.orig.tar.gz`, который в дальнейшем будет использоваться для создания неродного пакета с исходным кодом Debian с именем `debian.tar.gz`:

    $ cd ~/gentoo ; ls -F
    gentoo-0.9.12/
    gentoo-0.9.12.tar.gz
    gentoo_0.9.12.orig.tar.gz

Отметьте два ключевых момента в имени файла `gentoo_0.9.12.orig.tar.gz`:

- Имя пакета и версия разделены символом `_` (подчёркивание).

- Перед `.tar.gz` есть часть `.orig`.

Вы, наверное, уже заметили, что в исходном коде в каталоге `debian` было создано множество файлов шаблонов. Их назначение описано в Глава 4, Обязательные файлы в каталоге `debian` и Глава 5, Другие файлы в каталоге `debian/`. Как вы уже догадались, процесс пакетирования не может быть полностью автоматическим. Вам нужно изменить исходный код программы для Debian (Глава 3, Изменение исходного кода). После этого вам нужно правильно собрать пакет Debian (Глава 6, Сборка пакета), проверить его (Глава 7, Проверка пакета на наличие ошибок) и отослать в архив (Глава 9, Отправка пакета). Далее будут рассмотрены все эти шаги.

Если вы случайно стёрли какой-то файл шаблона при работе, то можете восстановить его, повторно запустив dh_make с параметром `--addmissing` в дереве исходного кода пакета Debian.

Обновлять существующий пакет сложнее, так как для его создания могли использоваться старые методы. Поэтому на время обучения пока беритесь за современные пакеты. Мы вернёмся к этому позднее в Глава 8, Обновление пакета.

Please note that the source file does not need to contain any build system discussed in Раздел 2.4, «Простые системы сборки» and Раздел 2.5, «Популярные переносимые системы сборки». It could be just a collection of graphical data, etc. Installation of files may be carried out using only `debhelper` configuration files such as `debian/install` (see Раздел 5.11, «Файл `install`»).

[4] В старом формате `1.0` для неродных пакетов Debian с исходным кодом использовалось имя ``пакет`_`версия`-`редакция`.diff.gz`.

[5] Смотрите описание полей 5.6.1 «Source», 5.6.7 «Package» и 5.6.12 «Version». Значение архитектуры пакета задаётся согласно политике Debian в разделе 5.6.8, «Architecture» и автоматически назначается в процессе сборки пакета.

[6] See Debian Developer's Reference 5.9.5 "Adopting a package".

[7] С другой стороны, всегда будут появляться новые программы, которые хотелось бы иметь в виде пакета.

[8] Не беспокойтесь об отсутствии файла `Makefile`. Вы можете установить команду hello просто с помощью debhelper, как показано в Раздел 5.11, «Файл `install`», или изменить исходный код, добавив новый `Makefile` с целью `install`, как показано в Глава 3, Изменение исходного кода.

[9] Вы можете определить формат архива с помощью команды file, если по расширению это непонятно.

[10] Для этой программы пакет уже создан. В текущей версии в качестве структуры сборки используется Autotools и, следовательно, есть различия с приводимыми примерами, которые были написаны для версии 0.9.12.

[11] Many modern programs come with a script named `configure`, which when executed creates a `Makefile` customized for your system.

[12] Autotools is too big to deal with in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and the local copy of `/usr/share/doc/autotools-dev/README.Debian.gz`, if you need to use it.

[13] Вы можете это автоматизировать с помощью пакета `dh-autoreconf`. Смотрите Раздел 4.4.3, «Доработка файла `rules`».

[14] В aptitude длина поля имени пакет по умолчанию равна 30. Длина имён более чем 90% пакетов менее 24 символов.

[15] If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issue.

[16] Это жёсткое правило должно помочь избежать путаницы в именах файлов.

[17] В aptitude длина поля версии по умолчанию равна 10. Редакция Debian с символом переноса обычно занимает 2 символа. В более 80% пакетов версия исходной программы — менее 8 символов, а редакция Debian — менее 2 символов. В более 90% пакетов версия исходной программы — менее 10 символов, а редакция Debian — менее 3 символов.

[18] Строками версий могут быть версия исходной программы (``версия``), редакция Debian (``редакция``) или версия (``версия`-`редакция``). Смотрите в Раздел 8.1, «Новая редакция Debian» как увеличивается значение редакции Debian.

[19] В примере предполагается, что в качестве регистрационной оболочки у вас используется Bash. Если вы используете другую регистрационную оболочку (например, Z shell), используйте другие соответствующие файлы настройки вместо `~/.bashrc`.

[20] If the upstream source provides the `debian` directory and its contents, run the dh_make command with the extra option `--addmissing`. The new source `3.0 (quilt)` format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream version for your Debian package.

[21] Здесь предлагается несколько вариантов: `s` — одиночный двоичный пакет, `i` — пакет, независящий от архитектуры, `m` — несколько двоичных пакетов, `l` — пакет для библиотеки, `k` — пакет для модуля ядра, `n` — пакет с заплатами к ядру и `b` — пакет, применяющий `cdbs`. В этом документе, в основном, описывается использование команды dh (из пакета `debhelper`) для создания одиночного двоичного пакета, но также затрагиваются варианты с пакетами, независящими от архитектуры, и когда из одной программы создаётся несколько двоичных пакетов. Пакет `cdbs` предоставляет инфраструктуру пакетирования альтернативную команде dh и не описан в этом документе.

Глава 1. Хорошее начало — половина дела |  | Глава 3. Изменение исходного кода