[ назад ] [ Заметка об авторских правах ] [ Содержание ] [ вперед ]

Руководство начинающего разработчика Debian
Глава 4 Обязательные файлы в каталоге debian/


В основном каталоге программы (gentoo-0.9.12) появился новый подкаталог — debian, в котором есть несколько файлов. Эти файлы определяют поведение пакета. Наиболее важные из них — это файлы control, changelog, copyright и rules, которые обязательны для всех пакетов.


4.1 Файл control

Этот файл содержит информацию, которая используется программами dpkg и dselect (а также другими) для работы c пакетами. Вот, например, файл control, который был создан программой dh_make.

       1  Source: gentoo
       2  Section: unknown
       3  Priority: optional
       4  Maintainer: Josip Rodin <jrodin@jagor.srce.hr>
       5  Standards-Version: 3.0.1
       6
       7  Package: gentoo
       8  Architecture: any
       9  Depends: ${shlibs:Depends}
      10  Description: <insert up to 60 chars description>
      11  <insert long description, indented with spaces>

(номера строк добавлены)

Строки 1-5 представляют собой управляющую информацию для пакета, содержащего исходные тексты, где строка 1 — его название.

Строка 2 — это название раздела, к которому относится данный пакет. Как, возможно, вы уже заметили, Debian разбит на несколько разделов: раздел main (основной) содержит свободное программное обеспечение, non-free (не-свободное) содержит пакеты, которые не совсем отвечают определению свободного программного обеспечения, и contib, где находятся пакеты, которые, являясь свободным программным обеспечением, зависят от не-свободного программного обесепеченя. В каждом разделе существуют логические подразделы, определяющие что пакет из данного подраздела делает. Таким образом, существует раздел ‘admin’, где находятся программы для администрирования системы, раздел ‘base’ — для основных пакетов, раздел ‘devel’ содержит инструменты разработки программного обеспечения, ‘doc’ — документацию, ‘libs’ — библиотеки, ‘mail’ — почтовых сервером и программ чтения почты, ‘net’ — для сетевых приложений, ‘x11’ — программ, работающих под X Window System, и много много других.

В нашем случае мы должны указать ‘x11’.

В строке 3 мы должны указать, насколько важен данный пакет. Значения полей Section и Priority пока используется только программой dselect, которая позволяет пользователю сортировать по значениям этих полей, они также могут (и, скорее всего, будут) замещены сопровождающими ftp-сервер. Документ «Policy Manual» подробно описывает, чем нужно руководствоваться при выборе значений для этих полей.

В нашем случае мы оставим значение этого поля равным ‘optional’.

В строке 4 указано имя и адрес разработчика пакета.

Строка 5 — это версия документа «Debian Policy», стандартам которого следует данный пакет (две основные версии пакета debian-policy).

Если для построения программы используется нестандартный компилятор или какие-нибудь дополнительные утилиты, вы должны перечислить их в специальной записи ‘Build-Depends’. Дополнительная информация может быть найдена в «Руководстве по созданию пакетов» (раздел 8.7) и в документации, прилагаемой к пакету build-essential.

В строке 7 указано имя двоичного пакета.

В строке 8 указана архитектура процессора, для которого может быть скомпилирован двоичный пакет. Мы можем оставить в качестве значения ‘any’, так как программа dpkg-gencontrol(1) поместит в это поле значение, соответствующее процессору машины, на которой компилировался пакет (см. в «Руководстве разработчика» объяснение понятия ‘перенос пакета’). Если ваш пакет не зависит от архитектуры процессора (например, сценарий на языке Perl или же документ), измените значение этого поля на ‘all’ и прочитайте раздел Файл rules, раздел 4.4, который описывает цель ‘binary-indep’, используемую при построении пакета.

Одна из самых полезных возможностей системы управления пакетами Debian приведена в строке 9. Пакеты могут зависеть друг от друга различным образом. Помимо зависимости Depends, существуют также зависимости Recommends, Suggests, Pre-Depends, Conflicts, Provides, и Replaces .

Программы управления пакетами (такие как dpkg, dselect или apt) обычно одинаковым образом обрабатывают эти зависимости. Мы попытались дать объяснение тем случаям, когда поведение различается. (см. dpkg(8), dselect(8), apt(8), console-apt(8), gnome-apt(8))

Ниже приведено описание того, что означает каждый тип зависимости:

Depends
Данный пакет не может быть установлен, если пакеты, указанные в списке зависимостей Depends, также не установлены. Используйте этот тип зависимости, если ваша программа гарантировано не будет работать (или вызовет какие-нибудь серьезные проблемы), если соответствующий пакет не установлен.

Recommends
Программа dselect не установит ваш пакет, если пакеты, указанные в списке зависимостей Recommends, не установлены. Однако программы dpkg и apt-get должны позволить сделать это. Используйте данный тип зависимостей для пакетов, которые бы не использовались вместе с вашим пакетом только в нестандартных случаях.

Suggests
Когда пользователь устанавливает ваш пакет, программа dselect предложит ему также установить пакеты, перечисленные в списке зависимостей Suggests. Программы dpkg и apt этого делать не будут. Используйте данный тип зависимостей для пакетов, которые могут расширить функциональность вашего пакета, и, таким образом, увеличить его полезность.

Pre-Depends
Данный тип зависимостей строже, чем зависимости типа Depends. Данный пакет не будет установлен, если пакеты, указанные в списке зависимостей Pre-Depends, уже не установлены или не настроены. Используйте этот тип зависимостей очень скупо и только после обсуждения в списке рассылки debian-devel. Другими словами, не используйте его никогда! :-)

Conflicts
Данный пакет не будет установлен пока пакеты, перечисленные в списке зависимостей Conflicts, не удалены из системы. Используйте этот тип зависимостей, если ваша программа гарантировано не будет работать (или же может вызвать серьезные повреждения системы), если присутвует какой-нибудь определенный пакет.

Provides
В случае, когда для какого-то типа пакетов существуют несколько альтернатив, вводятся так называемый виртуальные пакеты. Полный список виртуальных пакетов приведен в файле /usr/share/doc/debian-policy/virtual-package-names-list.text.gz. Вы должны использовать данный тип зависимостей, если ваша программа реализует функциональность существующего виртуального пакета.

Replaces
Используйте данный тип зависимостей в случае, когда ваш пакет заменяет файлы из другого пакета, или же полностью заменяет другой пакет (в этом случае, вы также должны использовать зависимость типа Conflicts:). Тогда файлы из указанного пакета будут удалены перед установкой вашего.

Формат этих полей одинаков: это список имен пакетов, разделенных запятой. Здесь также могут быть указаны списки имен альтернативных пакетов, разделенных вертикальной чертой |. Для каждого пакета в списке вы можете ограничить допустимость указанного пакета по версии. Версии указываются в круглых скобках после имени пакета и должны состоять из символа сравнения, за которым следует номер версии. Допустимыми символами сравнения являются: <<, <=, =, >=, и >> для “строго раньше чем”, “раньше или равно”, “в точности равно”, “равно или позже” и “строго позже чем” соответственно.

Последнее, что мы хотели бы здесь показать, это $(shlibs:Depends). Данная конструкция позволяет программе dh_gencontrol(1) заполнить данное поле названиями пакетов разделяемых библиотек — например, libc6 или xlib6g — которыми пользуется ваша программа (список библиотек позволяет получить программа dh_shlibdeps(1)). Таким образом, вы можете их не указывать. В нашем случае, мы оставляем строку 9 так как она есть.

Мы добавим строчку (которая станет строкой номер 10) со списком зависимостей типа Suggests. Здесь мы (пока только) укажем пакет file так как программа gentoo может использовать некоторые из возможностей предоставляемых данным пакетом/программой.

Строка 11 — это короткое описание. У большинства людей ширина экрана составляет 80 колонок, поэтому мы рекомендуем вам не превышать этот предел. Здесь мы напишем “A fully GUI configurable GTK+ file manager”.

В строке 12 мы укажем длинное (более полное) описание пакета. В первой колонке должен быть пробел. Пустых строк не должно быть. Если вам необходимо поместить в описание пустую строку, поместите после пробела (!) символ ‘.’ (точка). После описания не должно быть больше одной пустой строки.

Вот обновленный файл control:

       1  Source: gentoo
       2  Section: x11
       3  Priority: optional
       4  Maintainer: Josip Rodin <jrodin@jagor.srce.hr>
       5  Standards-Version: 3.0.1
       6
       7  Package: gentoo
       8  Architecture: any
       9  Depends: ${shlibs:Depends}
      10  Suggests: file
      11  Description: A fully GUI configurable GTK+ file manager
      12   gentoo is a file manager for Linux written from scratch in pure C. It
      13   uses the GTK+ toolkit for all of its interface needs. gentoo provides
      14   100% GUI configurability; no need to edit config files by hand and re-
      15   start the program. gentoo supports identifying the type of various
      16   files (using extension, regular expressions, or the 'file' command),
      17   and can display files of different types with different colors and icons.
      18   .
      19   gentoo borrows some of its look and feel from the classic Amiga file
      20   manager "Directory OPUS" (written by Jonathan Potter).

(номера строк добавлены)


4.2 Файл copyright

Этот файл содержит информацию о местнонахождении исходной программы и авторских правах и лицензионное соглашение. Документ «Политика Debian» диктует не формат этого файла, но его содержание (см. раздел 6.5). Вот как выглядит файл, созданный программой dh_make:

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from <fill in ftp site>
       5
       6  Upstream Author(s): <put author(s) name and email here>
       7
       8  Copyright:
       9
      10  <Must follow here>

(номера строк добавлены)

В этот файл необходимо добавить: место (ftp- или web-сервер), где вы взяли исходные пакет; информацию об авторских правах и лицензионную информацию. Если лицензионное соглашение — это одно из популярных “свободных” лицензий (например, GNU GPL, GNU LGPL, BSD или Artistic), вы можете просто сослаться на соответствующий файл в существующем в каждой системе Debian каталоге /usr/share/common-licenses/, в противном случае вы должны его включить полностью. Программа gentoo лицензирована в соответствии с GNU General Public License, поэтому измененный файл copyright будет выглядеть таким образом:

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
       5
       6  Upstream author: Emil Brink <emil@obsession.se>
       7
       8  This software is copyright (c) 1998-99 by Emil Brink, Obsession
       9  Development.
      10 
      11  You are free to distribute this software under the terms of
      12  the GNU General Public License.
      13  On Debian systems, the complete text of the GNU General Public
      14  License can be found in /usr/share/common-licenses/GPL file.

(номера строк добавлены)


4.3 Файл changelog

Это обязательный файл, имеющий специальный формат (описан в «Руководстве по созданию пакетов» (раздел 3.2.3)). Этот файл используется программой dpkg и другими для получения информации о версии, ревизии, разделе, и срочности для вашего пакета.

Он также важен и для вас, так как регистрировать все изменения очень помогает в последствии. Он также поможет людям, загрузившим ваш пакет, сразу понять, что именно изменилось в вашем пакете. После установки пакета, этот файл будет доступен как /usr/share/doc/gentoo/changelog.Debian.gz.

Программа dh_make создала такой файл:

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       6
       7  Local variables:
       8  mode: debian-changelog
       9  End:

(номера строк добавлены)

В первой строке указаны название пакета, версия программы, ревизия пакета, раздел, и срочность. Имя должно совпадать с названием пакета с исходными текстами. Раздел должен быть ‘unstable’ (нестабильный) или ‘experimental’ (экспериментальный). Срочность не должна заменяться на что-либо большее, чем ‘low’ (низкая). :-)

Строки 3-5 суть запись в журнале, это то, где вы регистрируете все сделанные над пакетом изменения (это не изменения сделанные авторами программы — для регистрации этих изменений используется отдельный файл, созданный авторами программы, и который устанавливается как /usr/share/doc/gentoo/changelog.gz). Новые строки должны включаться перед строкой, которая начинается с символа звездочка (‘*’). Программа dch(1) упростит вам работу, вы также можете использовать программу emacs(1) (строки 7-9 содержат информацию специально для нее). Либо вы можете воспользоваться любым текстовым редактором. В результате у вас должно получиться что-то подобное:

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4   * This is my first Debian package.
       5   * Adjusted the Makefile to fix $DESTDIR problems.
       6
       7  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       8
       9  Local variables:
      10   mode: debian-changelog
      11  End:

(номера строк добавлены)

Когда вы выпускаете новую версию пакета, вы должны увеличить номер версии пакета. Вы можете сделать это с помощью команды ‘dch -i’ или, если вам необходимо явно указать новую версию, при помощи команды ‘dch -v версия-ревизия’, а затем добавить комментарии при помощи вашего любимого текстового редактора. Совет: как получить дату в необходимом формате? Используйте команду ‘822-date’ или команду ‘date -R’

Информация о новой версии добавляется в начало файла changelog. Вот как может выглядеть этот файл после изменений:

       1  gentoo (0.9.12-2) unstable; urgency=low
       2
       3   * Fixed a glitch in the menu file.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 22:15:39 +0100
       6
       7  gentoo (0.9.12-1) unstable; urgency=low
       8
       9   * Initial Release.
      10   * This is my first Debian package.
      11   * Adjusted the Makefile to fix $DESTDIR problems.
      12 
      13  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
      14 
      15  Local variables:
      16  mode: debian-changelog
      17  End:

(номера строк добавлены)

Более подробную информацию о версия/обновлениях пакетов, вы можете найти в Обновление пакета, раздел 6.4.


4.4 Файл rules

Теперь вернемся в каталог debian и взглянем на файл rules, который используется программой dpkg-buildpackage(1) для создания пакета. Обычно это просто еще один управляющий файл для программы make. Только он отличается от того, что предлагается вместе с исходными текстами.

Каждый файл rules, как и любой другой Makefile, содержит правила, определяющие как необходимо выполнять те или иные действия. Правила состоят из имени цели, имен файлов, и названий действий, которые необходимо выполнить (например, ‘build:’ или ‘install:’). Правила, которые вы хотите выполнить, должны быть указаны в командной строке (например, ‘debian/rules build’ или ‘make -f debian/rules install’). После имени цели вы можете указать имя другой цели, название программы или файла, от которых зависит данная цель. Затем вы можете указать произвольной количество команд (первым символом в строке с командой должен быть символ табуляции!), пустая строка завершает правило[5] Комментарии начинаются с символа диеза (‘#’) и идут до конца строки. Вы можете обращаться к правилам либо из других правил, либо из командной строки ‘debian/rules clean’).

Возможное недопонимание должно уйти, после того, как вы посмотрите на содержимое файла rules, который был создан программой dh_make. Вы также должны прочитать документацию к программе make.

Самое главное, что вы должны помнить о файле rules, созданном программой dh_make, это то, что этот файл представляет собой рекомендацию. Он будет работать для простых пакетов, но для более сложных вам, скорее всего, понадобится что-то добавить или удалить. Единственное, что вы не должны менять, это имена правил, так как все инструменты используют эти имена в соответствии с «Руководством по созданию пакетов».

       1  #!/usr/bin/make -f
       2  # Made with the aid of dh_make, by Craig Small
       3  # Sample debian/rules that uses debhelper. GNU copyright 1997 by Joey Hess.
       4  # Some lines taken from debmake, by Christoph Lameter.
       5
       6  # Uncomment this to turn on verbose mode.
       7  #export DH_VERBOSE=1
       8
       9  # This is the debhelper compatability version to use.
      10  export DH_COMPAT=1
      11 
      12  build: build-stamp
      13  build-stamp:
      14 	dh_testdir
      15 
      16 	# Add here commands to compile the package.
      17 	$(MAKE)
      18 
      19 	touch build-stamp
      20 
      21  clean:
      22 	dh_testdir
      23 	dh_testroot
      24 	rm -f build-stamp
      25 
      26 	# Add here commands to clean up after the build process.
      27 	-$(MAKE) clean
      28 
      29 	dh_clean
      30 
      31  install: build-stamp
      32 	dh_testdir
      33 	dh_testroot
      34 	dh_clean -k
      35 	dh_installdirs
      36 
      37 	# Add here commands to install the package into debian/tmp.
      38 	$(MAKE) install DESTDIR=`pwd`/debian/tmp
      39 
      40  # Build architecture-independent files here.
      41  binary-indep: build install
      42  # We have nothing to do by default.
      43 
      44  # Build architecture-dependent files here.
      45  binary-arch: build install
      46  #	dh_testversion
      47 	dh_testdir
      48 	dh_testroot
      49  #	dh_installdebconf
      50 	dh_installdocs
      51 	dh_installexamples
      52 	dh_installmenu
      53  #	dh_installemacsen
      54  #	dh_installpam
      55  #	dh_installinit
      56 	dh_installcron
      57 	dh_installmanpages
      58 	dh_installinfo
      59  #	dh_undocumented
      60 	dh_installchangelogs
      61 	dh_link
      62 	dh_strip
      63 	dh_compress
      64 	dh_fixperms
      65 	# You may want to make some executables suid here.
      66 	dh_suidregister
      67  #	dh_makeshlibs
      68 	dh_installdeb
      69  #	dh_perl
      70 	dh_shlibdeps
      71 	dh_gencontrol
      72 	dh_md5sums
      73 	dh_builddeb
      74 
      75  binary: binary-indep binary-arch
      76  .PHONY: build clean binary-indep binary-arch binary install

(номера строк добавлены)

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

Строки с 12-й по 19-ую описывают правило ‘build’ (и подчиненной правило ‘build-stamp’), которое выполняет Makefile, идущий вместе с программой, и который позволяет скомпилировать программу.

Правило ‘clean’, описанное в строках 21-29, удаляет все автоматически созданные файлы. Это правило должно успешно выполняться всегда (даже, если файлов, которые нужно было бы удалять, нет). Поэтому используйте форсирующие параметры (например, для программы rm это ‘-f’) и игнорируйте результат выполнения команды (для этого поместите ‘-’ перед ее названием).

Процесс установки — правило ‘install’ — начинается в строке 31. Основное, что оно выполняет, это цель ‘install’ из файла исходного файла Makefile — установка происходит в каталог debian/tmp — вот зачем мы использовали переменную $(DESTDIR) для указания корневого каталога при установке программы.

Как указано в комментарии, правило ‘binary-indep’ в строках 41-43 используется для построения платформо-независимых пакетов, но в нашем примере такие отстутвуют. Если у вашего пакета в файле debian/control написано ‘Architecture: all’, то все команды для создания пакета вы должны поместить сюда, а правило ‘binary-arch’ должно быть пустым.

Следующее правило — ‘binary-arch’ (строки 45-73) — использует несколько небольших утилит из пакета debhelper, которые выполняют действия, необходимые для того, чтобы ваш пакет удовлетворял требованиям Debian.

Названия команд начинаются с dh_, здесь мы приводим список команд и описание того, что они делают:

dh_testdir(1)
проверяет, что вы находитесь в правильном каталоге (/usr/local/gentoo/gentoo-0.9.12/);

dh_testroot(1)
проверяет, что вы обладаете необходимыми привилегиями (пользователя root);

dh_installmanpages(1)
копирует страницы руководства;

dh_strip(1)
удаляет отладочную информацию из исполняемых файлов, что позволяет сделать их меньше;

dh_compress(1)
сжимает страницы Руководства и файлы документации программой gzip, если размер соответствующего файла превышает 4 Кбайт;

dh_installdeb(1)
копирует управляющие файлы пакета в каталог debian/tmp/DEBIAN;

dh_shlibdeps(1)
определяет зависимости для исполняемых файлов;

dh_gencontrol(1)
создает и устанавливает файл control;

dh_md5sums(1)
вычисляет MD5-суммы для всех файлов в пакете;

Для подробной информации о том, что делает и какие параметры допустимы для каждого из этих dh_* сценариев, мы рекомендуем вам прочитать соответствующие страницы Руководства. Мы упомянули не все сценарии из семейста dh_*, их описание вы можете найти в документации к пакету debhelper.

Раздел ‘binary-arch’ — это то место, где вы должны закомментировать все те строки, отвечающие за дополнительные возможности, в которых вы не нуждаетесь. Например, для пакета gentoo были закомментированы строки со словами testversion, emacsen, pam, init, cron, manpages, info, undocumented, suidregister, makeshlibs, и perl. Это было сделано просто потому, что пакет gentoo в этом не нуждается. А в строке 60 было необходимо добавить ‘ FIXED’, так как это имя файла журнала изменений исходной программы.

Две последние строки (как все другие строки, для которых у нас не нашлось комментариев) представляют собой более или менее обязательные вещи, о которых вы можете прочитать в руководстве к программе make и «Руководстве по созданию пакетов». Пока вы можете считать, что они недостаточно важны, чтобы о них знать.


[ назад ] [ Заметка об авторских правах ] [ Содержание ] [ вперед ]
Руководство начинающего разработчика Debian
версия 1.0 от 27 сентября 1999 года.
Josip Rodin jrodin@jagor.srce.hr
Перевод: Михаил Соболев, mss@transas.com
Перевод: Алексей Выскубов, alexey@pepper.spb.ru