| Глава 6. Basics for packaging | ||
|---|---|---|
 |
 |
|
| Глава 6. Basics for packaging | ||
|---|---|---|
| |
|
|
Содержание
Here, a broad overview is presented without using VCS operations for the basic rules of Debian packaging focusing on the non-native Debian package in the «3.0 (quilt)» format.
![[Примечание]](images/note.png) | Примечание |
|---|---|
|
Для ясности в дайльнейшем были умышленно опущены некоторые детали. Ознакомьтесь со страницами руководства dpkg-source(1), dpkg-buildpackage(1), dpkg(1), dpkg-deb(1), deb(5) и др. |
Пакет Debian с исходным кодом является набором входных файлов, используемых для сборки двоичного пакета Debian, и не представляет собой только один файл.
The Debian binary package is a special archive file which holds a set of installable binary data with its associated information.
Один пакет Debian с исходным кодом может использоваться для создания нескольких двоичных пакетов Debian, определяемых в файле debian/control.
The non-native Debian package in the Debian source format «3.0 (quilt)» is the most normal Debian source package format.
| Примечание |
|---|---|
|
Сущесвтует множество обёрточных сценариев. Используйте их для упрощения вашей работы, но обязательно разберитесь с основами их внутреннего устройства. |
The Debian packaging workflow to create a Debian binary package involves generating several specifically named files (see «Раздел 6.3, «Имя пакета и версия»») as defined in the «Debian Policy Manual». This workflow can be summarized in 10 steps with some over simplification as follows.
Архив основной ветки разработки копируется (или создаётся символьная ссылка на него) в файл со специальным именем имяпакета_версия.orig.tar.gz.
К исходному коду основной ветки разработки в каталог пакет-версия/debian/ добавляются файлы спецификации пакета Debian.
Обязательные файлы спецификации в каталоге debian/*:
The debmake command invoked in the package-version/ directory may be used to provide the initial template of these configuration files.
The dpkg-buildpackage command (usually from its wrapper debuild or sbuild) is invoked in the package-version/ directory to make the Debian source and binary packages by invoking the debian/rules script.
Create the Debian source package in the Debian source format «3.0 (quilt)» using dpkg-source(1)
Build the source using «debian/rules build» into $(DESTDIR)
Создание двоичного пакета Debian с помощью dpkg-deb(1), dpkg-genbuildinfo(1) и dpkg-genchanges(1).
Проверка качества пакета Debian с помощью команды lintian. (рекомендуется)
Follow the rejection guidelines from ftp-master.
Sign the Debian package file with the debsign command using your private GPG key.
Upload the set of the Debian package files with the dput command to the Debian archive.
Test building and confirming of the binary package goodness as above is the moral obligation as a diligent Debian developer but there is no physical barrier for people to skip such operations at this moment for the source-only upload.
Теперь замените каждую часть имени файла.
See also «Source-only uploads».
![[Подсказка]](images/tip.png) | Подсказка |
|---|---|
|
Использется множество различных стратегий по управлению заплатами и использованию систем управления версиями. Вам не следует использовать все из них. |
| Подсказка |
|---|---|
|
There is very extensive documentation in «Chapter 6. Best Packaging Practices» in the «Debian Developer’s Reference». Please read it. |
Although a Debian package can be made by writing a debian/rules script without using the debhelper package, it is impractical to do so. There are too many modern «Debian Policy» required features to be addressed, such as application of the proper file permissions, use of the proper architecture dependent library installation path, insertion of the installation hook scripts, generation of the debug symbol package, generation of package dependency information, generation of the package information files, application of the proper timestamp for reproducible build, etc.
Debhelper package provides a set of useful scripts in order to simplify Debian’s packaging workflow and reduce the burden of package maintainers. When properly used, they will help packagers handle and implement «Debian Policy» required features automatically.
Процедура создания пакета Debian в современном стиле может быть организована в виде набора простых модульных действий:
You should almost always use debhelper as your package’s build dependency. This document also assumes that you are using a fairly contemporary version of debhelper to handle packaging works in the following contents.
| Примечание |
|---|---|
|
For debhelper «compat >= 9», the dh command exports compiler flags (CFLAGS, CXXFLAGS, FFLAGS, CPPFLAGS and LDFLAGS) with values as returned by dpkg-buildflags if they are not set previously. (The dh command calls set_buildflags defined in the Debian::Debhelper::Dh_Lib module.) |
| Примечание |
|---|---|
|
debhelper(1) changes its behavior with time. Please make sure to read debhelper-compat-upgrade-checklist(7) to understand the situation. |
Если исходный код основной ветки разработки поставляется в виде архива hello-0.9.12.tar.gz, можно использовать hello в качестве имени пакета с исходным кодом основной ветки разработки, а 0.9.12 — в качестве версии основной ветки.
There are some limitations for what characters may be used as a part of the Debian package. The most notable limitation is the prohibition of uppercase letters in the package name. Here is a summary as a set of regular expressions:
[-+.a-z0-9]{2,}
[-+.a-z0-9]{2,}
[0-9][-+.:~a-z0-9A-Z]*
[0-9][+.~a-z0-9A-Z]*
See the exact definition in «Chapter 5 - Control files and their fields» in the «Debian Policy Manual».
Вам следует соответствующим образом изменить имя пакета и версию основной ветки разработки для создания пакета Debian.
Для того, чтобы информация об имени пакета и номере версии эффективно обрабатывались такими популярными инструментами как команда aptitude, рекомендуется, чтобы длина имени пакета была равна 30 символам или была меньше; а общая длина версии и редакции была равна 14 символам или меньше. [12]
Для того, чтобы не возникали конфликты, видимое пользователю имя двоичного пакета не следует выбирать из числа распространённых слов.
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 the dpkg command interprets later versions correctly as upgrades. If you need to ensure a smooth transition to a normal version scheme such as 0.1 in the future, use the 0~YYMMDD format such as 0~110429 as upstream version, instead.
Строки версий можно сравнивать друг с другом с помощью команды dpkg следующим образом.
$ dpkg --compare-versions ver1 op ver2
Правило сравнения версий может быть представлены следующим образом:
Также имеются специальные правила для символов точки (.), плюса (+) и тильды (~). Они показаны ниже.
0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0
Один сложный случай возникает тогда, когда разработчики основной ветки выпускают hello-0.9.12-ReleaseCandidate-99.tar.gz как предварительный выпуск для hello-0.9.12.tar.gz. Вам следует гарантировать, что обновление пакета Debian будет происходить правильно, переименовав для этого архив с исходным кодом основной ветки в hello-0.9.12~rc99.tar.gz.
The non-native Debian package in the Debian source format «3.0 (quilt)» is the most normal Debian source package format. The debian/source/format file should have «3.0 (quilt)» in it as described in dpkg-source(1). The above workflow and the following packaging examples always use this format.
A native Debian package is the rare Debian binary package format. It may be used only when the package is useful and valuable only for Debian. Thus, its use is generally discouraged.
![[Внимание]](images/caution.png) | Внимание |
|---|---|
|
A native Debian package is often accidentally built when its upstream tarball is not accessible from the dpkg-buildpackage command with its correct name package_version.orig.tar.gz . This is a typical newbie mistake caused by making a symlink name with «-» instead of the correct one with «_». |
A native Debian package has no separation between the upstream code and the Debian changes and consists only of the following:
If you need to create a native Debian package, create it in the Debian source format «3.0 (native)» using dpkg-source(1).
| Подсказка |
|---|---|
|
There is no need to create the tarball in advance if the native Debian package format is used. The debian/source/format file should have «3.0 (native)» in it as described in dpkg-source(1) and The debian/source/format file should have the version without the Debian revision (1.0 instead of 1.0-1). Then, the tarball containing is generated when «dpkg-source -b» is invoked in the source tree. |
The debian/rules file is the executable script which re-targets the upstream build system to install files in the $(DESTDIR) and creates the archive file of the generated files as the deb file. The deb file is used for the binary distribution and installed to the system using the dpkg command.
The Debian policy compliant debian/rules file supporting all the required targets can be written as simple as [13]:
Простой файл debian/rules:
#!/usr/bin/make -f #export DH_VERBOSE = 1 %: dh $@
The dh command functions as the sequencer to call all required «dh target» commands at the right moment. [14]
Here, $(DESTDIR) path depends on the build type.
See «Раздел 8.2, «Customized debian/rules»» and «Раздел 8.3, «Variables for debian/rules»» for customization.
| Подсказка |
|---|---|
|
Setting «export DH_VERBOSE = 1» outputs every command that modifies files on the build system. Also it enables verbose build logs for some build systems. |
The debian/control file consists of blocks of meta data separated by a blank line. Each block of meta data defines the following in this order:
See «Chapter 5 - Control files and their fields» of the «Debian Policy Manual» for the definition of each meta data.
| Примечание |
|---|---|
|
The debmake command sets the debian/control file with «Build-Depends: debhelper-compat (= 13)» to set the debhelper compatibility level. |
| Подсказка |
|---|---|
|
If an existing package has lower than debhelper compatibility level 13, probably it’s time to update its packaging. |
The debian/changelog file records the Debian package history.
The changes need to be documented in the specific, formal, and concise style.
Even if you are uploading your package by yourself, you must document all non-trivial user-visible changes such as:
If you are asking your sponsor to upload it, you should document changes more comprehensively, including all packaging related ones, to help reviewing your package.
After finishing your packaging and verifying its quality, please execute the «dch -r» command and save the finalized debian/changelog file with the suite normally set to unstable. [16] If you are packaging for backports, security updates, LTS, etc., please use the appropriate distribution names instead.
Команда debmake создаёт изначальный шаблонный файл с версией основной ветки и редакцией Debian. С целью предотвращения случайной загрузки в архив Debian выбирается выпуск UNRELEASED.
| Подсказка |
|---|---|
|
The date string used in the debian/changelog file can be manually generated by the «LC_ALL=C date -R» command. |
| Подсказка |
|---|---|
|
Когда вы экспериментируете, то используйте запись debian/changelog со строкой версии вида 1.0.1-1~rc1. Затем сведите такие записи журнала изменений в одну запись для официального пакета. |
The debian/changelog file is installed in the /usr/share/doc/binarypackage directory as changelog.Debian.gz by the dh_installchangelogs command.
Журнал изменений основной ветки устанавливается в каталог /usr/share/doc/двоичныйпакет под именем changelog.gz.
The upstream changelog is automatically found by the dh_installchangelogs using the case insensitive match of its file name to changelog, changes, changelog.txt, changes.txt, history, history.txt, or changelog.md and searched in the ./ doc/ or docs/ directories.
Debian takes the copyright and license matters very seriously. The «Debian Policy Manual» enforces having a summary of them in the debian/copyright file in the package.
The debmake command creates the initial debian/copyright template file.
Если команде debmake не была передана опция -P, то команда пропускает создаваемые автоматически файлы под разрешительными лицензиями.
| Внимание |
|---|---|
|
Файл debian/copyright должен быть отсортирован таким образом, что наиболее общие шаблоны файлов были размещены в начале списка. См. «Раздел 15.6, «debmake -k»». |
| Примечание |
|---|---|
|
Если при проверке лицензионной информации вы обнаружите какие-либо проблемы, то отправьте сообщение об ошибке в пакете debmake с проблемной частью текста, содержащего информацию об авторском праве и лицензии. |
As demonstrated in «Раздел 5.9, «Step 3 (alternatives): Modification to the upstream source»», the debian/patches/ directory holds
See how these files are used in:
| Примечание |
|---|---|
|
Header texts of these patches should conform to «DEP-3». |
| Примечание |
|---|---|
|
If you want to use VCS tools such as git, gbp and dgit to create and manage these patches after learning basics here, please refer to later in «Глава 10, Packaging with git». |
The «dpkg-source --commit» command functions like dquilt but has one advantage over the dquilt command. While the dquilt command can’t handle modified binary files, the «dpkg-source --commit» command detects modified binary files and lists them in the debian/source/include-binaries file to include them in the Debian tarball as a part of the Debian source package.
The uscan(1) command downloads the latest upstream version using the debian/watch file. E.g.:
Basic debian/watch file:
version=4 https://ftp.gnu.org/gnu/hello/ @PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
The uscan command may verify the authenticity of the upstream tarball with optional configuration (see «Раздел 6.12, «debian/upstream/signing-key.asc file»»).
See uscan(1), «Раздел 8.4, «Новый выпуск основной ветки»», «Раздел 7.1, «Fix with Files-Excluded»», and «Раздел 10.10, «Manage patch queue with gbp-pq»» for more.
Some packages are signed by a GPG key and their authenticity can be verified using their public GPG key.
For example, «GNU hello» can be downloaded via HTTP from https://ftp.gnu.org/gnu/hello/ . There are sets of files:
Выберем самую последнюю версию.
Download the upstream tarball and its signature.
$ wget https://ftp.gnu.org/gnu/hello/hello-2.9.tar.gz ... $ wget https://ftp.gnu.org/gnu/hello/hello-2.9.tar.gz.sig ... $ gpg --verify hello-2.9.tar.gz.sig gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00 gpg: Can't check signature: public key not found
If you know the public GPG key of the upstream maintainer from the mailing list, use it as the debian/upstream/signing-key.asc file. Otherwise, use the hkp keyserver and check it via your web of trust.
Download public GPG key for the upstream.
$ gpg --keyserver hkp://keys.gnupg.net --recv-key 80EE4A00 gpg: requesting key 80EE4A00 from hkp server keys.gnupg.net gpg: key 80EE4A00: public key "Reuben Thomas <[email protected]>" imported gpg: no ultimately trusted keys found gpg: Total number processed: 1 gpg: imported: 1 $ gpg --verify hello-2.9.tar.gz.sig gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00 gpg: Good signature from "Reuben Thomas <[email protected]>" ... Primary key fingerprint: 9297 8852 A62F A5E2 85B2 A174 6808 9F73 80EE 4A00
| Подсказка |
|---|---|
|
If your network environment blocks access to the HKP port 11371, use «hkp://keyserver.ubuntu.com:80» instead. |
After confirming the key ID 80EE4A00 is a trustworthy one, download its public key into the debian/upstream/signing-key.asc file.
Set public GPG key to debian/upstream/signing-key.asc.
$ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.asc
With the above debian/upstream/signing-key.asc file and the following debian/watch file, the uscan command can verify the authenticity of the upstream tarball after its download. E.g.:
Improved debian/watch file with GPG support:
version=4 opts="pgpsigurlmangle=s/$/.sig/" \ https://ftp.gnu.org/gnu/hello/ @PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Install Salsa CI configuration file. See «Раздел 10.3, «Salsa CI service»».
В каталог debian/ можно добавить дополнительные файлы настройки. Большинство из них используются для управления командами dh_*, предоставляемыми пакетом debhelper, но также имеются дополнительные файлы для команд dpkg-source, lintian и gbp.
| Подсказка |
|---|---|
|
Even an upstream source without its build system can be packaged just by using these files. See «Раздел 13.2, «Без Makefile (командная оболочка, интерфейс командной оболочки)»» as an example. |
The alphabetical list of notable optional debian/binarypackage.* configuration files listed below provides very powerful means to set the installation path of files. Please note:
Копируйте шаблонные файлы настроек по необходимости в файлы с соответствующими именами двоичных пакетов.
List bash completion scripts to be installed.
The bash-completion package is required for both build and user environments.
См. dh_bash-completion(1).
List files that should be removed but are not cleaned by the dh_auto_clean command.
См. dh_auto_clean(1) и dh_clean(1).
Set the debhelper compatibility level. (deprecated)
Use «Build-Depends: debhelper-compat (= 13)» in debian/control to specify the compatibility level and remove debian/compat.
See «COMPATIBILITY LEVELS» in debhelper(7).
This optional file is installed into the DEBIAN directory within the binary package while supplimenting it with all the conffiles auto-detected by debhelper.
This file is primarily useful for using "special" entries such as the remove-on-upgrade feature from dpkg(1).
If the program you’re packaging requires every user to modify the configuration files in the /etc directory, there are two popular ways to arrange for them not to be conffiles, keeping the dpkg command happy and quiet.
См. dh_installdeb(1).
Устанавливается в файл etc/cron/hourly/двоичныйпакет в двоичныйпакет.
См. dh_installcron(1) и cron(8).
Устанавливается в файл etc/cron/daily/двоичныйпакет в двоичныйпакет.
См. dh_installcron(1) и cron(8).
Устанавливается в файл etc/cron/weekly/двоичныйпакет в двоичныйпакет.
См. dh_installcron(1) и cron(8).
Installed into the *etc/cron/monthly/*binarypackage file in binarypackage.
См. dh_installcron(1) и cron(8).
Устанавливается в файл etc/cron.d/двоичныйпакет в двоичныйпакет.
См. dh_installcron(1), cron(8) и crontab(5).
Если такой файл существует, то он устанавливается в etc/default/двоичныйпакет в двоичныйпакет.
См. dh_installinit(1).
Содержит список каталогов, которые должны быть созданы в двоичныйпакет.
См. dh_installdirs(1).
Это это не требуется, поскольку все команды dh_install* автоматически создают необходимые каталоги. Используйте этот файл только в том случае, если у вас возникают какие-либо затруднения.
Устанавливается как управляющий файл doc-base в двоичныйпакет.
See dh_installdocs(1) and «Debian doc-base Manual (doc-base.html)» provided by the doc-base package.
Создержит список файлов документации для их установки в двоичныйпакет.
См. dh_installdocs(1).
Устанавливается в usr/lib/emacsen-common/packages/compat/двоичныйпакет в binarypackage.
См. dh_installemacsen(1).
Устанавливается в usr/lib/emacsen-common/packages/install/двоичныйпакет в двоичныйпакет.
См. dh_installemacsen(1).
Устанавливается в usr/lib/emacsen-common/packages/remove/двоичныйпакет в двоичныйпакет.
См. dh_installemacsen(1).
Устанавливается в usr/lib/emacsen-common/packages/startup/двоичныйпакет в двоичныйпакет.
См. dh_installemacsen(1).
Содержит список файлов или каталогов с примерами для их установки в usr/share/doc/двоичныйпакет/examples/ в двоичныйпакет.
См. dh_installexamples(1).
Если этот файл существует, то он используется как файл настройки для команды gbp.
См. gbp.conf(5), gbp(1) и git-buildpackage(1).
Содержит список info-файлов для их установки в двоичныйпакет.
См. dh_installinfo(1).
Installed into etc/init.d/binarypackage in binarypackage. (deprecated)
См. dh_installinit(1).
Содержит список файлов, которые должны быть установлены, но не устанавливаются командой dh_auto_install.
См. dh_install(1) и dh_auto_install(1).
List pairs of source and destination files to be symlinked. Each pair should be put on its own line, with the source and destination separated by whitespace.
См. dh_link(1).
Устанавливается в usr/share/lintian/overrides/двоичныйпакет в каталоге сборки пакета. Этот файл используется для блокировки ошибочных диагностических процедур lintian.
См. dh_lintian(1), lintian(1) и «Руководство пользователя Lintian».
If this optional file exists, debhelper uses this as the template to generate DEBIAN/binarypackage.{pre,post}{inst,rm} files within the binary package while adding «-- "$@"» to the dpkg-maintscript-helper(1) command.
See dh_installdeb(1) and «Chapter 6 - Package maintainer scripts and installation procedure» in the «Debian Policy Manual».
Команда debmake создаёт шаблонные файы страниц руководства. Переименуйте эти файлы соответствующим образом и обновите их содержимое.
Debian Policy requires that each program, utility, and function should have an associated manual page included in the same package. Manual pages are written in nroff(1). If you are new to making a manpage, use manpage.asciidoc or manpage.1 as the starting point.
Содержит список страниц руководства для их установки.
См. dh_installman(1).
tech-ctte #741573 decided «Debian should use .desktop files as appropriate».
Файл меню Debian устанавливается в usr/share/menu/двоичныйпакет в двоичныйпакет.
Информацию о формате см. в menufile(5). См. dh_installmenu(1).
Устанавливается в usr/share/doc/двоичныйпакет/NEWS.Debian.
См. dh_installchangelogs(1).
Набор файлов заплат -p1, которые применяются к исходному коде основной ветки до запуска процесса сборки исходного кода.
Команда debmake не создаёт файлы заплат.
См. dpkg-source(1), «Раздел 4.4, «quilt setup»» и «Раздел 5.9, «Step 3 (alternatives): Modification to the upstream source»».
If these optional files exist, the corresponding files are installed into the DEBIAN directory within the binary package after enriched by debhelper. Otherwise, these files in the DEBIAN directory within the binary package is generated by debhelper.
Whenever possible, simpler binarypackage.maintscript should be used instead.
See dh_installdeb(1) and «Chapter 6 - Package maintainer scripts and installation procedure» in the «Debian Policy Manual».
See also debconf-devel(7) and «3.9.1 Prompting in maintainer scripts» in the «Debian Policy Manual».
Устанавливается в первый двоичный пакет, указанный в файле debian/control как usr/share/doc/двоичныйпакет/README.Debian.
Этот файл содержит специальную информацию о пакете Debian.
См. dh_installdocs(1).
Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/README.source.
If running «dpkg-source -x» on a source package doesn’t produce the source of the package, ready for editing, and allow one to make changes and run dpkg-buildpackage to produce a modified package without taking any additional steps, creating this file is recommended.
Если этот файл существует, то он устанавливается в lib/systemd/system/двоичныйпакет.service в binarypackage.
См. dh_systemd_enable(1), dh_systemd_start(1) и dh_installinit(1).
Формат пакета Debian.
See «SOURCE PACKAGE FORMATS» in dpkg-source(1).
These file is not installed, but are scanned by the lintian command to provide overrides for the source package.
См. dh_lintian(1) и lintian(1).
The dpkg-source command uses this content as its options. Notable options are:
Этот файл не добавляется в создаваемый пакет с исходным кодом и предназначен скорее для добавления в систему управления версиями, используемую сопровождающим.
See «FILE FORMATS» in dpkg-source(1).
Свободная текстовая форма, размещаемая в верхней части автоматически созданной заплаты.
Этот файл не добавляется в создаваемый пакет с исходным кодом и предназначен скорее для добавления в систему управления версиями, используемую сопровождающим.
See «FILE FORMATS» in dpkg-source(1).
Файлы символов. Если эти файлы существуют, то они будут переданы для обработки и установки команде dpkg-gensymbols.
См. dh_makeshlibs(1) и «Раздел 9.16, «Библиотека символов»»..
Устанавливается в первый двоичный пакет, указанный в файле debian/control как usr/share/doc/двоичныйпакет/TODO.Debian.
См. dh_installdocs(1).
Если этот файл существует, то он устанавливается в usr/lib/tmpfiles.d/двоичныйпакет.conf в двоичныйпакет.
См. dh_systemd_enable(1), dh_systemd_start(1) и dh_installinit(1).
If this exists, it is installed into etc/init/package.conf in the package build directory. (deprecated)
См. dh_installinit(1).
[11] This is the default up to debhelper v13. At debhelper v14, it warns the default change. After debhelper v15, it will change the default to DESTDIR=debian/tmp/ .
[12] Для более чем 90% пакетов длина имени пакета равна 24 символам или меньше этого числа; длина версии основной ветки равна 10 символам или меньше, а длина номера редакции Debian равна 3 символам или меньше.
[13] Команда debmake создаёт несколько более сложный файл debian/rules. Тем не менее, это базовая часть.
[14] This simplicity is available since version 7 of the debhelper package. This guide assumes the use of debhelper version 13 or newer.
[15] This is the default up to debhelper v13. At debhelper v14, it warns the default change. After debhelper v15, it will change the default to DESTDIR=debian/tmp/ .
[16] If you are using the vim editor, make sure to save this with the «:wq» command.
| |
|
|
| Глава 5. Simple packaging |
|
Глава 7. Sanitization of the source |