Table of Contents
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.
Note | |
---|---|
为简明起见,某些细节被有意跳过。请按需查阅对应命令的手册页,例如dpkg-source(1)、dpkg-buildpackage(1)、dpkg(1)、dpkg-deb(1)、deb(5),等等。 |
Debian 源码包是一组用于构建 Debian 二进制软件包的输入文件,而非单个文件。
Debian 二进制软件包是一个特殊的档案文件,其中包含了一系列可安装的二进制数据及与它们相关的信息。
单个 Debian 源码包可能根据 debian/control 文件定义的内容产生多个 Debian 二进制软件包。
The non-native Debian package in the Debian source format “3.0 (quilt)” is the most normal Debian source package format.
Note | |
---|---|
有许多封装脚本可用。合理使用它们可以帮助您理顺工作流程,但是请确保您能理解它们内部的基本工作原理。 |
The Debian packaging workflow to create a Debian binary package involves generating several specifically named files (see “Section 6.3, “软件包名称和版本””) as defined in the “Debian Policy Manual”. This workflow can be summarized in 10 steps with some over simplification as follows.
上游的源码压缩包被复制(或符号链接)至一个特定的文件名 packagename_version.orig.tar.gz。
Debian 软件包规范文件将被添加至上游源代码中,存放在 package-version/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)
使用 dpkg-deb(1)、dpkg-genbuildinfo(1) 和 dpkg-genchanges(1) 创建 Debian 二进制软件包。
使用 lintian 命令检查 Debian 软件包的质量。(推荐)
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.
这里,请将文件名中对应的部分使用下面的方式进行替换:
参见 “Source-only uploads”。
Tip | |
---|---|
有很多种通过实践摸索而得到的补丁管理方法和版本控制系统的使用策略与技巧。您没有必要将它们全部用上。 |
Tip | |
---|---|
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 打包工作流可以组织成一个简单的模块化工作流,如下所示:
您几乎总是应当将 debhelper 列为您的软件包的构建依赖之一。本文档在接下来的内容中也假设您正在使用一个版本足够新的 debhelper 协助进行打包工作。
Note | |
---|---|
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.) |
Note | |
---|---|
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 作为上游版本号。
组成 Debian 软件包名称的字符选取存在一定的限制。最明显的限制应当是软件包名称中禁止出现大写字母。这里给出正则表达式形式的规则总结:
[-+.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]
为了避免命名冲突,对用户可见的二进制软件包名称不应选择任何常用的单词。
如果上游没有使用像 2.30.32 这样正常的版本编号方案,而是使用了诸如 11Apr29 这样包含日期、某些代号或者一个版本控制系统散列值等字符串作为版本号的一部分的话,请在上游版本号中将这些部分移除。这些信息可以稍后在 debian/changelog 文件中进行记录。如果您需要为软件设计一个版本字符串,可以使用 YYYYMMDD 格式,如 20110429 的字符串作为上游版本号。这样能保证 dpkg 命令在升级时能正确地确定版本的先后关系。如果您想要确保万一上游在未来重新采纳正常版本编号方案,例如 0.1 时能够做到顺畅地迁移,可以另行使用 0~YYMMDD 的格式,如 0~110429 作为上游版本号。
版本字符串可以按如下的方式使用 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.
而原生 Debian 软件包是较罕见的一种 Debian 软件包格式。它通常只用于打包仅对 Debian 项目有价值、有意义的软件。因此,该格式的使用通常不被提倡。
Caution | |
---|---|
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 “_”. |
原生 Debian 软件包不对 上游代码 和 Debian 的修改 进行区分,仅包含以下内容:
If you need to create a native Debian package, create it in the Debian source format “3.0 (native)” using dpkg-source(1).
Tip | |
---|---|
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 “Section 8.2, “Customized debian/rules”” and “Section 8.3, “Variables for debian/rules”” for customization.
Tip | |
---|---|
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. |
debian/control 文件包含了由空行分隔的数块元信息数据。每块元数据按照如下的顺序定义了下面这些内容:
See “Chapter 5 - Control files and their fields” of the “Debian Policy Manual” for the definition of each meta data.
Note | |
---|---|
The debmake command sets the debian/control file with “Build-Depends: debhelper-compat (= 13)” to set the debhelper compatibility level. |
Tip | |
---|---|
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.
即便您在自己独立进行软件包上传,您也必须记录所有较重要、用户可见的变更,例如:
如果您需要他人协助您进行上传,您应当更详尽地记录变更内容,包括所有打包相关的变动,从而方便他人对您的软件包进行审查。
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 打包修订编号。发行版部分被设置为 UNRELEASED 以避免半成品不小心被上传进入 Debian 仓库。
Tip | |
---|---|
The date string used in the debian/changelog file can be manually generated by the “LC_ALL=C date -R” command. |
Tip | |
---|---|
在实验时使用带有版本字符串的 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/binarypackage 目录中,文件名为 changelog.gz。
上游的变更日志是由 dh_installchangelogs 程序自动进行搜索和处理的;它会使用大小写不敏感的搜索方式寻找上游代码中特定名称的文件,如 changelog、changes、changelog.txt、changes.txt、history、history.txt 或 changelog.md。除了根目录,程序还会在 doc/ 目录和 docs/ 目录内进行搜索。
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.
除非明确指定(有些严格过头的) -P 选项,debmake 命令会为了实用性而跳过对自动生成的文件的检查与报告,默认它们采用宽松的许可证。
Caution | |
---|---|
这里的 debian/copyright 文件中描述的许可证信息匹配信息应当合适地进行排序,以确保越宽泛的文件匹配越靠前。请参见 “Section 15.6, “debmake -k””。 |
Note | |
---|---|
如果您发现了这个许可证检查工具存在一些问题,请向 debmake 软件包提交缺陷报告并提供包含出现问题的许可证和版权信息在内的相关文本内容。 |
As demonstrated in “Section 5.9, “Step 3 (alternatives): Modification to the upstream source””, the debian/patches/ directory holds
See how these files are used in:
Note | |
---|---|
Header texts of these patches should conform to “DEP-3”. |
Note | |
---|---|
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 “Chapter 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 “Section 6.12, “debian/upstream/signing-key.asc file””).
See uscan(1), “Section 8.4, “新上游版本””, “Section 7.1, “Fix with Files-Excluded””, and “Section 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 <rrt@sc3d.org>" 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 <rrt@sc3d.org>" ... Primary key fingerprint: 9297 8852 A62F A5E2 85B2 A174 6808 9F73 80EE 4A00
Tip | |
---|---|
If your network environment blocks access to the HKP port 11371, use “hkp://keyserver.ubuntu.com:80” instead. |
在确认密钥身份 80EE4A00 值得信任之后,应当下载其公钥并将其保存在 debian/upstream/signing-key.asc 文件中。
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 “Section 10.3, “Salsa CI service””.
另外也可以添加一些可选的配置文件并放入 debian/ 目录。它们大多用于控制由 debhelper 软件包提供的 dh_* 命令的行为,但也有一些文件会影响 dpkg-source、lintian 和 gbp 这些命令。
Tip | |
---|---|
Even an upstream source without its build system can be packaged just by using these files. See “Section 13.2, “无 Makefile(shell,命令行界面)”” 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)。
列出(构建前)未被 dh_auto_clean 命令清理,且需要手工清理的文件。
另请参考 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).
如果您正要打包的程序要求每个用户都对 /etc 目录下的配置文件进行修改,可以采取两种常见办法使其不作为 conffile 配置文件出现,避免 dpkg 命令处理软件包时给出不必要的处理选项。
另请参考 dh_installdeb(1)。
安装至 binarypackage 包内的 etc/cron/hourly/binarypackage 文件。
另请参见 dh_installcron(1) 和 cron(8)。
安装至 binarypackage 包内的 etc/cron/daily/binarypackage 文件。
另请参见 dh_installcron(1) 和 cron(8)。
安装至 binarypackage 包内的 etc/cron/weekly/binarypackage 文件。
另请参见 dh_installcron(1) 和 cron(8)。
Installed into the *etc/cron/monthly/*binarypackage file in binarypackage.
另请参见 dh_installcron(1) 和 cron(8)。
安装至 binarypackage 包内的 etc/cron.d/binarypackage 文件。
参见 dh_installcron(1)、cron(8) 和 crontab(5)。
若该文件存在,它将被安装至 binarypackage 包中的 etc/default/binarypackage 位置。
参见 dh_installinit(1)。
列出 binarypackage 包中要创建的目录。
参见 dh_installdirs(1)。
通常情况下您并不需要这么做,因为所有的 dh_install* 命令都会自动创建所需的目录。请仅在遇到问题时考虑使用这一工具。
作为 binarypackage 包中的 doc-base 控制文件进行安装。
See dh_installdocs(1) and “Debian doc-base Manual (doc-base.html)” provided by the doc-base package.
列出要安装在 binarypackage 包中的文档文件。
参见 dh_installdocs(1)。
安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/compat/binarypackage 文件。
参见 dh_installemacsen(1)。
安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/install/binarypackage 文件。
参见 dh_installemacsen(1)。
安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/remove/binarypackage 文件。
参见 dh_installemacsen(1)。
安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/startup/binarypackage 文件。
参见 dh_installemacsen(1)。
列出要安装至 binarypackage 包中 usr/share/doc/binarypackage/examples/ 位置下的示例文件或目录。
参见 dh_installexamples(1)。
如果该文件存在,它将作为 gbp 命令的配置文件发挥作用。
参见 gbp.conf(5)、gbp(1) 和 git-buildpackage(1)。
列出要安装至 binarypackage 包中的 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)。
列出要生成符号链接的源文件和目标文件对。每一对链接均应在单独的一行中列出,源文件和目标文件之间使用空白字符分隔。
参见 dh_link(1)。
安装至软件包构建目录的 usr/share/lintian/overrides/binarypackage 位置。该文件用于消除 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 命令生成的 man 手册页模板文件。请将其重命名为合适的文件名并更新其内容。
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.
列出要安装的 man 手册页。
参见 dh_installman(1)。
tech-ctte #741573 decided “Debian should use .desktop files as appropriate”.
安装至 binarypackage 包中的 usr/share/menu/binarypackage Debian 菜单文件。
参见 menufile(5) 以了解其格式。另请参见 dh_installmenu(1)。
安装至 usr/share/doc/binarypackage/NEWS.Debian 文件。
参见 dh_installchangelogs(1)。
这是 -p1 补丁文件的集合,它们将在使用源代码构建之前应用在上游源码上。
debmake 默认不会生成补丁文件。
参见 dpkg-source(1)、“Section 4.4, “quilt setup”” 和 “Section 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/binarypackage/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.
如果该文件存在,它将被安装到 binarypackage 包下面的 lib/systemd/system/binarypackage.service 位置。
参见 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)。
dpkg-source 命令使用此内容作为它的选项,比较重要的选项有:
该文件不会包含在生成的源码包中,仅对维护者在版本控制系统中维护软件包有意义。
See “FILE FORMATS” in dpkg-source(1).
自由格式的文本,将被包含在自动生成补丁的顶部。
该文件不会包含在生成的源码包中,仅对维护者在版本控制系统中维护软件包有意义。
See “FILE FORMATS” in dpkg-source(1).
这些符号文件如果存在,将交由 dpkg-gensymbols 命令进行处理和安装。
参见 dh_makeshlibs(1) 和 “Section 9.16, “库符号””。
安装至 debian/control 文件列出的第一个二进制包中的 usr/share/doc/binarypackage/TODO.Debian 文件。
参见 dh_installdocs(1)。
如果该文件存在,它将被安装至 binarypackage 包中的 usr/lib/tmpfiles.d/binarypackage.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] 对九成以上的软件包来说,软件包名称都不会超过 24 个字符;上游版本号通常不超过 10 个字符,而 Debian 修订版本号也通常不超过 3 个字符。
[13] debmake 命令会产生稍微复杂一些的 debian/rules 文件。虽然如此,其核心结构没有什么变化。
[14] 这个简化形式在 debhelper 软件包第七版或更新的版本中可用。本指南内容假设您在使用 debhelper 第 13 版或更新的版本。
[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.