Ubuntu logo

Packaging Guide

2. Загальний огляд каталогу debian/

Ця стаття дає короткі пояснення до різних файлів, важливих для створення пакунків Ubuntu, які містяться у каталозі debian/. Найважливішими з них є changelog, control, copyright, і 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>. Якщо поле Maintainer змінено, старе значення повинне бути збережене у полі XSBC-Original-Maintainer. Це можна зробити автоматично сценарієм update-maintainer з пакунку ubuntu-dev-tools. Для подальшої інформації дивіться Debian Maintainer Field spec в Ubuntu wiki.

Кожен додатковий абзац дає опис бінарного пакунку, який буде створений.

Детальнішу інформацію можна знайти на сторінці секції control-файлу (Розділ 5) документу Debian Policy Manual.

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

Якщо Ваші tarball-файли перебувають на 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/

https://wiki.debian.org/Projects/DebSrc3.0 містить додаткову інформацію стосовно переходу на версію 3.0 формату джерельних пакунків.

Додаткову інформацію можна знайти в man dpkg-source і у Розділі source/format (Розділ 5.21) посібника Debian New Maintainers.

2.6. Додаткові ресурси

Крім Debian Policy Manual, на який посилається стаття, посібник Debian New Maintainers’ Guide містить більш детальний опис для кожного файлу. Розділ 4, “Необхідні файли у теці debian” дає опис файлів control, changelog, copyright і rules. Розділ 5, “Інші файли у теці debian” дає опис додаткових файлів, які можна використовувати.