目录
这里展示了 Debian 打包工作中针对非本土软件包使用”3.0 (quilt)”格式进行打包所遵循基本规则的一个全局性概览。
![]() |
注意 |
---|---|
为简明起见,某些细节被有意跳过。请按需查阅对应命令的手册页,例如dpkg-source(1)、dpkg-buildpackage(1)、dpkg(1)、dpkg-deb(1)、deb(5),等等。 |
Debian 源码包是一组用于构建 Debian 二进制软件包的输入文件,而非单个文件。
Debian 二进制软件包是一个特殊的档案文件,其中包含了一系列可安装的二进制数据及与它们相关的信息。
单个 Debian 源码包可能根据 debian/control 文件定义的内容产生多个 Debian 二进制软件包。
使用 “3.0 (quilt)”格式的非本土 Debian 软件包是最普通的 Debian 源码包格式。
![]() |
注意 |
---|---|
有许多封装脚本可用。合理使用它们可以帮助你理顺工作流程,但是请确保你能理解它们内部的基本工作原理。 |
创建 Debian 二进制软件包的 Debian 打包工作流涉及创建数个特定名称的文件(参见 第 5.2 节 “软件包名称和版本”)。“Debian 政策手册”对此进行了定义。
一个极其简化的 Debian 打包工作流可以概括为以下五步。
上游的源码压缩包被复制(或符号链接)至一个特定的文件名 packagename_version.orig.tar.gz。
Debian 软件包规范文件将被添加至上游源代码中,存放在 package-version/debian/ 目录下。
debian/* 位置下的必要规范文件:
在 package-version/ 目录中调用 debmake 命令将会提供这些配置文件的一套模板。
dpkg-buildpackage 命令(通常由它的封装命令 debuild 或 pdebuild 所使用)会在 package-version/ 目录中被调用,进而以调用 debian/rules 脚本的方式制作 Debian 源码包和二进制软件包。
使用 dpkg-source(1) 以“3.0 (quilt)”格式创建 Debian 源码包
使用“debian/rules build”构建源代码并安装到 $(DESTDIR) 中
使用 dpkg-deb(1)、dpkg-genbuildinfo(1) 和 dpkg-genchanges(1) 创建 Debian 二进制软件包。
使用 lintian 命令检查 Debian 软件包的质量。(推荐)
遵守 ftp-master 的拒绝(rejection)指导方针。
这里,请将文件名中对应的部分使用下面的方式进行替换:
![]() |
提示 |
---|---|
有很多种通过实践摸索而得到的补丁管理方法和版本控制系统的使用策略与技巧。您没有必要将它们全部用上。 |
![]() |
提示 |
---|---|
在“Debian 开发者参考”一文的 第 6 章 最佳打包实践 部分有十分详尽的相关文档。请读一读这些内容。 |
![]() |
提示 |
---|---|
Although a Debian package can be made by writing a debian/rules script without using the debhelper package, it is unpractical to do so due to the complication of modern packaging concerns such as debug symbol handling, multiarch library, reproducible build, etc. The modern Debian packaging workflow can be organized into a simple modular workflow by using the dh command to invoke many utility scripts in the debhelper package and configuring their behavior with declarative configuration files in the debian/ directory. Many “Policy” required features such as proper file permissions, insertion of installation hook scripts, etc. are automatically |
Although a Debian package can be made by writing a debian/rules script without using the debhelper package, it is unpractical to do so. There are too many modern “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.
The modern Debian packaging workflow can be organized into a simple modular workflow by:
如果所获取上游源代码的形式为 hello-0.9.12.tar.gz,您可以将 hello 作为上游源代码名称,并将 0.9.12 作为上游版本号。
debmake 的目的是为软件包维护者提供开始工作的模板文件。注释行以 # 开始,其中包含一些教程性文字。您在将软件包上传至 Debian 仓库之前必须删除或者修改这样的注释行。
许可证信息的提取和指派过程应用了大量启发式操作,因此在某些情况下可能不会正常工作。强烈建议您搭配使用其它工具,例如来自 devscripts 软件包的 licensecheck 工具,以配合 debmake 的使用。
组成 Debian 软件包名称的字符选取存在一定的限制。最明显的限制应当是软件包名称中禁止出现大写字母。下面给出正则表达式形式的规则总结。
请在“Debian 政策手册”的 第 5 章 - Control 文件及其字段 一节中查看其精确定义。
debmake 所假设的打包情景是相对简单的。因此,所有与解释器相关的程序都会默认为“Architecture: all”的情况。当然,这个假设并非总是成立。
您必须为 Debian 打包工作适当地调整软件包名称和上游版本号。
为了能有效地使用一些流行的工具(如 aptitude)管理软件包名称和版本信息,最好能将软件包名称保持在 30 字符以下;版本号和修订号加起来最好能不超过 14 个字符。[9]
为了避免命名冲突,对用户可见的二进制软件包名称不应选择任何常用的单词。
如果上游没有使用像 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。
使用“3.0 (quilt)”格式的非本土 Debian 软件包是最常见最标准的 Debian 源码包格式。根据 dpkg-source(1) 的描述,此时的 debian/source/format 文件应当包含“3.0 (quilt) 的文字内容。上述的工作流和接下来给出的打包示例都使用了这种格式。
而本土 Debian 软件包是较罕见的一种 Debian 软件包格式。它通常只用于打包仅对 Debian 项目有价值、有意义的软件。因此,该格式的使用通常不被提倡。
![]() |
小心 |
---|---|
在上游 tarball 压缩包无法使用其正确名称 package_version.orig.tar.gz 被 dpkg-buildpackage 获取到的时候,会出现意外地构建了本土 Debian 软件包的情况。这是新手常见的一个错误,通常是因构建中错误地在符号链接名称中使用了“-”字符而非正确的“_”字符。[译注:此处仍然假设打包的场景是已经获取或形成了名为 package-version.tar.gz 的上游源码 tarball。Debian 的打包工作很大程度上是以上游源码 tarball 作为基础的,这一点须时刻牢记在心。] |
本土 Debian 软件包不对 上游代码 和 Debian 的修改 进行区分,仅包含以下内容:
如果你需要手动创建本土 Debian 软件包,可以使用 dpkg-source(1) 工具以“3.0 (native)”格式进行创建。
![]() |
提示 |
---|---|
某些人希望推行对那些即使是仅针对 Debian 编写的那些软件也使用非本土软件包格式的做法。这种做法所需要的不包含 debian/* 文件的 tarball 压缩包事先需要手动生成以符合在 第 5.1 节 “打包工作流” 中的标准工作流。他们声称使用非本土软件包格式可以方便与下游发行版之间的沟通与交流。 |
![]() |
提示 |
---|---|
如果使用本土软件包格式,没有必要事先创建 tarball 压缩包。要创建一个本土 Debian 软件包,应当将 debian/source/format 文件的内容设置为“3.0 (native)”,适当编写 debian/changelog 文件使得版本号中不包含 Debian 修订号(例如,1.0 而非 1.0-1),最后在源码树中调用“dpkg-source -b .”命令。这样做便可以自动生成包含源代码的 tarball。 |
debian/rules 脚本是用于实际构建 Debian 软件包的可执行脚本。
debian/rules 脚本重新封装了上游的构建系统(参见 第 5.16 节 “上游构建系统”)以达到将文件安装至 $(DESTDIR)并将生成的文件存入各个 deb 格式文件中的目的。
$(DESTDIR) 路径具体值依赖于构建的类型。
由 debhelper 软件包提供的 dh 命令与一些相关的软件包共同工作,作为典型的上游构建系统的一层封装,同时它支持所有 Debian 政策(Debian Policy)规定必须在 debian/rules 实现的目标(target),以此提供一个统一的访问接口。
![]() |
注意 |
---|---|
对使用了 debhelper“compat >=9”的情况,dh 命令将在编译参数未事先设置的情况下根据 dpkg-buildflags 命令返回的值设置并导出各个编译参数(如 CFLAGS、CXXFLAGS、FFLAGS、CPPFLAGS 和 LDFLAGS)。(dh 命令将调用在 Debian::Debhelper::Dh_Lib 模块中定义的 set_buildflags。) |
受益于 dh 命令对构建目标的抽象化 [10],一个符合 Debian 政策而支持所有必需目标(target)的 debian/rules 文件可以简单地写成如下形式[11]:
简单的 debian/rules:.
#!/usr/bin/make -f #export DH_VERBOSE = 1 %: dh $@
从本质上来看,这里的 dh 命令的作用是作为一个序列化工具,在合适的时候调用所有所需的 dh_* 命令。
![]() |
注意 |
---|---|
debmake 命令会在 debian/control 文件中写入“Build-Depends: debhelper (>=9)”,并在 debian/compat 文件中写入“9”。 |
![]() |
提示 |
---|---|
设置“export DH_VERBOSE = 1”会输出构建系统中每一条会修改文件内容的命令。它同时会在某些构建系统中启用详细输出构建日志的选项。 |
通过添加合适的 override_dh_* 目标(target)并编写对应的规则,可以实现对 debian/rules 脚本的灵活定制。
如果需要在 dh 命令调用某些特定的 dh_foo 命令时采取某些特别的操作,则任何自动执行的操作均可以被 debian/rules 中额外添加的 override_dh_foo 这样的 Makefile 目标所覆写。
构建的过程可以使用某些上游提供的接口传递信息,例如提供传递给某些标准的源代码构建系统的参数。这些构建系统包括但不限于:
在这种情况下,你应该添加一个 override_dh_auto_build 目标并在其中执行“dh_auto_build -- 自定义参数” 的命令。这样可以在 dh_auto_build 默认传递的参数之后将用户给出的 自定义参数 继续传递给那些构建系统。
![]() |
提示 |
---|---|
如果上文提到的构建系统命令已知得到了 dh_auto_build 命令的支持的话,请避免直接调用这些命令(而让 dh_auto_build 自动处理)。 |
debmake 命令所创建的初始模版文件除了应用了上文提到的简单 debian/rules 文件的优点外,同时为后续可能涉及的软件包加固等情景添加了一些额外的定制选项。您需要先了解整个构建系统背后的工作原理(参见 第 5.16 节 “上游构建系统”),之后才能收放自如地定制软件包来处理某些非常规的工作情况。
Some variable definitions useful for customizing debian/rules can be found in files under /usr/share/dpkg/. Notably:
If you wish to use some of these useful variables in debian/rules, copy relevant codes to debian/rules or write a simpler alternative in it. Please keep debian/rules simple.
For example, you can add an extra option to CONFIGURE_FLAGS for linux-any target architectures by adding the followings to debian/rules:
DEB_HOST_ARCH_OS ?= $(shell dpkg-architecture -qDEB_HOST_ARCH_OS) ... ifeq ($(DEB_HOST_ARCH_OS),linux) CONFIGURE_FLAGS += --enable-wayland endif
![]() |
提示 |
---|---|
It was useful to include buildflags.mk in the debian/rules to set the build flags such as CPPFLAGS, CFLAGS, LDFLAGS, etc. properly while honoring DEB_CFLAGS_MAINT_APPEND, DEB_BUILD_MAINT_OPTIONS, etc. for the debhelper “compat <= 8”. Now you should use the debhelper “compat >= 9”, should not include buildflags.mk without specific reasons, and should let the dh command set these build flags. |
See 第 5.19 节 “多体系结构”, dpkg-architecture(1) and dpkg-buildflags(1).
Here are some recommendations to attain the reproducible build result.
Read more at ReproducibleBuilds.
The control file source-name_source-version_arch.buildinfo generated by dpkg-genbuildinfo(1) records the build environment. See deb-buildinfo(5)
The debian/control file consists of blocks of meta data separated by the 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.
For well behaving build systems, the split of the Debian binary package into small ones can be realized as follows.
Please check examples in this guide:
The debmake command with the -b option provides intuitive and flexible method to creates the initial template debian/control file defining the split of the Debian binary packages with following stanzas:
The debmake command also set an appropriate set of substvars used in each pertinent dependency stanza.
Let’s quote the pertinent part from the debmake manpage here.
set the binary package specs by the comma separated list of binarypackage:type pairs, e.g., in the full form “foo:bin,foo-doc:doc,libfoo1:lib,libfoo1-dbg:dbg,libfoo-dev:dev” or in the short form “,-doc,libfoo1,libfoo1-dbg, libfoo-dev”.
Here, binarypackage is the binary package name; and the optional type is chosen from the following type values:
The pair values in the parentheses, such as (any, foreign), are the Architecture and Multi-Arch stanza values set in the debian/control file.
In many cases, the debmake command makes good guesses for type from binarypackage. If type is not obvious, type is set to bin. For example, libfoo sets type to lib, and font-bar sets type to data, …
If the source tree contents do not match settings for type, the debmake command warns you.
Here are some typical multiarch package split scenarios for the following upstream source examples using the debmake command:
binarypackage | type | Architecture: | Multi-Arch: | 软件包内容 |
---|---|---|---|---|
lib foo1 |
lib * |
any |
same |
共享库,可共同安装 |
lib foo1 -dbg |
dbg * |
any |
same |
共享库调试符号,可共同安装 |
lib foo -dev |
dev * |
any |
same |
共享库头文件之类,可共同安装 |
lib foo -tools |
bin * |
any |
外来 |
运行时支持程序,不可共同安装 |
lib foo -doc |
doc * |
全部 |
外来 |
共享库文档 |
bar |
bin * |
any |
外来 |
编译好的程序文件,不可共同安装 |
bar -doc |
doc * |
全部 |
外来 |
程序的配套文档文件 |
baz |
script |
全部 |
外来 |
解释型程序文件 |
Let’s consider that the upstream source tarball of the libfoo library is updated from libfoo-7.0.tar.gz to libfoo-8.0.tar.gz with the new SONAME major version which affects other packages.
The binary library package must be renamed from libfoo7 to libfoo8 to keep the unstable suite system working for all dependent packages after the upload of the package based on the libfoo-8.0.tar.gz.
![]() |
警告 |
---|---|
If the binary library package isn’t renamed, many dependent packages in the unstable suite become broken just after the library upload even if the binNMU is requested. The binNMU may not happen immediately after the upload due to several reasons. |
The -dev package must follow one of the following naming rules:
Use the unversioned -dev package name: libfoo-dev
Only one version of the library source package is allowed in the archive.
Use the versioned -dev package names: libfoo7-dev and libfoo8-dev
Two versions of the library source packages are allowed simultaneously in the archive.
![]() |
提示 |
---|---|
If data encoding scheme changes (e.g., latin1 to utf-8), the same care as the API change needs to be taken. |
See 第 5.18 节 “库软件包”.
The debian/control file also defines the package dependency in which the variable substitutions mechanism (substvar) may be used to free package maintainers from chores of tracking most of the simple package dependency cases. See deb-substvars(5).
The debmake command supports following substvars.
For the shared library, required libraries found simply by "objdump -p /path/to/program | grep NEEDED" are covered by the shlib substvar.
For the Python and other interpreters, required modules found simply looking for lines with “import”, “use”, “require”, etc., are covered by the corresponding substvars.
For other programs which do not deploy their own substvars, the misc substvar covers their dependency.
For POSIX shell programs, there is no easy way to identify the dependency and no substvar covers their dependency.
For libraries and modules required via the dynamic loading mechanism including the GObject introspection mechanism, there is no easy way to identify the dependency and no substvar covers their dependency.
A binNMU is a binary-only non-maintainer upload performed for library transitions etc. In a binNMU, only the “Architecture: any” packages are rebuilt with a suffixed version number (e.g. version 2.3.4-3 will become 2.3.4-3+b1). The “Architecture: all” packages are not built.
The dependency defined in the debian/control file among binary packages from a same source package should be safe for the binNMU. This needs attention if there are both “Architecture: any” and “Architecture: all” packages involved in it.
“Architecture: any” package depends on “Architecture: any” foo package
“Architecture: any” package depends on “Architecture: all” bar package
“Architecture: all” package depends on “Architecture: any” baz package
The debian/changelog file records the Debian package history and defines the upstream package version and the Debian revision in its first line.
The debmake command creates the initial template file with the upstream package version and the Debian revision. The distribution is set to UNRELEASED to prevent accidental upload to the Debian archive.
The debchange command (alias dch) is used to edit this.
![]() |
提示 |
---|---|
The date string used in the debian/changelog file can be manually generated by the “LC_ALL=C date -R” command. |
This is installed in the /usr/share/doc/binarypackage directory as changelog.Debian.gz by the dh_installchangelogs command.
The upstream changelog is installed in the /usr/share/doc/binarypackage directory as 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.
After finishing your packaging and verifying its quality, please execute the “dch -r” command and save the finalized debian/changelog file with the distribution normally set to unstable. [12] If you are packaging for the backports, security updates, LTS, etc., please use the appropriate distribution names, instead.
Debian takes the copyright and license matters very seriously. The “Debian Policy Manual” enforces to have summary of them in the debian/copyright file in the package.
You should format it as the machine-readable debian/copyright file (DEP-5).
![]() |
小心 |
---|---|
The debian/copyright file should be sorted to keep the generic file patterns at the top of the list. See 第 6.4 节 “debmake -k”. |
The debmake command creates the initial DEP-5 compatible template file by scanning the entire source tree. It uses an internal license checker to classify each license text. [13]
Unless specifically requested to be pedantic with the -P option, the debmake command skips reporting for auto-generated files with permissive licenses to be practical.
![]() |
注意 |
---|---|
If you find issues with this license checker, please file a bug report to the debmake package with the problematic part of text containing the copyright and license. |
![]() |
注意 |
---|---|
The debmake command focuses on bunching up same copyright and license claims in details to create template for debian/copyright. In order to do this within reasonable time, it only picks the first section which looks like copyright and license claims. So its license assignment may not be optimal. Please also use other tools such as licensecheck. |
![]() |
提示 |
---|---|
You are highly encourage to check the license status with the licensecheck(1) command and, as needed, with your manual code review. |
The -p1 patches in the debian/patches/ directory are applied in the sequence defined in the debian/patches/series file to the upstream source tree before the build process.
![]() |
注意 |
---|---|
The native Debian package (see 第 5.3 节 “本土 Debian 软件包”) doesn’t use these files. |
There are several methods to prepare a series of -p1 patches.
The diff command
Primitive but versatile method
The dquilt command
The “dpkg-source --commit” command
The automatic patch generation by the dpkg-buildpackage
The gbp-pq command
The gbp-dpm command
Wherever these patches come from, it is good idea to tag them with DEP-3 compatible header.
![]() |
提示 |
---|---|
The dgit package offeres an alternative git integration tool with the Debian package archive. |
The “dpkg-source -x” command unpacks the Debian source package.
It normally applies the patches in the debian/patches/ directory to the source tree and records the patch state in the .pc/ directory.
If you wish to keep the source tree unmodified (for example, for use in 第 5.13 节 “Recording in VCS (standard)”), please use the --skip-patches option.
The quilt command (or its wrapped dquilt command) was needed to manage the -p1 patches in the debian/patches/ directory before the --commit feature was added to the dpkg-source command in 1.16.1.
The patches should apply cleanly when using the dpkg-source command. Thus you can’t just copy the patches to the new packaging of the new upstream release if there are patch offset etc.
The dquilt command (see 第 3.4 节 “quilt”) is more foregiving. You can normalize the patches by the dquilt command.
$ while dquilt push; do dquilt refresh ; done $ dquilt pop -a
There is one advantage of using the dpkg-source command over the dquilt command. While the dquilt command can not handle modified binary files automatically, the dpkg-source command detects modified binary files and lists them in the debian/source/include-binaries file to include them in the Debian tarball.
Some packages are signed by the GPG key.
For example, GNU hello can be downloaded via HTTP from https://ftp.gnu.org/gnu/hello/ . There are sets of files:
Let’s pick the latest version set.
$ 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 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.
$ 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
![]() |
提示 |
---|---|
If your network environment blocks access to the HPK port 11371, use “hkp://keyserver.ubuntu.com:80” instead. |
After confirming the key ID 80EE4A00 is trust worthy one, download its public key into the debian/upstream/signing-key.asc file.
$ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.asc
Then set the corresponding debian/watch file as follows.
version=4 pgpsigurlmangle=s/$/.sig/ https://ftp.gnu.org/gnu/hello/ hello-(\d[\d.]*)\.tar\.(?:gz|bz2|xz)
Now the uscan command will check the authenticity of the package using the GPG signature.
Debian takes software freedom seriously and follows the DFSG.
The non-DFSG components in the upstream source tarball can be easily removed when the uscan command is used to update the Debian package.
Run the uscan command to download the new upstream tarball.
Optional configuration files may be added under the debian/ directory. Most of them are to control dh_* commands offered by the debhelper package but there are some for dpkg-source, lintian and gbp commands.
![]() |
提示 |
---|---|
Check debhelper(7) for the latest available set of the dh_* commands. |
These debian/binarypackage.* files provide very powerful means to set the installation path of files. Even an upstream source without its build system can be packaged just by using these files. See 第 8.2 节 “No Makefile (shell, CLI)” as an example.
Here is the alphabetical list of notable optional configuration files.
List bash
completion scripts to be installed.
The bash-completion
package is required for both build and user environment.
See dh_bash-completion(1).
List files which should be removed but are not cleaned by the dh_auto_clean command.
See dh_auto_clean(1) and dh_clean(1).
Set the debhelper compatibility level (currently, “9”).
See “COMPATIBILITY LEVELS” in debhelper(8).
No need for this file under “compat >= 3” since all files in the etc/ directory are conffiles.
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 to not be conffiles, keeping the dpkg command happy and quiet.
See dh_installdeb(1).
Installed into the etc/cron/hourly/binarypackage file in binarypackage.
See dh_installcron(1) and cron(8).
Installed into the etc/cron/daily/binarypackage file in binarypackage.
See dh_installcron(1) and cron(8).
Installed into the etc/cron/weekly/binarypackage file in binarypackage.
See dh_installcron(1) and cron(8).
Installed into the etc/cron/monthly/binarypackage file in binarypackage.
See dh_installcro*(1) and cron(8).
Installed into the etc/cron.d/binarypackage file in binarypackage.
See dh_installcron(1), cron(8), and crontab(5).
If this exists, it is installed into etc/default/binarypackage in binarypackage.
See dh_installinit(1).
List directories to be created in binarypackage.
See dh_installdirs(1).
Usually, this is not needed since all dh_install* commands create required directories automatically. Use this only when you run into trouble.
Installed as the doc-base control file in binarypackage.
See dh_installdocs(1) and Debian doc-base Manual provided by the doc-base package.
List documentation files to be installed in binarypackage.
See dh_installdocs(1).
Installed into usr/lib/emacsen-common/packages/compat/binarypackage in binarypackage.
See dh_installemacsen(1).
Installed into usr/lib/emacsen-common/packages/install/binarypackage in binarypackage.
See dh_installemacsen(1).
Installed into usr/lib/emacsen-common/packages/remove/binarypackage in binarypackage.
See dh_installemacsen(1).
Installed into usr/lib/emacsen-common/packages/startup/binarypackage in binarypackage.
See dh_installemacsen(1).
List example files or directories to be installed into usr/share/doc/binarypackage/examples/ in binarypackage.
See dh_installexamples(1).
If this exists, it functions as the configuration file for the gbp command.
See gbp.conf(5), gbp(1), and git-buildpackage(1).
List info files to be installed in binarypackage.
See dh_installinfo(1).
Installed into etc/init.d/binarypackage in binarypackage.
See dh_installinit(1).
List files which should be installed but are not installed by the dh_auto_install command.
See dh_install(1) and dh_auto_install(1).
These are copyright file examples generated by the debmake command. Use these as the reference for making copyright file.
Please make sure to erase these files.
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 the whitespace.
See dh_link(1).
Installed into usr/share/lintian/overrides/binarypackage in the package build directory. This file is used to suppress erroneous lintian diagnostics.
See dh_lintian(1), lintian(1) and Lintian User’s Manual.
These are manpage template files generated by the debmake command. Please rename these to appropriate file names and update their contents.
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 manpage, use manpage.asciidoc or manpage.1 as the starting point.
List man pages to be installed.
See dh_installman(1).
tech-ctte #741573 decided "Debian should use .desktop files as appropriate".
Debian menu file installed into usr/share/menu/binarypackage in binarypackage.
See menufile(5) for its format. See dh_installmenu(1).
Installed into usr/share/doc/binarypackage/NEWS.Debian.
See dh_installchangelogs(1).
Collection of -p1 patch files which are applied to the upstream source before building the source.
See dpkg-source(1), 第 3.4 节 “quilt” and 第 4.8 节 “第三步(备选):修改上游源代码”.
No patch files are generated by the debmake command.
These maintainer scripts are installed into the DEBIAN directory.
Inside the scripts, the token #DEBHELPER# is replaced with shell script snippets generated by other debhelper commands.
See dh_installdeb(1) and Chapter 6 - Package maintainer scripts and installation procedure of the “Debian Policy Manual”.
See also debconf-devel(7) and 3.9.1 Prompting in maintainer scripts of the “Debian Policy Manual”.
Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/README.Debian.
See dh_installdocs(1).
This file provides the information specific to the Debian package.
If this exists, it is installed into lib/systemd/system/binarypackage.service in binarypackage.
See dh_systemd_enable(1), dh_systemd_start(1), and dh_installinit(1).
The Debian package format.
See “SOURCE PACKAGE FORMATS” in dpkg-source(1).
These files are not installed, but will be scanned by the lintian command to provide overrides for the source package.
See dh_lintian(1) and lintian(1).
The dpkg-source command uses this contents as its options. Notable options are:
This is not included in the generated source package and is meant to be committed to the VCS of the maintainer.
See “FILE FORMATS” in dpkg-source(1).
Free form text that is put on top of the automatic patch generated.
This is not included in the generated source package and is meant to be committed to the VCS of the maintainer.
+ See “FILE FORMATS” in dpkg-source(1).
The symbols files, if present, are passed to the dpkg-gensymbols command to be processed and installed.
See dh_makeshlibs(1) and 第 5.18.1 节 “Library symbols”..
Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/TODO.Debian.
See dh_installdocs(1).
If this exists, it is installed into usr/lib/tmpfiles.d/binarypackage.conf in binarypackage.
See dh_systemd_enable(1), dh_systemd_start(1), and dh_installinit(1).
If this exists, it is installed into etc/init/package.conf in the package build directory. (deprecated)
See dh_installinit(1) and 第 8.1 节 “Cherry-pick templates”.
The control file for the uscan command to download the latest upstream version
This control file may be configured to verify the authenticity of the tarball using its GPG signature (see 第 5.9 节 “debian/upstream/signing-key.asc”).
See 第 5.10 节 “debian/watch and DFSG” and uscan(1).
Here are a few reminders to the above list.
Let’s recap the customization of the Debian packaging.
All customization data for the Debian package reside in the debian/ directory. A simple example is given in 第 4.6 节 “第三步:编辑模板文件”. Normally, this customization involves combination of the followings:
When these are not sufficient to make a good Debian package, the modification to the upstream source recorded as the -p1 patches in the debian/patches/ directory is deployed. These patches are applied in the sequence defined in the debian/patches/series file before building the package (see 第 5.8 节 “debian/patches/*”). A simple examples are given in 第 4.8 节 “第三步(备选):修改上游源代码”.
You should address the root cause of the Debian packaging problem by the least invasive way. The generated package shall be more robust for the future upgrades in this way.
![]() |
注意 |
---|---|
Send the patch addressing the root cause to the upstream if it is useful to the upstream. |
Typically, Git is used as VCS to record the Debian packaging activity with the following branches.
master branch
upstream branch
![]() |
提示 |
---|---|
It’s a good idea to add the .gitignore file listing .pc. |
![]() |
提示 |
---|---|
Add unapply-patches and abort-on-upstream-changes lines to the debian/source/local-options file to keep the upstream portion unmodified |
![]() |
提示 |
---|---|
You may also track the upstream VCS data with a branch different from the upstream branch to ease cherry-picking of patches. |
You may not wish to keep up with creating the -p1 patch files for all upstream changes needed. You can record the Debian packaging activity with the following branches.
master branch
upstream branch
Adding few extra files in debian/ directory enables you to do this.
$ tar -xvzf <package-version>.tar.gz $ ln -sf <package_version>.orig.tar.gz $ cd <package-version>/ ... hack...hack... $ echo "single-debian-patch" >> debian/source/local-options $ cat >debian/source/local-patch-header <<END This patch contains all the Debian-specific changes mixed together. To review them separately, please inspect the VCS history at https://git.debian.org/?=collab-maint/foo.git
Let the dpkg-source command invoked by the Debian package build process (dpkg-buildpackage, debuild, …) to generate the -p1 patch file debian/patches/debian-changes automatically.
![]() |
提示 |
---|---|
This approach can be adopted for any VCS tools. Since this approach merges all changes into a merged patch, it is desirable to keep the VCS data publicly accessible. |
![]() |
提示 |
---|---|
The debian/source/local-options and debian/source/local-patch-header files are meant to be recorded in the VCS. These aren’t included in the Debian source package. |
There are a few cases which cause the inclusion of the undesirable contents in the generated Debian source package.
Normally, the -i and -I options set in 第 3.5 节 “devscripts” for the dpkg-source command should avoid these. Here, the -i option is aimed at the non-native package while the -I is aimed at the native package. See dpkg-source(1) and the “dpkg-source --help” output.
There are several methods to avoid inclusion of the undesirable contents.
The problem of extraneous contents can be fixed by removing such files in the “debian/rules clean” target. This is also useful for auto-generated files
![]() |
注意 |
---|---|
The “debian/rules clean” target is called before the “dpkg-source --build” command by the dpkg-buildpackage command and the “dpkg-source --build” command ignores removed files. |
The problem of extraneous contents can be fixed by restoring the source tree by committing the source tree to the VCS before the first build.
You can restore the source tree before the second package build. For example:
$ git reset --hard $ git clean -dfx $ debuild
This works because the dpkg-source command ignores the contents of the typical VCS files in the source tree with the setting in 第 3.5 节 “devscripts”.
![]() |
提示 |
---|---|
If the source tree is not managed by the VCS, you should run “git init; git add -A .; git commit” before the first build. |
This is for the non-native package.
The problem of extraneous diffs can be fixed by ignoring changes made to parts of the source tree by adding the “extend-diff-ignore=…” line in the debian/source/options file.
For excluding the config.sub, config.guess and Makefile files:
# Don't store changes on autogenerated files extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
![]() |
注意 |
---|---|
This approach always works, even when you can’t remove the file. So it saves you having to make a backup of the unmodified file just to be able to restore it before the next build. |
![]() |
提示 |
---|---|
If the debian/source/local-options file is used instead, you can hide this setting from the generated source package. This may be useful when the local non-standard VCS files interfere with your packaging. |
This is for the native package.
You can exclude some files in the source tree from the generated tarball by tweaking the file glob by adding the “tar-ignore=…” lines in the debian/source/options or debian/source/local-options files.
![]() |
注意 |
---|---|
If, for example, the source package of a native package needs files with the file extension .o as a part of the test data, the setting in 第 3.5 节 “devscripts” is too aggressive. You can work around this problem by dropping the -I option for DEBUILD_DPKG_BUILDPACKAGE_OPTS in 第 3.5 节 “devscripts” while adding the “tar-ignore=…” lines in the debian/source/local-options file for each package. |
Upstream build systems are designed to go through several steps to install generated binary files to the system from the source distribution.
Autotools (autoconf + automake) has 4 steps.
The upstream usually performs the step 1 and builds the upstream tarball for distribution using the “make dist” command. (The generated tarball contains not only the pristine upstream VCS contents but also other generated files.)
The package maintainer needs to take care steps 2 to 4 at least. This is realized by the “dh $@ --with autotools-dev” command used in the debian/rules file.
The package maintainer may wish to take care all steps 1 to 4. This is realized by the “dh $@ --with autoreconf” command used in the debian/rules file. This rebuilds all auto-generated files to the latest version ones and provides better supports for the porting to the newer architectures.
If you wish to learn more on the Autotools, please see:
CMake has 4 steps.
The upstream tarball contains no auto-generated files and is generated by the tar command after the step 1.
The package maintainer needs to take care steps 2 to 4.
If you wish to learn more on the CMake, please see:
Python distutils has 3 steps.
The upstream usually performs the step 1 and builds the upstream tarball for distribution using the “python setup.py sdist” command.
The package maintainer needs to take care the step 2. This is realized simply by the “dh $@” command used in the debian/rules file, after jessie.
The situation of other build systems, such as CMake, are very similar to this Python one.
If you wish to learn more on the Python3 and distutils, please see:
The Debian package is built with the debugging information but packaged into the binary package after stripping the debugging information as required by Chapter 10 - Files of the “Debian Policy Manual”.
See
The debugging information is automatically packaged separately as the debug package using the dh_strip command in its default. The name of such debug package normally has the -dbgsym suffix.
The debugging information can be packaged separately as the debug package using the “dh_strip --dbg-package=package” command in the override_dh_strip: target of the debian/rules file. The name of such debug package normally has the -dbg suffix.
The installation path of the debugging information is as follows to enable auto-loading of it by the gdb command.
![]() |
注意 |
---|---|
The creation of the -dbg package is optional. |
![]() |
注意 |
---|---|
This is deprecated for Strech 9.0 and after. |
Packaging the library software requires you to perform much more work than usual. Here are some reminders for packaging the library software:
Before packaging the shared library software, see:
For the historic background study, see:
Escaping the Dependency Hell [14]
Debian Library Packaging guide [15]
The symbols support in the dpkg introduced to Debian lenny (5.0, May 2009) helps us to manage the backward ABI compatibility of the library package with the same package name. The DEBIAN/symbols file in the binary package provides the minimal version associated to each symbol.
The oversimplified method for the library packaging is as follows.
Extract the old DEBIAN/symbols file of the immediate previous binary package with the “dpkg-deb -e” command.
Copy it to the debian/binarypackage.symbols file.
Build the binary package.
If the dpkg-gensymbols command warns some new symbols:
If the dpkg-gensymbols command does not warn new symbols:
For the details, you should read the following primary references.
Yous should also check:
![]() |
提示 |
---|---|
For C++ libraries and other cases where the tracking of the symbols is problematic, follow 8.6.4 The shlibs system of the “Debian Policy Manual”, instead. Please make sure to erase the empty debian/binarypackage.symbols file generated by the debmake command. For this case, the DEBIAN/shlibs file is used. |
When you package a new library package version which affects other packages, you must file a transition bug report against the release.debian.org pseudo package using the reportbug command with the ben file and wait for the approval for its upload from the Release Team.
Release team has the transition tracker. See Transitions.
![]() |
小心 |
---|---|
Please make sure to rename binary packages as 第 5.5.1.3 节 “The library package name”. |
The multiarch support for cross-architecture installation of binary packages (particularly i386 and amd64, but also other combinations) in the dpkg and apt packages introduced to Debian wheezy (7.0, May 2013) demands us to pay extra attention for the packaging.
You should read the following references in detail.
Ubuntu wiki (upstream)
Debian wiki (Debian situation)
The multiarch is enabled by using the <triplet> value such as i386-linux-gnu and x86_64-linux-gnu in the install path of shared libraries as /usr/lib/<triplet>/, etc..
The <triplet> value used in override_dh_* target scripts must be explicitly set in the debian/rules by the maintainer. The <triplet> value is stored in $(DEB_HOST_MULTIARCH) variable in the following debian/rules snippet example:
DEB_HOST_MULTIARCH = $(shell dpkg-architecture -qDEB_HOST_MULTIARCH) ... override_dh_install: mkdir -p package1/lib/$(DEB_HOST_MULTIARCH) cp -dR tmp/lib/. package1/lib/$(DEB_HOST_MULTIARCH)
See:
Debian policy requires to follow Filesystem Hierarchy Standard. Its /usr/lib : Libraries for programming and packages states "/usr/lib includes object files, libraries, and internal binaries that are not intended to be executed directly by users or shell scripts."
Debian policy makes an exception to Filesystem Hierarchy Standard to use /usr/lib/<triplet>/ instead of /usr/lib<qual>/ (e.g., /lib32/ and /lib64/) to support the multiarch library.
表 5.1. The multiarch library path options
Classic path | i386 多体系结构路径 | amd64 多体系结构路径 |
---|---|---|
/lib/ |
/lib/i386-linux-gnu/ |
/lib/x86_64-linux-gnu/ |
/usr/lib/ |
/usr/lib/i386-linux-gnu/ |
/usr/lib/x86_64-linux-gnu/ |
For Autotools based packages under the debhelper package (compat>=9), this path setting is automatically taken care by the dh_auto_configure command.
For other packages with non-supported build systems, you need to manually adjust the install path as follows.
All files installed simultaneously as the multiarch package to the same file path should have exactly the same file content. You must be careful on differences generated by the data byte order and by the compression algorithm.
![]() |
注意 |
---|---|
The --libexecdir option of the ./configure command specifies the default path to install executable programs run by other programs rather than by users. Its Autotools default is /usr/libexec/ but its Debian non-multi-arch default is /usr/lib/. If such executables are a part of a "Multi-arch: foreign" package, path such as /usr/lib/ or /usr/lib/packagename may be more desirable than /usr/lib/<triplet>/ which dh_auto_configure uses. The GNU Coding Standards: 7.2.5 Variables for Installation Directories has description for libexecdir as "The definition of libexecdir is the same for all packages, so you should install your data in a subdirectory thereof. Most packages install their data under $(libexecdir)/package-name/ …". (It is always good idea to follow GNU unless it conflicts with the Debian policy) |
The shared library files in the default path /usr/lib/ and /usr/lib/<triplet>/ are loaded automatically.
For the shared library files in the other path, GCC option -l must be set by the pkg-config command to make them loaded properly.
GCC includes both /usr/include/ and /usr/include/<triplet>/ by default on the multiarch Debian system.
If the header file is not in those paths, GCC option -I must be set by the pkg-config command to make "#include <foo.h>" work properly.
表 5.2. The multiarch header file path options
Classic path | i386 多体系结构路径 | amd64 多体系结构路径 |
---|---|---|
/usr/include/ |
/usr/include/i386-linux-gnu/ |
/usr/include/x86_64-linux-gnu/ |
/usr/include/ packagename / |
/usr/include/i386-linux-gnu/ packagename / |
/usr/include/x86_64-linux-gnu/ packagename / |
/usr/lib/i386-linux-gnu/ packagename / |
/usr/lib/x86_64-linux-gnu/ packagename / |
The use if the /usr/lib/<triplet>/packagename/ path for the header files allows the upstream to use the same install script for the multiatch system with /usr/lib/<triplet> and the biarch system with /usr/lib<qual>/. [16]
The use of the file path containing packagename enables to have more than 2 development libraries simultaneously installed on a system.
The pkg-config program is used to retrieve information about installed libraries in the system. It stores its configuration parameters in the *.pc file and is used for setting the -I and -l options for GCC.
表 5.3. The *.pc file path options
Classic path | i386 多体系结构路径 | amd64 多体系结构路径 |
---|---|---|
/usr/lib/pkgconfig/ |
/usr/lib/i386-linux-gnu/pkgconfig/ |
/usr/lib/x86_64-linux-gnu/pkgconfig/ |
The compiler hardening support spreading for Debian jessie (8.0, TBA) demands us to pay extra attention for the packaging.
You should read the following references in detail.
The debmake command adds template comments to the debian/rules file as needed for DEB_BUILD_MAINT_OPTIONS, DEB_CFLAGS_MAINT_APPEND, and DEB_LDFLAGS_MAINT_APPEND (see 第 4 章 简单例子 and dpkg-buildflags(1)).
The debconf package enables us to configure packages during their installation in 2 main ways:
interactively from the menu interface (dialog, gnome, kde, …)
All user interactions for the package installation must be handled by this debconf system using the following files.
debian/binarypackage.cofig
debian/binarypackage.template
package configuration scripts
See dh_installdebconf(1), debconf(7), debconf-devel(7) and 3.9.1 Prompting in maintainer scripts of the “Debian Policy Manual”.
DEP-8 defines the debian/tests/control file as the RFC822-style test metadata file for the continuous integration (CI) of the Debian package.
It is used after building the binary packages from the source package containing this debian/tests/control file. When the adt-run command provided by the autopkgtest package is run, the generated binary packages are installed and tested in the virtual environment according to this file.
See documents in the /usr/share/doc/autopkgtest/ directory and 3. autopkgtest: Automatic testing for packages of the “Ubuntu Packaging Guide”.
There are several other CI tools on Debian for you to explore.
Debian cares about supporting new ports or flavours. The new ports or flavours require bootstrapping operation for the cross-build of initial minimal native-building system. In order to avoid build-dependency loops during bootstrapping, the build-dependency needs to be reduced using the profile builds feature.
![]() |
提示 |
---|---|
If a core package |
The reportbug command used for the bug report of binarypackage can be customized by the files in usr/share/bug/binarypackage/.
The dh_bugfiles command installs these files from the template files in the debian/ directory.
debian/binarypackage.bug-control → usr/share/bug/binarypackage/control
debian/binarypackage.bug-presubj → usr/share/bug/binarypackage/presubj
debian/binarypackage.bug-script → usr/share/bug/binarypackage or usr/share/bug/binarypackage/script
See dh_bugfiles(1) and reportbug’s Features for Developers
![]() |
提示 |
---|---|
If you always remind something to the bug reporter or ask them about their situation, use these to automate it. |
[9] 对九成以上的软件包来说,软件包名称都不会超过 24 个字符;上游版本号通常不超过 10 个字符,而 Debian 修订版本号也通常不超过 3 个字符。
[10] 这个简化形式在 debhelper 软件包第七版或更新的版本中可用。本指导内容假设您在使用 debhelper 第九版或更新的版本。
[11] debmake 命令会产生稍微复杂一些的 debian/rules 文件。虽然如此,其核心结构没有什么变化。
[12] If you are using the vim editor, make sure to save this with the “:wq” command.
[13] The licensecheck command from the devscripts package was referenced to make this internal checker. Now the licensecheck command is provided in an independent licensecheck package with a lot of improvements.
[14] This document was written before the introduction of the symbols file.
[15] The strong preference to use the SONAME versioned -dev package names over the single -dev package name in its Chapter 6. Development (-DEV) packages does not seem to be shared by the former ftp-master (Steve Langasek). This document was written before the introduction of the multiarch system and the symbols file.
[16] This path is compliant to the FHS. Filesystem Hierarchy Standard: /usr/lib : Libraries for programming and packages states "Applications may use a single subdirectory under /usr/lib. If an application uses a subdirectory, all architecture-dependent data exclusively used by the application must be placed within that subdirectory."